Document command output structure

[christophermaier]

Commands can return JSON objects, but to enable the efficient construction of pipelines, users should be able to quickly determine the structure of those objects, so they can know exactly how to extract the data they care about.

A first pass at this could be providing an OUTPUT section in the structured documentation. Having some way to actually ensure that the documented output is the same as the generated output would be ideal, but that's likely a bigger task.

Related: #948

[vanstee]

@christophermaier Do you think a freeform text attribute named output for each command would be good enough here.

[christophermaier]

@vanstee I think that'll be good for a first pass. If we ever get some kind of automated verification wired up (still not sure how we'd accomplish that, though), then having it be something like JSON Schema would make sense, but absent that, I don't think we gain anything by imposing any more structure than "arbitrary text".

TL;DR - 👍

[vanstee]

Cool. Yeah, agreed that a JSON schema would be interesting eventually.

[christophermaier]

@vanstee That being said, if it's possible to easily permit the value to be text or a map, then users could have a bit of flexibility in how they choose to describe things.

[christophermaier]

Capturing some out-of-band discussion on this: we're just going to stick with plain text for now, since commands can dynamically change the structure they return based on arbitrary criteria. It'll be easier for now to explain "the output looks like this if you call a command this way, but like that if you call it that way" with text.