|
125 | 125 | </t> |
126 | 126 | </section> |
127 | 127 |
|
128 | | - <section title="Overview"> |
| 128 | + <!-- JSON Schema is designed for two broad use cases, which should each get their own section. --> |
| 129 | + <section title="Validation"> |
129 | 130 | <t> |
130 | | - This document proposes a new media type "application/schema+json" to identify a JSON |
131 | | - Schema for describing JSON data. |
132 | | - It also proposes a further optional media type, "application/schema-instance+json", |
133 | | - to provide additional integration features. |
134 | | - JSON Schemas are themselves JSON documents. |
135 | | - This, and related specifications, define keywords allowing authors to describe JSON |
136 | | - data in several ways. |
| 131 | + A JSON Schema is a document that describes a validator (also known as a "recognizer" or "acceptor") which classifies a provided JSON document as "accepted" or "rejected." |
| 132 | + It supports "structural validation" (context-free grammars), and certain more complicated conditions. |
| 133 | + Validation follows JSON semantics, so two documents that are value-equal, but vary only by character escapes, property ordering, or whitespace, will validate with the same result. |
137 | 134 | </t> |
138 | 135 | <t> |
139 | | - JSON Schema uses keywords to assert constraints on JSON instances or annotate those |
140 | | - instances with additional information. Additional keywords are used to apply |
141 | | - assertions and annotations to more complex JSON data structures, or based on |
142 | | - some sort of condition. |
| 136 | + With respect to a given schema, an input document accepted by that schema is called an "instance." |
| 137 | + A JSON Schema may be used to specify sets of JSON documents, by referring to the set of all possible instances of that schema. |
143 | 138 | </t> |
144 | 139 | <t> |
145 | | - To facilitate re-use, keywords can be organized into vocabularies. A vocabulary |
146 | | - consists of a list of keywords, together with their syntax and semantics. |
147 | | - A dialect is defined as a set of vocabularies and their required support |
148 | | - identified in a meta-schema. |
| 140 | + A condition for accepting a document is called an "assertion". |
| 141 | + Assertions add constraints that instances must conform to. |
| 142 | + Given a schema and an instance, the schema "accepts" an input whenever all the assertions are met, |
| 143 | + and the schema "rejects" when any of the assertions fail. |
| 144 | + Schemas without any assertions accept all JSON documents. |
149 | 145 | </t> |
150 | 146 | <t> |
151 | | - JSON Schema can be extended either by defining additional vocabularies, |
152 | | - or less formally by defining additional keywords outside of any vocabulary. |
153 | | - Unrecognized individual keywords simply have their values collected as annotations, |
154 | | - while the behavior with respect to an unrecognized vocabulary can be controlled |
155 | | - when declaring which vocabularies are in use. |
| 147 | + Assertions are encoded into a JSON Schema using "keywords," described below. |
156 | 148 | </t> |
| 149 | + </section> |
| 150 | + |
| 151 | + <section title="Annotation"> |
157 | 152 | <t> |
158 | | - This document defines a core vocabulary that MUST be supported by any |
159 | | - implementation, and cannot be disabled. Its keywords are each prefixed |
160 | | - with a "$" character to emphasize their required nature. This vocabulary |
161 | | - is essential to the functioning of the "application/schema+json" media |
162 | | - type, and is used to bootstrap the loading of other vocabularies. |
| 153 | + A JSON Schema may also describe an "annotator", a way to read an instance and return a set of "annotations." |
| 154 | + Annotations can be any output metadata about that instance. |
163 | 155 | </t> |
164 | 156 | <t> |
165 | | - Additionally, this document defines a RECOMMENDED vocabulary of keywords |
166 | | - for applying subschemas conditionally, and for applying subschemas to |
167 | | - the contents of objects and arrays. Either this vocabulary or one very |
168 | | - much like it is required to write schemas for non-trivial JSON instances, |
169 | | - whether those schemas are intended for assertion validation, annotation, |
170 | | - or both. While not part of the required core vocabulary, for maximum |
171 | | - interoperability this additional vocabulary is included in this document |
172 | | - and its use is strongly encouraged. |
| 157 | + For example, you can document the meaning of a property, |
| 158 | + suggest a default value for new instances, |
| 159 | + generate a list of hyperlinks from the instance, |
| 160 | + or declare relationships between data. |
| 161 | + Applications may make use of annotations to query for arbitrary information; |
| 162 | + for example, to extract a list of names from a document with a known structure. |
| 163 | + Annotations may also describe values within the instance in a standard way; |
| 164 | + for example, extracting a common type of hyperlink from many different types of documents, using a different schema for type. |
173 | 165 | </t> |
174 | 166 | <t> |
175 | | - Further vocabularies for purposes such as structural validation or |
176 | | - hypermedia annotation are defined in other documents. These other |
177 | | - documents each define a dialect collecting the standard sets of |
178 | | - vocabularies needed to write schemas for that document's purpose. |
| 167 | + Like assertions, the instructions for producing annotations are encoded in a schema using keywords. |
| 168 | + Output of annotations is only defined over valid instances, |
| 169 | + so annotations are not returned until the input has been validated. |
| 170 | + However, not all valid input is meaningful or true to a given application. |
| 171 | + That is, if you process an arbitrary instance with nonsense data, |
| 172 | + the resulting annotations may not necessarily be true, even though the input is valid. |
179 | 173 | </t> |
180 | 174 | </section> |
181 | 175 |
|
|
394 | 388 | </t> |
395 | 389 | </section> |
396 | 390 | <section title="Schema Vocabularies"> |
| 391 | + <t> |
| 392 | + To facilitate re-use, keywords can be organized into vocabularies. A vocabulary |
| 393 | + consists of a list of keywords, together with their syntax and semantics. |
| 394 | + A dialect is defined as a set of vocabularies and their required support |
| 395 | + identified in a meta-schema. |
| 396 | + </t> |
| 397 | + <t> |
| 398 | + JSON Schema can be extended either by defining additional vocabularies, |
| 399 | + or less formally by defining additional keywords outside of any vocabulary. |
| 400 | + Unrecognized individual keywords simply have their values collected as annotations, |
| 401 | + while the behavior with respect to an unrecognized vocabulary can be controlled |
| 402 | + when declaring which vocabularies are in use. |
| 403 | + </t> |
| 404 | + <t> |
| 405 | + This document defines a core vocabulary that MUST be supported by any |
| 406 | + implementation, and cannot be disabled. Its keywords are each prefixed |
| 407 | + with a "$" character to emphasize their required nature. This vocabulary |
| 408 | + is essential to the functioning of the "application/schema+json" media |
| 409 | + type, and is used to bootstrap the loading of other vocabularies. |
| 410 | + </t> |
| 411 | + <t> |
| 412 | + Additionally, this document defines a RECOMMENDED vocabulary of keywords |
| 413 | + for applying subschemas conditionally, and for applying subschemas to |
| 414 | + the contents of objects and arrays. Either this vocabulary or one very |
| 415 | + much like it is required to write schemas for non-trivial JSON instances, |
| 416 | + whether those schemas are intended for assertion validation, annotation, |
| 417 | + or both. While not part of the required core vocabulary, for maximum |
| 418 | + interoperability this additional vocabulary is included in this document |
| 419 | + and its use is strongly encouraged. |
| 420 | + </t> |
| 421 | + <t> |
| 422 | + Further vocabularies for purposes such as structural validation or |
| 423 | + hypermedia annotation are defined in other documents. These other |
| 424 | + documents each define a dialect collecting the standard sets of |
| 425 | + vocabularies needed to write schemas for that document's purpose. |
| 426 | + </t> |
397 | 427 | <t> |
398 | 428 | A schema vocabulary, or simply a vocabulary, is a set of keywords, |
399 | 429 | their syntax, and their semantics. A vocabulary is generally organized |
|
0 commit comments