Restructure vocabulary-related sections #772
Conversation
Attempt to make this more understandable by removing some duplication, putting things in the right order, and explaning certain things more clearly. Hopefully.
handrews
requested review from
philsturgeon,
awwright,
Relequestual and
gregsdennis
jsonschema-core.xml
Outdated
| <t> | ||
| Meta-schema authoring is an advanced usage of JSON Schema, so the design of | ||
| meta-schema features emphasizes flexibility over simplicity. | ||
| how to interpret a schema. Every schema has a meta-schema, typically identified |
There was a problem hiding this comment.
Every schema has a meta-schema.
Later you say "If absent from the root schema, the resulting behavior is implementation-defined." I realize they don't technically conflict, but it might be nice to have something to the effect of "even if it's not explicitly defined by the $schema keyword" rather that the casual "typically defined by..."
It might also be good to say something about having a convention that the meta-schema's $id is defined by the associated vocabulary.
jsonschema-core.xml
Outdated
| <t> | ||
| A schema vocabulary, or simply a vocabulary, is a set of keywords, | ||
| their syntax, and their semantics. A vocabulary is generally organized | ||
| around a particular purpose. Different uses of JSON Schema will |
There was a problem hiding this comment.
could we add examples here? Validation, UI generation, etc.
| Vocabularies are the primary unit of re-use in JSON Schema, as schema | ||
| authors can indicate what vocabularies are required or optional in | ||
| order to process the schema. While keywords can be supported outside | ||
| of any vocabulary, there is no analogous mechanism to indicate individual |
There was a problem hiding this comment.
While arbitrary extra keywords are allowed in JSON Schema, vocabularies are how we can define their meaning in a portable way, which other tooling can then start to support.
Or something.
|
@philsturgeon @gregsdennis I made some updates based on your feedback. How is this? |
|
Since @philsturgeon said nothing was blocking and I need to post a PR that builds on this I'm going to go ahead and merge with @gregsdennis's approval. Phil, let me know if I messed anything up and I'll fix it in the next PR. |
gregsdennis
added
clarification
Attempt to make this more understandable by removing
some duplication, putting things in the right order,
and explaning certain things more clearly. Hopefully.
It might be easier to just download and build this to review.