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