Define "vocabularies" better

[handrews]

There's always been some notion of a "vocabulary" to JSON Schema, but it's become more an more prominent. As @awwright just observed in PR #461, we never really define what that means properly in a way that it could be readily understood as used in that abstract.

We should do that, and/or reword the abstract so that it is more self-contained.

[awwright]

Thanks for opening this.

The line currently reads

JSON Schema is a JSON-based format for describing JSON data using various vocabularies.=

I was thinking something like

JSON Schema is a JSON-based format for describing JSON data. JSON Schemas can written in one of several vocabularies, for extensibility.

[Anthropic]

@handrews @awwright is it worth a high level mention of how vocabularies are connected and share keywords and/or ignore them in this summation? Expand on for extensibility just a little more.

[handrews]

@awwright @Anthropic looking first at the core spec, aside from the suitably vague mention in the Introduction (which I think is fine as-is), the next mention is in the Data Model:

Whitespace and formatting concerns, including different lexical representations of numbers that are equal within the data model, are thus outside the scope of JSON Schema. JSON Schema vocabularies that wish to work with such differences in lexical representations SHOULD define keywords to precisely interpret formatted strings within the data model rather than relying on having the original JSON representation Unicode characters available.

That's definitely lacking in context.

Then, in the JSON Schema Documents section, we have:

JSON Schema vocabularies can include assertions, which return a boolean result when applied to an instance.

which still assumes that you know what a "JSON Schema vocabulary" is.

I think what we should do is expand §4.3 and organize it into an intro and 3 subsections (instead of an intro and 1 subsection as it is now). The reference in the Data Model section can become a forward xref, as you don't really need to understand it precisely to make sense of that section.

§4.3 JSON Schema Documents would keep the existing first paragraph as an introduction

§4.3.1 JSON Schema Values and Keywords (or something like that) would have most of the remaining existing §4.3 intro content, except for the meta-schema paragraph. It would be reworded somewhat to remove or minimize the use of the word "vocabulary"

§4.3.2 JSON Schema Vocabularies would define what a vocabulary is and how the different types of keywords fit together, and define meta-schemas. It would say something about extensibility, as I agree with @awwright that that's missing from the mention on the Hyper-Schema spec.

§4.3.3 Root Schemas and Subschemas would be identical to the current §4.3.1 of the same name.

Additionally, some key information, including the extensibility motivation, needs to be moved up to the core spec's abstract. At that point, I think the existing Hyper-Schema abstract wording would be fine. We can reasonably expect a reader of the Hyper-Schema abstract, even in isolation away from the full spec, to have access to and read the Core abstract. Which would tell them that they need to read Core in full to properly understand what a "vocabulary" is.

How does that sound?

[handrews]

Merged #488, please file new issues with further feedback.