|
135 | 135 | data in several ways. |
136 | 136 | </t> |
137 | 137 | <t> |
138 | | - JSON Schema uses keywords to assert constraints on JSON instances or annotate those |
139 | | - instances with additional information. Additional keywords are used to apply |
140 | | - assertions and annotations to more complex JSON data structures, or based on |
141 | | - some sort of condition. |
| 138 | + A JSON Schema document is comprised of a set of keywords, |
| 139 | + which are specified as properties in a JSON object. |
| 140 | + The name of the keyword is used as the property name, |
| 141 | + and any arguments to the keyword are provided as the value. |
| 142 | + Keywords can be classified by their functions. |
| 143 | + The most important classes are validation, annotation, and applicator keywords. |
142 | 144 | </t> |
143 | 145 | <t> |
144 | | - To facilitate re-use, keywords can be organized into vocabularies. A vocabulary |
| 146 | + "Validation keywords" form the basis of JSON Schema. |
| 147 | + Given a schema and an instance, the instance is "valid" if all of the keywords in |
| 148 | + the schema are valid against the instance. |
| 149 | + Validation keywords may be used to describe a set of JSON documents. |
| 150 | + Without any validation keywords, the set of all valid instances is the set of all valid JSON documents. |
| 151 | + Typically, adding validation keywords creates a subset. |
| 152 | + Keywords are typically defined to not be redundant with other keywords: |
| 153 | + For example, the "minimum" keyword only shrinks the valid set of numbers, but not strings or other |
| 154 | + types—this is what the "type" keyword does. |
| 155 | + </t> |
| 156 | + <t> |
| 157 | + When an instance validates against a schema, "annotation keywords" may provide "annotations": |
| 158 | + metadata that describes the instance. |
| 159 | + For example, you can document the meaning of a property, |
| 160 | + suggest a default value for new instances, |
| 161 | + generate a list of hyperlinks from the instance, |
| 162 | + or declare relationships between data. |
| 163 | + </t> |
| 164 | + <t> |
| 165 | + "Applicator keywords" are keywords that accept a schema as part of their argument, |
| 166 | + which is applied to the instance in some fashion. |
| 167 | + Applicator keywords may use or modify the validation result of their sub-schemas, |
| 168 | + for example, to be valid conditional on which sub-schemas are valid |
| 169 | + (e.g. the "if", "then", "oneOf", or "anyOf" keywords). |
| 170 | + They may also validate a schema against values within the inststance, |
| 171 | + for example, a specific property within the object (the "properties" keyword). |
| 172 | + The "$ref" keyword is a special applicator keyword that takes a reference to a schema, |
| 173 | + instead of a literal schema. This allows schemas to be defined recursively. |
| 174 | + </t> |
| 175 | + <t> |
| 176 | + Applicator keywords typically also return the annotations from their valid schemas. |
| 177 | + Since only annotations from valid schemas can be returned, |
| 178 | + applicator keywords may be used to specify annotations that conditionally appear, |
| 179 | + depending on the validation result of other keywords. |
| 180 | + </t> |
| 181 | + <t> |
| 182 | + Since keywords are listed in an object by their name, they may be used at most once per schema and sub-schema. |
| 183 | + However, the effect of multiple keywords can be achieved by listing each keyword in a different sub-schema, |
| 184 | + inside an applicator keyword designed for this purpose, such as the "allOf" keyword. |
| 185 | + Additionally, many keywords can often be reduced to a single keyword; |
| 186 | + for example, when using "minimum", only the highest value of many will be effective. |
| 187 | + There are also schemas besides JSON objects: |
| 188 | + The booleans true/false represent a schema that's always valid/invalid, respectively. |
| 189 | + </t> |
| 190 | + <t> |
| 191 | + JSON Schema documents can themselves be described by a schema. |
| 192 | + In this context, this "schema of a schema" is called the meta-schema. |
| 193 | + In addition to a core vocabulary and a default validation vocabulary, |
| 194 | + JSON Schema supports some amount of customization by providing a custom meta-schema. |
| 195 | + </t> |
| 196 | + <t> |
| 197 | + To facilitate re-use, the meta-schema organizes keywords into vocabularies. A vocabulary |
145 | 198 | consists of a list of keywords, together with their syntax and semantics. |
146 | 199 | A dialect is defined as a set of vocabularies and their required support |
147 | 200 | identified in a meta-schema. |
|
0 commit comments