Make a real, appropriately short, Overview section #762
Conversation
The "Keyword Behavior" section is moved, completely unchanged, to immediately after the "General Considerations", where it makes quite a bit more sense. The "General Considerations" section gives a brief description of the keyword types, which makes a lot more sense before the detailed description rather than after it. The old "Schema Vocabularies" section has mostly been deleted, as it took up a lot of space without adding much. Given that the validation spec now contains four or five vocabularies, enumerating all of them plus hyper-schema (which is highly unlikely to reach RFC at the same time as core) seemed like an overlaod of non-essential information. The introductory paragraph is still useful, so it has been spliced into the appropriate location in the "Meta-Schemas and Vocabularies" section, and the reference anchor has been given to that section as well. The contents of that paragraph are also completely unchanged.
handrews
requested review from
philsturgeon,
awwright,
Relequestual and
gregsdennis
jsonschema-core.xml
Outdated
| consists of a list of keywords, together with their syntax and semantics. | ||
| </t> | ||
| <t> | ||
| JSON Schema can be extended either by adding vocabularies, or less formally |
There was a problem hiding this comment.
by adding vocabularies where?
..."when defining a new meta-schema,"
There was a problem hiding this comment.
I see your point here, although I think I have a better solution. "adding" makes it sound like there is some specific place to which to add the thing. I don't want to get into meta-schemas in this overview, so instead of "adding vocabularies" let's go with "defining new vocabularies" or "defining additional vocabularies". And likewise "defining new keywords" or "defining additional keywords" instead of "adding keywords."
BTW when I do the next clarifications I'll make it clear that the thing you do in a meta-schema is declare vocabularies, while defining vocabularies is (currently) done in specification text.
Make it more clear that extending involves defining more vocabularies and/or keywords, not adding existing vocabularies/keywords from some place to some other place.
gregsdennis
added
clarification
I think this dramatically improves the flow of the document. There is almost certainly more to do, but just having a concise overview and going from brief descriptions to detailed descriptions is a vast improvement.
The "Keyword Behavior" section is moved, completely unchanged,
to immediately after the "General Considerations", where
it makes quite a bit more sense. The "General Considerations"
section gives a brief description of the keyword types,
which makes a lot more sense before the detailed description
rather than after it.
The old "Schema Vocabularies" section has mostly been deleted,
as it took up a lot of space without adding much. Given that
the validation spec now contains four or five vocabularies,
enumerating all of them plus hyper-schema (which is highly
unlikely to reach RFC at the same time as core) seemed
like an overlaod of non-essential information.
The introductory paragraph is still useful, so it has been
spliced into the appropriate location in the
"Meta-Schemas and Vocabularies" section, and the reference
anchor has been given to that section as well. The contents
of that paragraph are also completely unchanged.