Best practice in writing JSON

Some best practices which we have adopted.

Guidelines

$schema should be the first entry inside a JSON file.
That should be "http://json-schema.org/draft-07/schema#" for a schema, or the relevant GGS file name for data files.
GGS schemas should be referred to by filename in the current directory, e.g. "./sw-pdfparams-schema.json", in $schema, $ref and patternProperties properties.

Schema files should include a $comment property claiming copyright, e.g:
"$comment": "Copyright (C) 2021 Global Graphics Software Ltd. All rights reserved."

$comment may be used elsewhere in GGS schemas to explain specific structures.

Do not use "#" properties in GGS schemas. Do not use "$comment" in data files.

All GGS schemas should include an $id property defining an absolute URL, e.g.:
"$id": "http://globalgraphics.com/schemas/sw-pdfparams-schema.json"

All GGS schemas should include a description property briefly describing what this schema is for, e.g.:
"description": "JSON schema for pdfparams",

GGS schemas should include a patternProperties entry unless adding "#..." keys would cause problems downstream, i.e.:
"patternProperties": { "^#[0-9]*$": { "$ref": "./sw-comment-schema.json#" } },

This patternProperties for comments should also be included in any object types, as should requiredProperties and additionalProperties.

Taken together, a schema will start something like this:

JS

"$schema": "http://json-schema.org/draft-07/schema#",
"$comment": "Copyright (C) 2021 Global Graphics Software Ltd. All rights reserved.",


"$id": "http://globalgraphics.com/schemas/sw-files-schema.json",
"description": "JSON schema for file installation and deletion",

"type": "object",
"required": [],
"additionalProperties": false,
"patternProperties": { "^#[0-9]*$": { "$ref": "./sw-comment-schema.json#" } },

Schema validation is improved if additionalProperties can be set to false, as then misspelt and misplaced keys will be highlighted.

FAQ

Does the JSON conversion code delete all #.. properties?

Answer: Yes

What PostScript properties should not be included in the JSON schemas?

* read-only items (i.e. Unable to set them in PS, so why would we try in JSON!)
* deprecated items (for obvious reasons)
* items where we would prefer OEMs to use some other method ... let's use JSON as a lever to shift people over
* items that we have deliberately not documented.

Editing JSON tests in place using VS Code while getting schema validation without copying schema files

NOTE: In practice, while developing schemas and tests, it is generally easier to copy all the schemas into a directory next to your test in a directory named "schemas" so relative validation works and the test file is ready to commit without further modification.

When we edit JSON tests under SWcore_tests, we don't get schema validation "out of the box". You need to either copy the schema files relative to the test your editing (note above) or edit the test relative to where the schema files are. Either is not ideal and prone to further mistakes.

It looks like we can set up VS Code such that one can add & edit new test files directly in SWcore_tests/JSONconfig/Resource/TestConfig/JSONtests/<Category>/TestName.json (where ever that repo is cloned to) and get direct schema validation from the files in hqnrip/skintest/swf/testconf/JSON/schemas. i.e. All the files can remain in the location where they were added to the Mecurial source structure(s). I've yet to get this working but here are the instructions.

See: https://code.visualstudio.com/docs/languages/json

I managed to get what I wanted with this in settings.json:

JS

{
    "fileMatch": [
        "*.hqn.json"
    ],
    "url": "file:///C:/users/martinb/GGSource/hacks/JSON/stack/sw-config-schema.json"
}

That works as long as the file is named <whatever>.hqn.json and has no explicit $schema property in the root. Obviously, the path in your url would need to be different.