identify standard formatter for JSON so that comparisons can be made easily

[jbfaden]

There should be a single standard for formatting JSON documents committed here. It should be something we can all access, and something which could be run as a git commit hook.

I propose the linux command "json_pp" which:

• indents using 3-space indents
• alphabetizes tags in a json object
• each item of array has a separate line
• each tag of an object has a separate line
• each tag of an object has a space after the tag's name

Here is an example json_pp-formatted about schema:

{
   "$schema" : "http://json-schema.org/draft-07/schema#",
   "additionalProperties" : false,
   "definitions" : {
      "HAPI" : {
         "description" : "HAPI Version",
         "id" : "#/definitions/HAPI",
         "pattern" : "^3\\.1$",
         "type" : "string"
      },
      "HAPIStatus" : {
         "additionalProperties" : false,
         "description" : "Request status",
         "id" : "#/definitions/HAPIStatus",
         "patternProperties" : {
            "x_.*" : {}
         },
         "properties" : {
            "code" : {
               "description" : "HAPI request status code",
               "enum" : [
                  1200,
                  1201,
                  1400,
                  1401,
                  1402,
                  1403,
                  1404,
                  1405,
                  1406,
                  1407,
                  1408,
                  1409,
                  1410,
                  1411,
                  1412,
                  1500,
                  1501
               ],
               "type" : "integer"
            },
            "message" : {
               "description" : "HAPI request status message",
               "type" : "string"
            }
         },
         "required" : [
            "code",
            "message"
         ],
         "title" : "",
         "type" : "object"
      }
   },
   "description" : "Server /capabilities response",
   "patternProperties" : {
      "x_.*" : {}
   },
   "properties" : {
      "$schema" : {
         "description" : "schema declaration is sometimes found in response.",
         "type" : "string"
      },
      "HAPI" : {
         "$ref" : "#/definitions/HAPI"
      },
      "outputFormats" : {
         "additionalItems" : true,
         "description" : "Output formats, which must include csv.",
         "items" : {
            "enum" : [
               "csv",
               "binary",
               "json"
            ],
            "type" : "string"
         },
         "minItems" : 1,
         "type" : "array",
         "uniqueItems" : true
      },
      "status" : {
         "$ref" : "#/definitions/HAPIStatus"
      }
   },
   "required" : [
      "HAPI",
      "outputFormats",
      "status"
   ],
   "title" : "capabilities",
   "type" : "object"
}

[jbfaden]

In our meeting today, we resolved that json_pp is not acceptable because it sorts the tags in the objects. Instead we should preserve the order which Bob had when formatting objects. I'd like to compare this to the order they appear in the specification document, and if it's close I think we should use its order. I will write a pretty printer which will be consistent with whitespace choices used in JSON.stringify in Python and Javascript. (We also need to see if Python and JS implementations are consistent with one another.)

[rweigel]

The Javascript one is the written: https://github.com/hapi-server/data-specification-schema/blob/main/util/reformat.js and I put a note about it in the README: https://github.com/hapi-server/data-specification-schema

I agree about matching order in docs. Ideally, we would build the documentation tables in the spec from the schema so that the order is guaranteed to be correct. At present, we have descriptions of the nodes in the schema and also a description in the spec. Really they should be the same.

[jbfaden]

I've confirmed that I can use node reformat.js with node. So the new spec will be:

• indents using 2-space indents
• json tag order should match the order which they are listed in the documentation
• each item of array has a separate line
• each tag of an object has a separate line
• each tag of an object does not have a space after the tag's name

[jbfaden]

I've been writing a code which will reformat my schemas as described. I could either back out my changes to before I ran json_pp on them, or I could write a reformatter and have it available in the future, so I decided to write one.

One thing I notice is in the spec we list all the required items then the optional ones, and I suspect we'll want to change the order somewhat. For example, description is optional but you would probably want it up near the top. I've made it so that in my code we will be able to change the order easily.

[jbfaden]

I notice that the Java library Gson formats JSON such that the spec I posted three hours ago is met.

[jbfaden]

Still a work in progress, this Java code will (eventually) take any HAPI output or schema and output to a known predictable order: https://github.com/jbfaden/hapi-json-sorter. https://github.com/jbfaden/hapi-json-sorter/blob/669a5f23a90c20a6f7adc6da0ff6cd55abd62c5e/src/hapitests/HapiJsonSorter.java#L77 is the routine which identifies the order for each type of node.

[rweigel]

Closing b/c issue has been addressed ("identify standard formatter for JSON" = reformat.js). If reformatters become available, put a note in the README.md.

[jbfaden]

Note reformat.js does not resort the tags of a map. My goal in this ticket was so that two json scripts, having any indentation or tag order, would be made the same in serial form if they are the same.