From 3e879a8530581eb53654c02d318a3540861fd5a0 Mon Sep 17 00:00:00 2001 From: Austin Wright Date: Tue, 14 Jun 2022 15:45:22 -0700 Subject: [PATCH] Expand the Overview section to put some context to vocabularies --- jsonschema-core.xml | 63 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 58 insertions(+), 5 deletions(-) diff --git a/jsonschema-core.xml b/jsonschema-core.xml index a8ca268f..1fd15e0f 100644 --- a/jsonschema-core.xml +++ b/jsonschema-core.xml @@ -136,13 +136,66 @@ data in several ways. - JSON Schema uses keywords to assert constraints on JSON instances or annotate those - instances with additional information. Additional keywords are used to apply - assertions and annotations to more complex JSON data structures, or based on - some sort of condition. + A JSON Schema document is comprised of a set of keywords, + which are specified as properties in a JSON object. + The name of the keyword is used as the property name, + and any arguments to the keyword are provided as the value. + Keywords can be classified by their functions. + The most important classes are assertion, annotation, and applicator keywords. - To facilitate re-use, keywords can be organized into vocabularies. A vocabulary + "Assertion keywords" form the basis of JSON Schema. + Given a schema and an instance, the instance is "valid" if all of the keywords in + the schema are valid against the instance. + Assertion keywords may be used to describe a set of JSON documents. + Without any assertion keywords, the set of all valid instances is the set of all valid JSON documents. + Typically, adding assertion keywords reduces the set of valid JSON documents. + Keywords are defined to not be redundant with other keywords: + For example, the "minimum" keyword only shrinks the valid set of numbers, but not strings or other + types—this is what the "type" keyword does. + + + When an instance validates against a schema, "annotation keywords" may provide "annotations": + metadata that describes the instance. + For example, you can document the meaning of a property, + suggest a default value for new instances, + generate a list of hyperlinks from the instance, + or declare relationships between data. + + + "Applicator keywords" are keywords that accept sub-schemas as part of their argument, + which are validated against the instance in some fashion. + Applicator keywords may use or modify the validation result of their sub-schemas, + for example, to be valid conditional on which sub-schemas are valid + (e.g. the "if", "then", "oneOf", or "anyOf" keywords). + They may also validate a schema against values within the instance, + for example, a specific property within the object (the "properties" keyword). + The "$ref" keyword is a special applicator keyword that takes a reference to a schema, + instead of a literal schema. This allows schemas to be defined recursively. + + + Applicator keywords typically also return the annotations from their valid schemas. + Since only annotations from valid schemas can be returned, + applicator keywords may be used to specify annotations that conditionally appear, + depending on the validation result of other keywords. + + + Since keywords are listed in an object by their name, + they may be used at most once per schema and sub-schema. + However, the effect of multiple keywords may be achieved by listing each keyword in its own sub-schema, + inside an applicator keyword designed for this purpose, such as the "allOf" keyword. + Additionally, many keywords can often be reduced to a single keyword; + for example, when using "minimum", only the highest value of many will be effective. + As a short form, the booleans true/false represent a schema that's always valid/invalid, respectively. + + + JSON Schema documents can themselves be described by a schema. + In this context, this "schema of the schema" is called the meta-schema. + In addition to a core vocabulary and a default validation vocabulary, + JSON Schema supports some amount of customization by providing a custom meta-schema. + + + To facilitate re-use, the meta-schema organizes keywords into vocabularies. A vocabulary consists of a list of keywords, together with their syntax and semantics. A dialect is defined as a set of vocabularies and their required support identified in a meta-schema.