Guidelines for extensible JSON

[roberth]

Is your feature request related to a problem? Please describe.

Commands with --json need to be future proof.

Describe the solution you'd like

We need JSON guidelines.

• The top level object must always be a record
• The value of a dictionary must always be a record
• List items should be records

Definitions

• dictionary: a map from names to things that all have the same type (C++ std::map)
• record: a fixed set of attributes each with their own type (C++ struct)

In case of streaming json (json lines, etc), the rules apply such that each value is regarded as a top level object.

Describe alternatives you've considered

Just break stuff.

Additional context

• nix describe-stores --json format is not extensible #7824

Priorities

Add 👍 to issues you find important.

[fricklerhandwerk]

Discussed in Nix team:

• @thufschmitt: shall the rule apply recursively, i.e. where the output is a list of things, whether the items shall also be records with named entries
  • @roberth: yes, added this to the proposal
• @fricklerhandwerk: where to put the outcome of this discussion?
  • @thufschmitt: should be part of the CLI guidelines
    • @edolstra: agreed, should go here
• agreement on proposal
  • @roberth will make a PR, @fricklerhandwerk will review

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-02-17-nix-team-meeting-minutes-33/25624/1

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-02-20-nix-team-meeting-minutes-34/25625/1