Discussion: machine-readable output

[ianmcorvidae]

Breaking this out into a new issue for discussion from a couple other spots.

We should establish a format and standard way of accessing machine-readable output, most likely JSON, and then implement it in the CLI. Once we have an initial standard, other output options such as tabular formats can be more easily defined relative to a JSON format.

My preferred format would diverge as little as possible from things as defined in the protobufs for the sake of easier forward compatibility; if a field gets added somewhere, updating the protocol buffer definitions should as often as possible be all that's needed.

I think that there's probably several good ways to go about this, and the decisions may be closely tied with any reorganization of the CLI. Broadly, I think we might have two options:

• a single format that's able to express anything relevant within the same structure, which different commands and options would populate different parts of (for read operations) or only read/consider specific parts of (for write/update operations)
• a number of somewhat more command-specific formats not intended to be directly merged with one another but instead relying on the context of the command

To me, the first of these would be more consistent but more challenging to define fully and less well-suited for streaming data, while the second would be a little easier to create and better-suited for streaming but require more work from users in making their scripts understand the context of the data.

I don't have any sort of exclusive claim on ideas and there could easily be good options I haven't thought of! So please share your thoughts if you're a user of the CLI or might want to be a user of machine-readable outputs from the CLI.

Previously: #475, #566

[holdenweb]

Sounds like we're looking for a generic "Protobuf to JSON" function. Let me think about that.

Ah, edit five minutes later: this stackoverlow answer implies that this functionality is already part of the protobuf package!

[ianmcorvidae]

Yeah -- it's more of a question of how to put the outputs of that together. We already use MessageToJson (and the related MessageToDict) a lot, but there isn't something in the protobufs that defines a completely top-level format like my first option above, and we'd need to decide which things to return where for the second option.

[holdenweb]

Each protobuf has a unique name, right? So how about a dict keyed by protobuf name, whose values were a list of zero or more dicts each representing a protobuf's contents. If the list associated with a key were empty then that key could be omitted.

There may be other data we wish to communicate. We can include that as (an)other key(s) in the same dict. Would that work?

[ianmcorvidae]

I think that's probably the thing to do, yeah -- other than probably lowercasing the protobuf names, as is more typical for JSON. I think I'd propose we use key names beginning with an underscore for anything we need to add beyond the protobufs. And I would propose we do no de-nesting of things so we don't need to do anything funny as far as references from one part of a document to another.

I'll plan to go through and make sure this can represent everything we'd want it to that's done in the current CLI (I suspect it does, but I think it's worth checking).

[holdenweb]

Rather than use _name for fields that don't occur in the protobuf, perhaps consider adding an "extras" key to contain them? This would seem to give rather better separation and avoid the two sets of data becoming intermingled, as well as avoid the leading underscores.

The main thing is keeping the format as pure JSON, allowing parsing by many packages in a multitude of languages without any special casing.

[holdenweb]

One final thought: if it's practical, the JSON output layer and any reporting interfaces should both be based on a common level that creates dicts. It would be tedious to have to convert the JSON back into a dict when it isn't really necessary.