|
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 defines 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), as well as some select, more complicated conditions. |
| 133 | + However validation always follows JSON semantics, so two documents that are value-equal, but vary only by indentation, whitespace, character escapes, and property ordering, 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, a 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 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 | + The conditions for accepting a document are specified as a list of "assertions" within the schema. |
| 141 | + Assertions add constraints that instances must conform to. |
| 142 | + Given a schema and an instance, the schema "accepts" an instance whenever all the assertions are met, |
| 143 | + and the schema "rejects" when any of the assertions fail. |
| 144 | + In a schema without any assertion keywords, all JSON documents are accepted. |
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 also defines an "annotator", which reads an instance and returns a set of "annotations", or metadata describing that instance. |
163 | 154 | </t> |
164 | 155 | <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. |
| 156 | + For example, you can document the meaning of a property, |
| 157 | + suggest a default value for new instances, |
| 158 | + generate a list of hyperlinks from the instance, |
| 159 | + or declare relationships between data. |
| 160 | + Applications may make use of annotations to query for arbitrary information; |
| 161 | + for example, to extract a list of names from a document with a known structure. |
| 162 | + Annotations may also describe values within the instance in a standard way; |
| 163 | + for example, extracting a common type of hyperlink from many different types of documents, using a different schema for type. |
173 | 164 | </t> |
174 | 165 | <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. |
| 166 | + Like assertions, the rules governing annotations are encoded into a JSON Schema using keywords. |
| 167 | + Annotations are only produced by schemas that first accept the instance. |
| 168 | + However, even though you can generate annotations from any instance, |
| 169 | + annotations may only be meaningful from instances first known by the application to be meaningful. |
| 170 | + That is, if you generate an arbitrary instance with nonsense data, |
| 171 | + the annotations will not necessarily be true, even though the instance is valid. |
| 172 | + Correctly applying the semantics of annotations is the responsibility of the application and schema author. |
179 | 173 | </t> |
180 | 174 | </section> |
181 | 175 |
|
|
384 | 378 | </t> |
385 | 379 | </section> |
386 | 380 | <section title="Schema Vocabularies"> |
| 381 | + <t> |
| 382 | + To facilitate re-use, keywords can be organized into vocabularies. A vocabulary |
| 383 | + consists of a list of keywords, together with their syntax and semantics. |
| 384 | + A dialect is defined as a set of vocabularies and their required support |
| 385 | + identified in a meta-schema. |
| 386 | + </t> |
| 387 | + <t> |
| 388 | + JSON Schema can be extended either by defining additional vocabularies, |
| 389 | + or less formally by defining additional keywords outside of any vocabulary. |
| 390 | + Unrecognized individual keywords simply have their values collected as annotations, |
| 391 | + while the behavior with respect to an unrecognized vocabulary can be controlled |
| 392 | + when declaring which vocabularies are in use. |
| 393 | + </t> |
| 394 | + <t> |
| 395 | + This document defines a core vocabulary that MUST be supported by any |
| 396 | + implementation, and cannot be disabled. Its keywords are each prefixed |
| 397 | + with a "$" character to emphasize their required nature. This vocabulary |
| 398 | + is essential to the functioning of the "application/schema+json" media |
| 399 | + type, and is used to bootstrap the loading of other vocabularies. |
| 400 | + </t> |
| 401 | + <t> |
| 402 | + Additionally, this document defines a RECOMMENDED vocabulary of keywords |
| 403 | + for applying subschemas conditionally, and for applying subschemas to |
| 404 | + the contents of objects and arrays. Either this vocabulary or one very |
| 405 | + much like it is required to write schemas for non-trivial JSON instances, |
| 406 | + whether those schemas are intended for assertion validation, annotation, |
| 407 | + or both. While not part of the required core vocabulary, for maximum |
| 408 | + interoperability this additional vocabulary is included in this document |
| 409 | + and its use is strongly encouraged. |
| 410 | + </t> |
| 411 | + <t> |
| 412 | + Further vocabularies for purposes such as structural validation or |
| 413 | + hypermedia annotation are defined in other documents. These other |
| 414 | + documents each define a dialect collecting the standard sets of |
| 415 | + vocabularies needed to write schemas for that document's purpose. |
| 416 | + </t> |
387 | 417 | <t> |
388 | 418 | A schema vocabulary, or simply a vocabulary, is a set of keywords, |
389 | 419 | their syntax, and their semantics. A vocabulary is generally organized |
|
0 commit comments