Add title and description annotations to JSON Schema elements

From https://json-schema.org/understanding-json-schema/reference/generic.html#annotations

JSON Schema includes a few keywords, title, description, default, examples that aren’t strictly used for validation, but are used to describe parts of a schema.

None of these “annotation” keywords are required, but they are encouraged for good practice, and can make your schema “self-documenting”.

The title and description keywords must be strings. A “title” will preferably be short, whereas a “description” will provide a more lengthy explanation about the purpose of the data described by the schema.

Currently, there is confusion over what certain variables in CSL JSON are supposed to containing. Setting title and description would be helpful in addressing this. Also it would allow for a single authoritative source of CSL JSON field documentation.

examples might also be helpful, but probably not as pressing:

New in draft 6 The examples keyword is a place to provide an array of examples that validate against the schema. This isn’t used for validation, but may help with explaining the effect and purpose of the schema to a reader. Each entry should validate against the schema in which is resides, but that isn’t strictly required. There is no need to duplicate the default value in the examples array, since default will be treated as another example.

However, the test suite could extract and test the examples, so examples could also help improve test coverage.

[dhimmel]

Do you have in mind a specific approach to this? What would a fragment look like?

Take for example:

https://github.com/citation-style-language/schema/blob/c194326df31e39b1eb3d48c0162f157af47147a6/csl-data.json#L64-L66

One could imagine the following documentation:

 "journalAbbreviation": { 
     "title": "Journal Abbreviation (deprecated)",
     "description": "Abbreviation for the journal name, ideally following the ISO 4 standard at https://www.iso.org/standard/3569.html. Use NLM Title Abbreviation when available. This field is deprecated, use container-title-short instead.",
     "type": "string",
     "examples": ["BMC Complement Med Ther", "Jt Dis Relat Surg"]
 }, 

Note that I don’t actually know anything about journalAbbreviation. So really you’d need someone who knows a bit more about CSL JSON usage and design to write this. I get the sense a lot of the meaning of fields has been established by practice, and is not centrally located anywhere.

But once these definitions are written, they can become the authoritative interpretations of these fields. @rmzelle do you know any places where many of these CSL JSON fields are documented?

[bdarcus]

I imagine we could post it alongside the documentation, on the main CSL site.