Add title and description annotations to JSON Schema elements

[dhimmel]

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.

[bdarcus]

Would it be possible/wise to have a single source for definitions, and then programmatically propagate them to the different places they need to be?

For example, the RNC schema should have annotations for everything, but they need to be in the documentation too, and also (per this issue) would be helpful in the json schemas.

For that matter, could we programmatically update the csl-data.json file from the RNC schema?

[bdarcus]

Well, now that I think about, I may be overstating how well the rnc schema is commented currently. We don't have annotations for the terms and such, which we should.

[dhimmel]

@bdarcus I'm not familiar with what the RNC schemas are used for and what their overlap is with the CSL Data schema. Ideally, we wouldn't be defining the same schema in two formats unless one is entirely auto-generated from the other.

What is the RNC schema used for in terms of CSL JSON Data?

[dhimmel]

I may be overstating how well the rnc schema is commented currently.

The RNC schema should be describing the XML used to specify a CSL Style. So if a title/definition concerns an element of an XML style, then we should put the description in the RNC. But if it primarily concerns CSL JSON Data, we should use the JSON Schema. Does that delineation make sense?

[bdarcus]

I'm just observing that in both the json and the csl, strings like variables and types are just lists, with slightly different syntax.

Because we maintain them in different places, you can imagine it's easy for them to get out of sync.

In any case, I agree adding annotations to the schema makes sense. Anything that can help developers is a good thing ;-)

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

[dhimmel]

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

Take for example:

schema/csl-data.json

Lines 64 to 66 in c194326

	"journalAbbreviation": {
	"type": "string"
	},

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 was looking around for tools that could take such a documented schema and output human-readable results.

There's these:

1. https://coveooss.github.io/json-schema-for-humans/
2. https://github.com/adobe/jsonschema2md

The latter, in particular, has some cool features, like optionally reformatting embedded examples as YAML, and here's what the former looks like with your recent example:

Any others?

[dhimmel]

Awesome! Either one would be incredibly helpful.

Where do we want to the deploy rendered output? I.e. which website / URL?

Hopefully we can automate deployment with GitHub actions.

[bdarcus]

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