idnits 2.17.1 draft-bhutton-json-schema-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 8 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 2836 has weird spacing: '...ragment https...' == Line 2843 has weird spacing: '...ragment https...' == Line 2853 has weird spacing: '...ragment https...' == Line 2863 has weird spacing: '...ragment https...' == Line 2876 has weird spacing: '...ragment https...' == (2 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: Vocabulary authors SHOULD provide a meta-schema that validates the expected usage of the vocabulary's keywords on their own. Such meta-schemas SHOULD not forbid additional keywords, and MUST not forbid any keywords from the Core vocabulary. -- The document date (December 8, 2020) is 1235 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'A-Za-z' is mentioned on line 1299, but not defined == Missing Reference: '0-9' is mentioned on line 1300, but not defined -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 10 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force A. Wright, Ed. 3 Internet-Draft 4 Intended status: Informational H. Andrews, Ed. 5 Expires: June 11, 2021 6 B. Hutton, Ed. 8 G. Dennis 9 December 8, 2020 11 JSON Schema: A Media Type for Describing JSON Documents 12 draft-bhutton-json-schema-00 14 Abstract 16 JSON Schema defines the media type "application/schema+json", a JSON- 17 based format for describing the structure of JSON data. JSON Schema 18 asserts what a JSON document must look like, ways to extract 19 information from it, and how to interact with it. The "application/ 20 schema-instance+json" media type provides additional feature-rich 21 integration with "application/schema+json" beyond what can be offered 22 for "application/json" documents. 24 Note to Readers 26 The issues list for this draft can be found at . 29 For additional information, see . 31 To provide feedback, use this issue tracker, the communication 32 methods listed on the homepage, or email the document editors. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on June 11, 2021. 50 Copyright Notice 52 Copyright (c) 2020 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 5 69 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 6 71 4.1. JSON Document . . . . . . . . . . . . . . . . . . . . . . 6 72 4.2. Instance . . . . . . . . . . . . . . . . . . . . . . . . 6 73 4.2.1. Instance Data Model . . . . . . . . . . . . . . . . . 6 74 4.2.2. Instance Equality . . . . . . . . . . . . . . . . . . 7 75 4.2.3. Non-JSON Instances . . . . . . . . . . . . . . . . . 8 76 4.3. JSON Schema Documents . . . . . . . . . . . . . . . . . . 8 77 4.3.1. JSON Schema Objects and Keywords . . . . . . . . . . 8 78 4.3.2. Boolean JSON Schemas . . . . . . . . . . . . . . . . 9 79 4.3.3. Schema Vocabularies . . . . . . . . . . . . . . . . . 10 80 4.3.4. Meta-Schemas . . . . . . . . . . . . . . . . . . . . 10 81 4.3.5. Root Schema and Subschemas and Resources . . . . . . 10 82 5. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . 11 83 6. General Considerations . . . . . . . . . . . . . . . . . . . 12 84 6.1. Range of JSON Values . . . . . . . . . . . . . . . . . . 12 85 6.2. Programming Language Independence . . . . . . . . . . . . 12 86 6.3. Mathematical Integers . . . . . . . . . . . . . . . . . . 12 87 6.4. Regular Expressions . . . . . . . . . . . . . . . . . . . 12 88 6.5. Extending JSON Schema . . . . . . . . . . . . . . . . . . 13 89 7. Keyword Behaviors . . . . . . . . . . . . . . . . . . . . . . 13 90 7.1. Lexical Scope and Dynamic Scope . . . . . . . . . . . . . 14 91 7.2. Keyword Interactions . . . . . . . . . . . . . . . . . . 15 92 7.3. Default Behaviors . . . . . . . . . . . . . . . . . . . . 15 93 7.4. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16 94 7.5. Applicators . . . . . . . . . . . . . . . . . . . . . . . 16 95 7.5.1. Referenced and Referencing Schemas . . . . . . . . . 17 97 7.6. Assertions . . . . . . . . . . . . . . . . . . . . . . . 17 98 7.6.1. Assertions and Instance Primitive Types . . . . . . . 17 99 7.7. Annotations . . . . . . . . . . . . . . . . . . . . . . . 18 100 7.7.1. Collecting Annotations . . . . . . . . . . . . . . . 19 101 7.8. Reserved Locations . . . . . . . . . . . . . . . . . . . 22 102 7.9. Loading Instance Data . . . . . . . . . . . . . . . . . . 22 103 8. The JSON Schema Core Vocabulary . . . . . . . . . . . . . . . 23 104 8.1. Meta-Schemas and Vocabularies . . . . . . . . . . . . . . 24 105 8.1.1. The "$schema" Keyword . . . . . . . . . . . . . . . . 24 106 8.1.2. The "$vocabulary" Keyword . . . . . . . . . . . . . . 25 107 8.1.3. Updates to Meta-Schema and Vocabulary URIs . . . . . 27 108 8.2. Base URI, Anchors, and Dereferencing . . . . . . . . . . 27 109 8.2.1. The "$id" Keyword . . . . . . . . . . . . . . . . . . 27 110 8.2.2. Defining location-independent identifiers . . . . . . 28 111 8.2.3. Schema References . . . . . . . . . . . . . . . . . . 29 112 8.2.4. Schema Re-Use With "$defs" . . . . . . . . . . . . . 30 113 8.3. Comments With "$comment" . . . . . . . . . . . . . . . . 31 114 9. Loading and Processing Schemas . . . . . . . . . . . . . . . 31 115 9.1. Loading a Schema . . . . . . . . . . . . . . . . . . . . 32 116 9.1.1. Initial Base URI . . . . . . . . . . . . . . . . . . 32 117 9.1.2. Loading a referenced schema . . . . . . . . . . . . . 32 118 9.1.3. Detecting a Meta-Schema . . . . . . . . . . . . . . . 33 119 9.2. Dereferencing . . . . . . . . . . . . . . . . . . . . . . 33 120 9.2.1. JSON Pointer fragments and embedded schema resources 34 121 9.3. Compound Documents . . . . . . . . . . . . . . . . . . . 36 122 9.3.1. Bundling . . . . . . . . . . . . . . . . . . . . . . 36 123 9.3.2. Differing and Default Dialects . . . . . . . . . . . 37 124 9.3.3. Validating . . . . . . . . . . . . . . . . . . . . . 37 125 9.4. Caveats . . . . . . . . . . . . . . . . . . . . . . . . . 38 126 9.4.1. Guarding Against Infinite Recursion . . . . . . . . . 38 127 9.4.2. References to Possible Non-Schemas . . . . . . . . . 38 128 9.5. Associating Instances and Schemas . . . . . . . . . . . . 39 129 9.5.1. Usage for Hypermedia . . . . . . . . . . . . . . . . 39 130 10. A Vocabulary for Applying Subschemas . . . . . . . . . . . . 40 131 10.1. Keyword Independence . . . . . . . . . . . . . . . . . . 40 132 10.2. Keywords for Applying Subschemas in Place . . . . . . . 40 133 10.2.1. Keywords for Applying Subschemas With Logic . . . . 41 134 10.2.2. Keywords for Applying Subschemas Conditionally . . . 42 135 10.3. Keywords for Applying Subschemas to Child Instances . . 43 136 10.3.1. Keywords for Applying Subschemas to Arrays . . . . . 43 137 10.3.2. Keywords for Applying Subschemas to Objects . . . . 45 138 11. A Vocabulary for Unevaluated Locations . . . . . . . . . . . 46 139 11.1. Keyword Independence . . . . . . . . . . . . . . . . . . 47 140 11.2. unevaluatedItems . . . . . . . . . . . . . . . . . . . . 48 141 11.3. unevaluatedProperties . . . . . . . . . . . . . . . . . 48 142 12. Output Formatting . . . . . . . . . . . . . . . . . . . . . . 49 143 12.1. Format . . . . . . . . . . . . . . . . . . . . . . . . . 49 144 12.2. Output Formats . . . . . . . . . . . . . . . . . . . . . 49 145 12.3. Minimum Information . . . . . . . . . . . . . . . . . . 50 146 12.3.1. Keyword Relative Location . . . . . . . . . . . . . 50 147 12.3.2. Keyword Absolute Location . . . . . . . . . . . . . 50 148 12.3.3. Instance Location . . . . . . . . . . . . . . . . . 51 149 12.3.4. Error or Annotation . . . . . . . . . . . . . . . . 51 150 12.3.5. Nested Results . . . . . . . . . . . . . . . . . . . 51 151 12.4. Output Structure . . . . . . . . . . . . . . . . . . . . 52 152 12.4.1. Flag . . . . . . . . . . . . . . . . . . . . . . . . 54 153 12.4.2. Basic . . . . . . . . . . . . . . . . . . . . . . . 54 154 12.4.3. Detailed . . . . . . . . . . . . . . . . . . . . . . 55 155 12.4.4. Verbose . . . . . . . . . . . . . . . . . . . . . . 57 156 12.4.5. Output validation schemas . . . . . . . . . . . . . 59 157 13. Security Considerations . . . . . . . . . . . . . . . . . . . 59 158 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 159 14.1. application/schema+json . . . . . . . . . . . . . . . . 60 160 14.2. application/schema-instance+json . . . . . . . . . . . . 60 161 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 61 162 15.1. Normative References . . . . . . . . . . . . . . . . . . 61 163 15.2. Informative References . . . . . . . . . . . . . . . . . 62 164 Appendix A. Schema identification examples . . . . . . . . . . . 64 165 Appendix B. Manipulating schema documents and references . . . . 66 166 B.1. Bundling schema resources into a single document . . . . 66 167 B.2. Reference removal is not always safe . . . . . . . . . . 66 168 Appendix C. Example of recursive schema extension . . . . . . . 67 169 Appendix D. Working with vocabularies . . . . . . . . . . . . . 69 170 D.1. Best practices for vocabulary and meta-schema authors . . 69 171 D.2. Example meta-schema with vocabulary declarations . . . . 70 172 Appendix E. References and generative use cases . . . . . . . . 73 173 Appendix F. Acknowledgments . . . . . . . . . . . . . . . . . . 74 174 Appendix G. ChangeLog . . . . . . . . . . . . . . . . . . . . . 74 175 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 78 177 1. Introduction 179 JSON Schema is a JSON media type for defining the structure of JSON 180 data. JSON Schema is intended to define validation, documentation, 181 hyperlink navigation, and interaction control of JSON data. 183 This specification defines JSON Schema core terminology and 184 mechanisms, including pointing to another JSON Schema by reference, 185 dereferencing a JSON Schema reference, specifying the dialect being 186 used, specifying a dialect's vocabulary requirements, and defining 187 the expected output. 189 Other specifications define the vocabularies that perform assertions 190 about validation, linking, annotation, navigation, and interaction. 192 2. Conventions and Terminology 194 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 195 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 196 document are to be interpreted as described in RFC 2119 [RFC2119]. 198 The terms "JSON", "JSON text", "JSON value", "member", "element", 199 "object", "array", "number", "string", "boolean", "true", "false", 200 and "null" in this document are to be interpreted as defined in RFC 201 8259 [RFC8259]. 203 3. Overview 205 This document proposes a new media type "application/schema+json" to 206 identify a JSON Schema for describing JSON data. It also proposes a 207 further optional media type, "application/schema-instance+json", to 208 provide additional integration features. JSON Schemas are themselves 209 JSON documents. This, and related specifications, define keywords 210 allowing authors to describe JSON data in several ways. 212 JSON Schema uses keywords to assert constraints on JSON instances or 213 annotate those instances with additional information. Additional 214 keywords are used to apply assertions and annotations to more complex 215 JSON data structures, or based on some sort of condition. 217 To facilitate re-use, keywords can be organized into vocabularies. A 218 vocabulary consists of a list of keywords, together with their syntax 219 and semantics. A dialect is defined as a set of vocabularies and 220 their required support identified in a meta-schema. 222 JSON Schema can be extended either by defining additional 223 vocabularies, or less formally by defining additional keywords 224 outside of any vocabulary. Unrecognized individual keywords simply 225 have their values collected as annotations, while the behavior with 226 respect to an unrecognized vocabulary can be controlled when 227 declaring which vocabularies are in use. 229 This document defines a core vocabulary that MUST be supported by any 230 implementation, and cannot be disabled. Its keywords are each 231 prefixed with a "$" character to emphasize their required nature. 232 This vocabulary is essential to the functioning of the "application/ 233 schema+json" media type, and is used to bootstrap the loading of 234 other vocabularies. 236 Additionally, this document defines a RECOMMENDED vocabulary of 237 keywords for applying subschemas conditionally, and for applying 238 subschemas to the contents of objects and arrays. Either this 239 vocabulary or one very much like it is required to write schemas for 240 non-trivial JSON instances, whether those schemas are intended for 241 assertion validation, annotation, or both. While not part of the 242 required core vocabulary, for maximum interoperability this 243 additional vocabulary is included in this document and its use is 244 strongly encouraged. 246 Further vocabularies for purposes such as structural validation or 247 hypermedia annotation are defined in other documents. These other 248 documents each define a dialect collecting the standard sets of 249 vocabularies needed to write schemas for that document's purpose. 251 4. Definitions 253 4.1. JSON Document 255 A JSON document is an information resource (series of octets) 256 described by the application/json media type. 258 In JSON Schema, the terms "JSON document", "JSON text", and "JSON 259 value" are interchangeable because of the data model it defines. 261 JSON Schema is only defined over JSON documents. However, any 262 document or memory structure that can be parsed into or processed 263 according to the JSON Schema data model can be interpreted against a 264 JSON Schema, including media types like CBOR [RFC7049]. 266 4.2. Instance 268 A JSON document to which a schema is applied is known as an 269 "instance". 271 JSON Schema is defined over "application/json" or compatible 272 documents, including media types with the "+json" structured syntax 273 suffix. 275 Among these, this specification defines the "application/schema- 276 instance+json" media type which defines handling for fragments in the 277 URI. 279 4.2.1. Instance Data Model 281 JSON Schema interprets documents according to a data model. A JSON 282 value interpreted according to this data model is called an 283 "instance". 285 An instance has one of six primitive types, and a range of possible 286 values depending on the type: 288 null: A JSON "null" value 290 boolean: A "true" or "false" value, from the JSON "true" or "false" 291 value 293 object: An unordered set of properties mapping a string to an 294 instance, from the JSON "object" value 296 array: An ordered list of instances, from the JSON "array" value 298 number: An arbitrary-precision, base-10 decimal number value, from 299 the JSON "number" value 301 string: A string of Unicode code points, from the JSON "string" 302 value 304 Whitespace and formatting concerns, including different lexical 305 representations of numbers that are equal within the data model, are 306 thus outside the scope of JSON Schema. JSON Schema vocabularies 307 (Section 8.1) that wish to work with such differences in lexical 308 representations SHOULD define keywords to precisely interpret 309 formatted strings within the data model rather than relying on having 310 the original JSON representation Unicode characters available. 312 Since an object cannot have two properties with the same key, 313 behavior for a JSON document that tries to define two properties with 314 the same key in a single object is undefined. 316 Note that JSON Schema vocabularies are free to define their own 317 extended type system. This should not be confused with the core data 318 model types defined here. As an example, "integer" is a reasonable 319 type for a vocabulary to define as a value for a keyword, but the 320 data model makes no distinction between integers and other numbers. 322 4.2.2. Instance Equality 324 Two JSON instances are said to be equal if and only if they are of 325 the same type and have the same value according to the data model. 326 Specifically, this means: 328 both are null; or 330 both are true; or 332 both are false; or 334 both are strings, and are the same codepoint-for-codepoint; or 335 both are numbers, and have the same mathematical value; or 337 both are arrays, and have an equal value item-for-item; or 339 both are objects, and each property in one has exactly one 340 property with a key equal to the other's, and that other property 341 has an equal value. 343 Implied in this definition is that arrays must be the same length, 344 objects must have the same number of members, properties in objects 345 are unordered, there is no way to define multiple properties with the 346 same key, and mere formatting differences (indentation, placement of 347 commas, trailing zeros) are insignificant. 349 4.2.3. Non-JSON Instances 351 It is possible to use JSON Schema with a superset of the JSON Schema 352 data model, where an instance may be outside any of the six JSON data 353 types. 355 In this case, annotations still apply; but most validation keywords 356 will not be useful, as they will always pass or always fail. 358 A custom vocabulary may define support for a superset of the core 359 data model. The schema itself may only be expressible in this 360 superset; for example, to make use of the "const" keyword. 362 4.3. JSON Schema Documents 364 A JSON Schema document, or simply a schema, is a JSON document used 365 to describe an instance. A schema can itself be interpreted as an 366 instance, but SHOULD always be given the media type "application/ 367 schema+json" rather than "application/schema-instance+json". The 368 "application/schema+json" media type is defined to offer a superset 369 of the fragment identifier syntax and semantics provided by 370 "application/schema-instance+json". 372 A JSON Schema MUST be an object or a boolean. 374 4.3.1. JSON Schema Objects and Keywords 376 Object properties that are applied to the instance are called 377 keywords, or schema keywords. Broadly speaking, keywords fall into 378 one of five categories: 380 identifiers: control schema identification through setting the 381 schema's canonical URI and/or changing how the base URI is 382 determined 384 assertions: produce a boolean result when applied to an instance 386 annotations: attach information to an instance for application use 388 applicators: apply one or more subschemas to a particular location 389 in the instance, and combine or modify their results 391 reserved locations: do not directly affect results, but reserve a 392 place for a specific purpose to ensure interoperability 394 Keywords may fall into multiple categories, although applicators 395 SHOULD only produce assertion results based on their subschemas' 396 results. They should not define additional constraints independent 397 of their subschemas. 399 Keywords which are properties within the same schema object are 400 referred to as adjacent keywords. 402 Extension keywords, meaning those defined outside of this document 403 and its companions, are free to define other behaviors as well. 405 A JSON Schema MAY contain properties which are not schema keywords. 406 Unknown keywords SHOULD be treated as annotations, where the value of 407 the keyword is the value of the annotation. 409 An empty schema is a JSON Schema with no properties, or only unknown 410 properties. 412 4.3.2. Boolean JSON Schemas 414 The boolean schema values "true" and "false" are trivial schemas that 415 always produce themselves as assertion results, regardless of the 416 instance value. They never produce annotation results. 418 These boolean schemas exist to clarify schema author intent and 419 facilitate schema processing optimizations. They behave identically 420 to the following schema objects (where "not" is part of the subschema 421 application vocabulary defined in this document). 423 true: Always passes validation, as if the empty schema {} 425 false: Always fails validation, as if the schema { "not": {} } 427 While the empty schema object is unambiguous, there are many possible 428 equivalents to the "false" schema. Using the boolean values ensures 429 that the intent is clear to both human readers and implementations. 431 4.3.3. Schema Vocabularies 433 A schema vocabulary, or simply a vocabulary, is a set of keywords, 434 their syntax, and their semantics. A vocabulary is generally 435 organized around a particular purpose. Different uses of JSON 436 Schema, such as validation, hypermedia, or user interface generation, 437 will involve different sets of vocabularies. 439 Vocabularies are the primary unit of re-use in JSON Schema, as schema 440 authors can indicate what vocabularies are required or optional in 441 order to process the schema. Since vocabularies are identified by 442 URIs in the meta-schema, generic implementations can load extensions 443 to support previously unknown vocabularies. While keywords can be 444 supported outside of any vocabulary, there is no analogous mechanism 445 to indicate individual keyword usage. 447 4.3.4. Meta-Schemas 449 A schema that itself describes a schema is called a meta-schema. 450 Meta-schemas are used to validate JSON Schemas and specify which 451 vocabularies they are using. 453 Typically, a meta-schema will specify a set of vocabularies, and 454 validate schemas that conform to the syntax of those vocabularies. 455 However, meta-schemas and vocabularies are separate in order to allow 456 meta-schemas to validate schema conformance more strictly or more 457 loosely than the vocabularies' specifications call for. Meta-schemas 458 may also describe and validate additional keywords that are not part 459 of a formal vocabulary. 461 4.3.5. Root Schema and Subschemas and Resources 463 A JSON Schema resource is a schema which is canonically [RFC6596] 464 identified by an absolute URI [RFC3986]. 466 The root schema is the schema that comprises the entire JSON document 467 in question. The root schema is always a schema resource, where the 468 URI is determined as described in section 9.1.1. 470 Some keywords take schemas themselves, allowing JSON Schemas to be 471 nested: 473 { 474 "title": "root", 475 "items": { 476 "title": "array item" 477 } 478 } 480 In this example document, the schema titled "array item" is a 481 subschema, and the schema titled "root" is the root schema. 483 As with the root schema, a subschema is either an object or a 484 boolean. 486 As discussed in section 8.2.1, a JSON Schema document can contain 487 multiple JSON Schema resources. When used without qualification, the 488 term "root schema" refers to the document's root schema. In some 489 cases, resource root schemas are discussed. A resource's root schema 490 is its top-level schema object, which would also be a document root 491 schema if the resource were to be extracted to a standalone JSON 492 Schema document. 494 Whether multiple schema resources are embedded or linked with a 495 reference, they are processed in the same way, with the same 496 available behaviors. 498 5. Fragment Identifiers 500 In accordance with section 3.1 of RFC 6839 [RFC6839], the syntax and 501 semantics of fragment identifiers specified for any +json media type 502 SHOULD be as specified for "application/json". (At publication of 503 this document, there is no fragment identification syntax defined for 504 "application/json".) 506 Additionally, the "application/schema+json" media type supports two 507 fragment identifier structures: plain names and JSON Pointers. The 508 "application/schema-instance+json" media type supports one fragment 509 identifier structure: JSON Pointers. 511 The use of JSON Pointers as URI fragment identifiers is described in 512 RFC 6901 [RFC6901]. For "application/schema+json", which supports 513 two fragment identifier syntaxes, fragment identifiers matching the 514 JSON Pointer syntax, including the empty string, MUST be interpreted 515 as JSON Pointer fragment identifiers. 517 Per the W3C's best practices for fragment identifiers 518 [W3C.WD-fragid-best-practices-20121025], plain name fragment 519 identifiers in "application/schema+json" are reserved for referencing 520 locally named schemas. All fragment identifiers that do not match 521 the JSON Pointer syntax MUST be interpreted as plain name fragment 522 identifiers. 524 Defining and referencing a plain name fragment identifier within an 525 "application/schema+json" document are specified in the "$anchor" 526 keyword (Section 8.2.2) section. 528 6. General Considerations 530 6.1. Range of JSON Values 532 An instance may be any valid JSON value as defined by JSON [RFC8259]. 533 JSON Schema imposes no restrictions on type: JSON Schema can describe 534 any JSON value, including, for example, null. 536 6.2. Programming Language Independence 538 JSON Schema is programming language agnostic, and supports the full 539 range of values described in the data model. Be aware, however, that 540 some languages and JSON parsers may not be able to represent in 541 memory the full range of values describable by JSON. 543 6.3. Mathematical Integers 545 Some programming languages and parsers use different internal 546 representations for floating point numbers than they do for integers. 548 For consistency, integer JSON numbers SHOULD NOT be encoded with a 549 fractional part. 551 6.4. Regular Expressions 553 Keywords MAY use regular expressions to express constraints, or 554 constrain the instance value to be a regular expression. These 555 regular expressions SHOULD be valid according to the regular 556 expression dialect described in ECMA-262, section 21.2.1 [ecma262]. 558 Regular expressions SHOULD be built with the "u" flag (or equivalent) 559 to provide Unicode support, or processed in such a way which provides 560 Unicode support as defined by ECMA-262. 562 Furthermore, given the high disparity in regular expression 563 constructs support, schema authors SHOULD limit themselves to the 564 following regular expression tokens: 566 individual Unicode characters, as defined by the JSON 567 specification [RFC8259]; 568 simple character classes ([abc]), range character classes ([a-z]); 570 complemented character classes ([^abc], [^a-z]); 572 simple quantifiers: "+" (one or more), "*" (zero or more), "?" 573 (zero or one), and their lazy versions ("+?", "*?", "??"); 575 range quantifiers: "{x}" (exactly x occurrences), "{x,y}" (at 576 least x, at most y, occurrences), {x,} (x occurrences or more), 577 and their lazy versions; 579 the beginning-of-input ("^") and end-of-input ("$") anchors; 581 simple grouping ("(...)") and alternation ("|"). 583 Finally, implementations MUST NOT take regular expressions to be 584 anchored, neither at the beginning nor at the end. This means, for 585 instance, the pattern "es" matches "expression". 587 6.5. Extending JSON Schema 589 Additional schema keywords and schema vocabularies MAY be defined by 590 any entity. Save for explicit agreement, schema authors SHALL NOT 591 expect these additional keywords and vocabularies to be supported by 592 implementations that do not explicitly document such support. 593 Implementations SHOULD treat keywords they do not support as 594 annotations, where the value of the keyword is the value of the 595 annotation. 597 Implementations MAY provide the ability to register or load handlers 598 for vocabularies that they do not support directly. The exact 599 mechanism for registering and implementing such handlers is 600 implementation-dependent. 602 7. Keyword Behaviors 604 JSON Schema keywords fall into several general behavior categories. 605 Assertions validate that an instance satisfies constraints, producing 606 a boolean result. Annotations attach information that applications 607 may use in any way they see fit. Applicators apply subschemas to 608 parts of the instance and combine their results. 610 Extension keywords SHOULD stay within these categories, keeping in 611 mind that annotations in particular are extremely flexible. Complex 612 behavior is usually better delegated to applications on the basis of 613 annotation data than implemented directly as schema keywords. 614 However, extension keywords MAY define other behaviors for 615 specialized purposes. 617 Evaluating an instance against a schema involves processing all of 618 the keywords in the schema against the appropriate locations within 619 the instance. Typically, applicator keywords are processed until a 620 schema object with no applicators (and therefore no subschemas) is 621 reached. The appropriate location in the instance is evaluated 622 against the assertion and annotation keywords in the schema object, 623 and their results are gathered into the parent schema according to 624 the rules of the applicator. 626 Evaluation of a parent schema object can complete once all of its 627 subschemas have been evaluated, although in some circumstances 628 evaluation may be short-circuited due to assertion results. When 629 annotations are being collected, some assertion result short- 630 circuiting is not possible due to the need to examine all subschemas 631 for annotation collection, including those that cannot further change 632 the assertion result. 634 7.1. Lexical Scope and Dynamic Scope 636 While most JSON Schema keywords can be evaluated on their own, or at 637 most need to take into account the values or results of adjacent 638 keywords in the same schema object, a few have more complex behavior. 640 The lexical scope of a keyword is determined by the nested JSON data 641 structure of objects and arrays. The largest such scope is an entire 642 schema document. The smallest scope is a single schema object with 643 no subschemas. 645 Keywords MAY be defined with a partial value, such as a URI- 646 reference, which must be resolved against another value, such as 647 another URI-reference or a full URI, which is found through the 648 lexical structure of the JSON document. The "$id", "$ref", and 649 "$dynamicRef" core keywords, and the "base" JSON Hyper-Schema 650 keyword, are examples of this sort of behavior. 652 Note that some keywords, such as "$schema", apply to the lexical 653 scope of the entire schema resource, and therefore MUST only appear 654 in a schema resource's root schema. 656 Other keywords may take into account the dynamic scope that exists 657 during the evaluation of a schema, typically together with an 658 instance document. The outermost dynamic scope is the schema object 659 at which processing begins, even if it is not a schema resource root. 660 The path from this root schema to any particular keyword (that 661 includes any "$ref" and "$dynamicRef" keywords that may have been 662 resolved) is considered the keyword's "validation path." 663 Lexical and dynamic scopes align until a reference keyword is 664 encountered. While following the reference keyword moves processing 665 from one lexical scope into a different one, from the perspective of 666 dynamic scope, following a reference is no different from descending 667 into a subschema present as a value. A keyword on the far side of 668 that reference that resolves information through the dynamic scope 669 will consider the originating side of the reference to be their 670 dynamic parent, rather than examining the local lexically enclosing 671 parent. 673 The concept of dynamic scope is primarily used with "$dynamicRef" and 674 "$dynamicAnchor", and should be considered an advanced feature and 675 used with caution when defining additional keywords. It also appears 676 when reporting errors and collected annotations, as it may be 677 possible to revisit the same lexical scope repeatedly with different 678 dynamic scopes. In such cases, it is important to inform the user of 679 the dynamic path that produced the error or annotation. 681 7.2. Keyword Interactions 683 Keyword behavior MAY be defined in terms of the annotation results of 684 subschemas (Section 4.3.5) and/or adjacent keywords (keywords within 685 the same schema object) and their subschemas. Such keywords MUST NOT 686 result in a circular dependency. Keywords MAY modify their behavior 687 based on the presence or absence of another keyword in the same 688 schema object (Section 4.3). 690 7.3. Default Behaviors 692 A missing keyword MUST NOT produce a false assertion result, MUST NOT 693 produce annotation results, and MUST NOT cause any other schema to be 694 evaluated as part of its own behavioral definition. However, given 695 that missing keywords do not contribute annotations, the lack of 696 annotation results may indirectly change the behavior of other 697 keywords. 699 In some cases, the missing keyword assertion behavior of a keyword is 700 identical to that produced by a certain value, and keyword 701 definitions SHOULD note such values where known. However, even if 702 the value which produces the default behavior would produce 703 annotation results if present, the default behavior still MUST NOT 704 result in annotations. 706 Because annotation collection can add significant cost in terms of 707 both computation and memory, implementations MAY opt out of this 708 feature. Keywords that are specified in terms of collected 709 annotations SHOULD describe reasonable alternate approaches when 710 appropriate. This approach is demonstrated by the "items" and 711 "additionalProperties" keywords in this document. 713 Note that when no such alternate approach is possible for a keyword, 714 implementations that do not support annotation collections will not 715 be able to support those keywords or vocabularies that contain them. 717 7.4. Identifiers 719 Identifiers set the canonical URI of a schema, or affect how such 720 URIs are resolved in references (Section 8.2.3), or both. The Core 721 vocabulary defined in this document defines several identifying 722 keywords, most notably "$id". 724 Canonical schema URIs MUST NOT change while processing an instance, 725 but keywords that affect URI-reference resolution MAY have behavior 726 that is only fully determined at runtime. 728 While custom identifier keywords are possible, vocabulary designers 729 should take care not to disrupt the functioning of core keywords. 730 For example, the "$dynamicAnchor" keyword in this specification 731 limits its URI resolution effects to the matching "$dynamicRef" 732 keyword, leaving the behavior of "$ref" undisturbed. 734 7.5. Applicators 736 Applicators allow for building more complex schemas than can be 737 accomplished with a single schema object. Evaluation of an instance 738 against a schema document (Section 4.3) begins by applying the root 739 schema (Section 4.3.5) to the complete instance document. From 740 there, keywords known as applicators are used to determine which 741 additional schemas are applied. Such schemas may be applied in-place 742 to the current location, or to a child location. 744 The schemas to be applied may be present as subschemas comprising all 745 or part of the keyword's value. Alternatively, an applicator may 746 refer to a schema elsewhere in the same schema document, or in a 747 different one. The mechanism for identifying such referenced schemas 748 is defined by the keyword. 750 Applicator keywords also define how subschema or referenced schema 751 boolean assertion (Section 7.6) results are modified and/or combined 752 to produce the boolean result of the applicator. Applicators may 753 apply any boolean logic operation to the assertion results of 754 subschemas, but MUST NOT introduce new assertion conditions of their 755 own. 757 Annotation (Section 7.7) results are preserved along with the 758 instance location and the location of the schema keyword, so that 759 applications can decide how to interpret multiple values. 761 7.5.1. Referenced and Referencing Schemas 763 As noted in Section 7.5, an applicator keyword may refer to a schema 764 to be applied, rather than including it as a subschema in the 765 applicator's value. In such situations, the schema being applied is 766 known as the referenced schema, while the schema containing the 767 applicator keyword is the referencing schema. 769 While root schemas and subschemas are static concepts based on a 770 schema's position within a schema document, referenced and 771 referencing schemas are dynamic. Different pairs of schemas may find 772 themselves in various referenced and referencing arrangements during 773 the evaluation of an instance against a schema. 775 For some by-reference applicators, such as "$ref" (Section 8.2.3.1), 776 the referenced schema can be determined by static analysis of the 777 schema document's lexical scope. Others, such as "$dynamicRef" (with 778 "$dynamicAnchor"), may make use of dynamic scoping, and therefore 779 only be resolvable in the process of evaluating the schema with an 780 instance. 782 7.6. Assertions 784 JSON Schema can be used to assert constraints on a JSON document, 785 which either passes or fails the assertions. This approach can be 786 used to validate conformance with the constraints, or document what 787 is needed to satisfy them. 789 JSON Schema implementations produce a single boolean result when 790 evaluating an instance against schema assertions. 792 An instance can only fail an assertion that is present in the schema. 794 7.6.1. Assertions and Instance Primitive Types 796 Most assertions only constrain values within a certain primitive 797 type. When the type of the instance is not of the type targeted by 798 the keyword, the instance is considered to conform to the assertion. 800 For example, the "maxLength" keyword from the companion validation 801 vocabulary [json-schema-validation]: will only restrict certain 802 strings (that are too long) from being valid. If the instance is a 803 number, boolean, null, array, or object, then it is valid against 804 this assertion. 806 This behavior allows keywords to be used more easily with instances 807 that can be of multiple primitive types. The companion validation 808 vocabulary also includes a "type" keyword which can independently 809 restrict the instance to one or more primitive types. This allows 810 for a concise expression of use cases such as a function that might 811 return either a string of a certain length or a null value: 813 { 814 "type": ["string", "null"], 815 "maxLength": 255 816 } 818 If "maxLength" also restricted the instance type to be a string, then 819 this would be substantially more cumbersome to express because the 820 example as written would not actually allow null values. Each 821 keyword is evaluated separately unless explicitly specified 822 otherwise, so if "maxLength" restricted the instance to strings, then 823 including "null" in "type" would not have any useful effect. 825 7.7. Annotations 827 JSON Schema can annotate an instance with information, whenever the 828 instance validates against the schema object containing the 829 annotation, and all of its parent schema objects. The information 830 can be a simple value, or can be calculated based on the instance 831 contents. 833 Annotations are attached to specific locations in an instance. Since 834 many subschemas can be applied to any single location, applications 835 may need to decide how to handle differing annotation values being 836 attached to the same instance location by the same schema keyword in 837 different schema objects. 839 Unlike assertion results, annotation data can take a wide variety of 840 forms, which are provided to applications to use as they see fit. 841 JSON Schema implementations are not expected to make use of the 842 collected information on behalf of applications. 844 Unless otherwise specified, the value of an annotation keyword is the 845 keyword's value. However, other behaviors are possible. For 846 example, JSON Hyper-Schema's [json-hyper-schema] "links" keyword is a 847 complex annotation that produces a value based in part on the 848 instance data. 850 While "short-circuit" evaluation is possible for assertions, 851 collecting annotations requires examining all schemas that apply to 852 an instance location, even if they cannot change the overall 853 assertion result. The only exception is that subschemas of a schema 854 object that has failed validation MAY be skipped, as annotations are 855 not retained for failing schemas. 857 7.7.1. Collecting Annotations 859 Annotations are collected by keywords that explicitly define 860 annotation-collecting behavior. Note that boolean schemas cannot 861 produce annotations as they do not make use of keywords. 863 A collected annotation MUST include the following information: 865 The name of the keyword that produces the annotation 867 The instance location to which it is attached, as a JSON Pointer 869 The schema location path, indicating how reference keywords such 870 as "$ref" were followed to reach the absolute schema location. 872 The absolute schema location of the attaching keyword, as a URI. 873 This MAY be omitted if it is the same as the schema location path 874 from above. 876 The attached value(s) 878 7.7.1.1. Distinguishing Among Multiple Values 880 Applications MAY make decisions on which of multiple annotation 881 values to use based on the schema location that contributed the 882 value. This is intended to allow flexible usage. Collecting the 883 schema location facilitates such usage. 885 For example, consider this schema, which uses annotations and 886 assertions from the Validation specification 887 [json-schema-validation]: 889 Note that some lines are wrapped for clarity. 891 { 892 "title": "Feature list", 893 "type": "array", 894 "prefixItems": [ 895 { 896 "title": "Feature A", 897 "properties": { 898 "enabled": { 899 "$ref": "#/$defs/enabledToggle", 900 "default": true 901 } 902 } 903 }, 904 { 905 "title": "Feature B", 906 "properties": { 907 "enabled": { 908 "description": "If set to null, Feature B 909 inherits the enabled 910 value from Feature A", 911 "$ref": "#/$defs/enabledToggle" 912 } 913 } 914 } 915 ], 916 "$defs": { 917 "enabledToggle": { 918 "title": "Enabled", 919 "description": "Whether the feature is enabled (true), 920 disabled (false), or under 921 automatic control (null)", 922 "type": ["boolean", "null"], 923 "default": null 924 } 925 } 926 } 928 In this example, both Feature A and Feature B make use of the re- 929 usable "enabledToggle" schema. That schema uses the "title", 930 "description", and "default" annotations. Therefore the application 931 has to decide how to handle the additional "default" value for 932 Feature A, and the additional "description" value for Feature B. 934 The application programmer and the schema author need to agree on the 935 usage. For this example, let's assume that they agree that the most 936 specific "default" value will be used, and any additional, more 937 generic "default" values will be silently ignored. Let's also assume 938 that they agree that all "description" text is to be used, starting 939 with the most generic, and ending with the most specific. This 940 requires the schema author to write descriptions that work when 941 combined in this way. 943 The application can use the schema location path to determine which 944 values are which. The values in the feature's immediate "enabled" 945 property schema are more specific, while the values under the re- 946 usable schema that is referenced to with "$ref" are more generic. 947 The schema location path will show whether each value was found by 948 crossing a "$ref" or not. 950 Feature A will therefore use a default value of true, while Feature B 951 will use the generic default value of null. Feature A will only have 952 the generic description from the "enabledToggle" schema, while 953 Feature B will use that description, and also append its locally 954 defined description that explains how to interpret a null value. 956 Note that there are other reasonable approaches that a different 957 application might take. For example, an application may consider the 958 presence of two different values for "default" to be an error, 959 regardless of their schema locations. 961 7.7.1.2. Annotations and Assertions 963 Schema objects that produce a false assertion result MUST NOT produce 964 any annotation results, whether from their own keywords or from 965 keywords in subschemas. 967 Note that the overall schema results may still include annotations 968 collected from other schema locations. Given this schema: 970 { 971 "oneOf": [ 972 { 973 "title": "Integer Value", 974 "type": "integer" 975 }, 976 { 977 "title": "String Value", 978 "type": "string" 979 } 980 ] 981 } 983 Against the instance ""This is a string"", the title annotation 984 "Integer Value" is discarded because the type assertion in that 985 schema object fails. The title annotation "String Value" is kept, as 986 the instance passes the string type assertions. 988 7.7.1.3. Annotations and Applicators 990 In addition to possibly defining annotation results of their own, 991 applicator keywords aggregate the annotations collected in their 992 subschema(s) or referenced schema(s). 994 7.8. Reserved Locations 996 A fourth category of keywords simply reserve a location to hold re- 997 usable components or data of interest to schema authors that is not 998 suitable for re-use. These keywords do not affect validation or 999 annotation results. Their purpose in the core vocabulary is to 1000 ensure that locations are available for certain purposes and will not 1001 be redefined by extension keywords. 1003 While these keywords do not directly affect results, as explained in 1004 section 9.4.2 unrecognized extension keywords that reserve locations 1005 for re-usable schemas may have undesirable interactions with 1006 references in certain circumstances. 1008 7.9. Loading Instance Data 1010 While none of the vocabularies defined as part of this or the 1011 associated documents define a keyword which may target and/or load 1012 instance data, it is possible that other vocabularies may wish to do 1013 so. 1015 Keywords MAY be defined to use JSON Pointers or Relative JSON 1016 Pointers to examine parts of an instance outside the current 1017 evaluation location. 1019 Keywords that allow adjusting the location using a Relative JSON 1020 Pointer SHOULD default to using the current location if a default is 1021 desireable. 1023 8. The JSON Schema Core Vocabulary 1025 Keywords declared in this section, which all begin with "$", make up 1026 the JSON Schema Core vocabulary. These keywords are either required 1027 in order to process any schema or meta-schema, including those split 1028 across multiple documents, or exist to reserve keywords for purposes 1029 that require guaranteed interoperability. 1031 The Core vocabulary MUST be considered mandatory at all times, in 1032 order to bootstrap the processing of further vocabularies. Meta- 1033 schemas that use the "$vocabulary" (Section 8.1) keyword to declare 1034 the vocabularies in use MUST explicitly list the Core vocabulary, 1035 which MUST have a value of true indicating that it is required. 1037 The behavior of a false value for this vocabulary (and only this 1038 vocabulary) is undefined, as is the behavior when "$vocabulary" is 1039 present but the Core vocabulary is not included. However, it is 1040 RECOMMENDED that implementations detect these cases and raise an 1041 error when they occur. It is not meaningful to declare that a meta- 1042 schema optionally uses Core. 1044 Meta-schemas that do not use "$vocabulary" MUST be considered to 1045 require the Core vocabulary as if its URI were present with a value 1046 of true. 1048 The current URI for the Core vocabulary is: . 1051 The current URI for the corresponding meta-schema is: . 1054 While the "$" prefix is not formally reserved for the Core 1055 vocabulary, it is RECOMMENDED that extension keywords (in 1056 vocabularies or otherwise) begin with a character other than "$" to 1057 avoid possible future collisions. 1059 8.1. Meta-Schemas and Vocabularies 1061 Two concepts, meta-schemas and vocabularies, are used to inform an 1062 implementation how to interpret a schema. Every schema has a meta- 1063 schema, which can be declared using the "$schema" keyword. 1065 The meta-schema serves two purposes: 1067 Declaring the vocabularies in use The "$vocabulary" keyword, when it 1068 appears in a meta-schema, declares which vocabularies are 1069 available to be used in schemas that refer to that meta-schema. 1070 Vocabularies define keyword semantics, as well as their general 1071 syntax. 1073 Describing valid schema syntax A schema MUST successfully validate 1074 against its meta-schema, which constrains the syntax of the 1075 available keywords. The syntax described is expected to be 1076 compatible with the vocabularies declared; while it is possible to 1077 describe an incompatible syntax, such a meta-schema would be 1078 unlikely to be useful. 1080 Meta-schemas are separate from vocabularies to allow for vocabularies 1081 to be combined in different ways, and for meta-schema authors to 1082 impose additional constraints such as forbidding certain keywords, or 1083 performing unusually strict syntactical validation, as might be done 1084 during a development and testing cycle. Each vocabulary typically 1085 identifies a meta-schema consisting only of the vocabulary's 1086 keywords. 1088 Meta-schema authoring is an advanced usage of JSON Schema, so the 1089 design of meta-schema features emphasizes flexibility over 1090 simplicity. 1092 8.1.1. The "$schema" Keyword 1094 The "$schema" keyword is both used as a JSON Schema dialect 1095 identifier and as the identifier of a resource which is itself a JSON 1096 Schema, which describes the set of valid schemas written for this 1097 particular dialect. 1099 The value of this keyword MUST be a URI [RFC3986] (containing a 1100 scheme) and this URI MUST be normalized. The current schema MUST be 1101 valid against the meta-schema identified by this URI. 1103 If this URI identifies a retrievable resource, that resource SHOULD 1104 be of media type "application/schema+json". 1106 The "$schema" keyword SHOULD be used in the document root schema 1107 object, and MAY be used in the root schema objects of embedded schema 1108 resources. It MUST NOT appear in non-resource root schema objects. 1109 If absent from the document root schema, the resulting behavior is 1110 implementation-defined. 1112 Values for this property are defined elsewhere in this and other 1113 documents, and by other parties. 1115 8.1.2. The "$vocabulary" Keyword 1117 The "$vocabulary" keyword is used in meta-schemas to identify the 1118 vocabularies available for use in schemas described by that meta- 1119 schema. It is also used to indicate whether each vocabulary is 1120 required or optional, in the sense that an implementation MUST 1121 understand the required vocabularies in order to successfully process 1122 the schema. Together, this information forms a dialect. Any 1123 vocabulary that is understood by the implementation MUST be processed 1124 in a manner consistent with the semantic definitions contained within 1125 the vocabulary. 1127 The value of this keyword MUST be an object. The property names in 1128 the object MUST be URIs (containing a scheme) and this URI MUST be 1129 normalized. Each URI that appears as a property name identifies a 1130 specific set of keywords and their semantics. 1132 The URI MAY be a URL, but the nature of the retrievable resource is 1133 currently undefined, and reserved for future use. Vocabulary authors 1134 MAY use the URL of the vocabulary specification, in a human-readable 1135 media type such as text/html or text/plain, as the vocabulary URI. 1136 [[CREF1: Vocabulary documents may be added in forthcoming drafts. 1137 For now, identifying the keyword set is deemed sufficient as that, 1138 along with meta-schema validation, is how the current "vocabularies" 1139 work today. Any future vocabulary document format will be specified 1140 as a JSON document, so using text/html or other non-JSON formats in 1141 the meantime will not produce any future ambiguity. ]] 1143 The values of the object properties MUST be booleans. If the value 1144 is true, then implementations that do not recognize the vocabulary 1145 MUST refuse to process any schemas that declare this meta-schema with 1146 "$schema". If the value is false, implementations that do not 1147 recognize the vocabulary SHOULD proceed with processing such schemas. 1148 The value has no impact if the implementation understands the 1149 vocabulary. 1151 Per 6.5, unrecognized keywords SHOULD be treated as annotations. 1152 This remains the case for keywords defined by unrecognized 1153 vocabularies. It is not currently possible to distinguish between 1154 unrecognized keywords that are defined in vocabularies from those 1155 that are not part of any vocabulary. 1157 The "$vocabulary" keyword SHOULD be used in the root schema of any 1158 schema document intended for use as a meta-schema. It MUST NOT 1159 appear in subschemas. 1161 The "$vocabulary" keyword MUST be ignored in schema documents that 1162 are not being processed as a meta-schema. This allows validating a 1163 meta-schema M against its own meta-schema M' without requiring the 1164 validator to understand the vocabularies declared by M. 1166 8.1.2.1. Default vocabularies 1168 If "$vocabulary" is absent, an implementation MAY determine behavior 1169 based on the meta-schema if it is recognized from the URI value of 1170 the referring schema's "$schema" keyword. This is how behavior (such 1171 as Hyper-Schema usage) has been recognized prior to the existence of 1172 vocabularies. 1174 If the meta-schema, as referenced by the schema, is not recognized, 1175 or is missing, then the behavior is implementation-defined. If the 1176 implementation proceeds with processing the schema, it MUST assume 1177 the use of the core vocabulary. If the implementation is built for a 1178 specific purpose, then it SHOULD assume the use of all of the most 1179 relevant vocabularies for that purpose. 1181 For example, an implementation that is a validator SHOULD assume the 1182 use of all vocabularies in this specification and the companion 1183 Validation specification. 1185 8.1.2.2. Non-inheritability of vocabularies 1187 Note that the processing restrictions on "$vocabulary" mean that 1188 meta-schemas that reference other meta-schemas using "$ref" or 1189 similar keywords do not automatically inherit the vocabulary 1190 declarations of those other meta-schemas. All such declarations must 1191 be repeated in the root of each schema document intended for use as a 1192 meta-schema. This is demonstrated in the example meta-schema 1193 (Appendix D.2). [[CREF2: This requirement allows implementations to 1194 find all vocabulary requirement information in a single place for 1195 each meta-schema. As schema extensibility means that there are 1196 endless potential ways to combine more fine-grained meta-schemas by 1197 reference, requiring implementations to anticipate all possibilities 1198 and search for vocabularies in referenced meta-schemas would be 1199 overly burdensome. ]] 1201 8.1.3. Updates to Meta-Schema and Vocabulary URIs 1203 Updated vocabulary and meta-schema URIs MAY be published between 1204 specification drafts in order to correct errors. Implementations 1205 SHOULD consider URIs dated after this specification draft and before 1206 the next to indicate the same syntax and semantics as those listed 1207 here. 1209 8.2. Base URI, Anchors, and Dereferencing 1211 To differentiate between schemas in a vast ecosystem, schemas are 1212 identified by URI [RFC3986], and can embed references to other 1213 schemas by specifying their URI. 1215 Several keywords can accept a relative URI-reference [RFC3986], or a 1216 value used to construct a relative URI-reference. For these 1217 keywords, it is necessary to establish a base URI in order to resolve 1218 the reference. 1220 8.2.1. The "$id" Keyword 1222 The "$id" keyword identifies a schema resource with its canonical 1223 [RFC6596] URI. 1225 Note that this URI is an identifier and not necessarily a network 1226 locator. In the case of a network-addressable URL, a schema need not 1227 be downloadable from its canonical URI. 1229 If present, the value for this keyword MUST be a string, and MUST 1230 represent a valid URI-reference [RFC3986]. This URI-reference SHOULD 1231 be normalized, and MUST resolve to an absolute-URI [RFC3986] (without 1232 a fragment). Therefore, "$id" MUST NOT contain a non-empty fragment, 1233 and SHOULD NOT contain an empty fragment. 1235 Since an empty fragment in the context of the application/schema+json 1236 media type refers to the same resource as the base URI without a 1237 fragment, an implementation MAY normalize a URI ending with an empty 1238 fragment by removing the fragment. However, schema authors SHOULD 1239 NOT rely on this behavior across implementations. [[CREF3: This is 1240 primarily allowed because older meta-schemas have an empty fragment 1241 in their $id (or previously, id). A future draft may outright forbid 1242 even empty fragments in "$id". ]] 1244 This URI also serves as the base URI for relative URI-references in 1245 keywords within the schema resource, in accordance with RFC 3986 1246 section 5.1.1 [RFC3986] regarding base URIs embedded in content. 1248 The presence of "$id" in a subschema indicates that the subschema 1249 constitutes a distinct schema resource within a single schema 1250 document. Furthermore, in accordance with RFC 3986 section 5.1.2 1251 [RFC3986] regarding encapsulating entities, if an "$id" in a 1252 subschema is a relative URI-reference, the base URI for resolving 1253 that reference is the URI of the parent schema resource. 1255 If no parent schema object explicitly identifies itself as a resource 1256 with "$id", the base URI is that of the entire document, as 1257 established by the steps given in the previous section. 1258 (Section 9.1.1) 1260 8.2.1.1. Identifying the root schema 1262 The root schema of a JSON Schema document SHOULD contain an "$id" 1263 keyword with an absolute-URI [RFC3986] (containing a scheme, but no 1264 fragment). 1266 8.2.2. Defining location-independent identifiers 1268 Using JSON Pointer fragments requires knowledge of the structure of 1269 the schema. When writing schema documents with the intention to 1270 provide re-usable schemas, it may be preferable to use a plain name 1271 fragment that is not tied to any particular structural location. 1272 This allows a subschema to be relocated without requiring JSON 1273 Pointer references to be updated. 1275 The "$anchor" and "$dynamicAnchor" keywords are used to specify such 1276 fragments. They are identifier keywords that can only be used to 1277 create plain name fragments, rather than absolute URIs as seen with 1278 "$id". 1280 The base URI to which the resulting fragment is appended is the 1281 canonical URI of the schema resource containing the "$anchor" or 1282 "$dynamicAnchor" in question. As discussed in the previous section, 1283 this is either the nearest "$id" in the same or parent schema object, 1284 or the base URI for the document as determined according to RFC 3986. 1286 Separately from the usual usage of URIs, "$dynamicAnchor" indicates 1287 that the fragment is an extension point when used with the 1288 "$dynamicRef" keyword. This low-level, advanced feature makes it 1289 easier to extend recursive schemas such as the meta-schemas, without 1290 imposing any particular semantics on that extension. See the section 1291 on "$dynamicRef" (Section 8.2.3.2) for details. 1293 In most cases, the normal fragment behavior both suffices and is more 1294 intuitive. Therefore it is RECOMMENDED that "$anchor" be used to 1295 create plain name fragments unless there is a clear need for 1296 "$dynamicAnchor". 1298 If present, the value of this keyword MUST be a string and MUST start 1299 with a letter ([A-Za-z]) or underscore ("_"), followed by any number 1300 of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), and 1301 periods ("."). This matches the US-ASCII part of XML's NCName 1302 production [xml-names]. [[CREF4: Note that the anchor string does 1303 not include the "#" character, as it is not a URI-reference. An 1304 "$anchor": "foo" becomes the fragment "#foo" when used in a URI. See 1305 below for full examples. ]] 1307 The effect of specifying the same fragment name multiple times within 1308 the same resource, using any combination of "$anchor" and/or 1309 "$dynamicAnchor", is undefined. Implementations MAY raise an error 1310 if such usage is detected. 1312 8.2.3. Schema References 1314 Several keywords can be used to reference a schema which is to be 1315 applied to the current instance location. "$ref" and "$dynamicRef" 1316 are applicator keywords, applying the referenced schema to the 1317 instance. 1319 As the values of "$ref" and "$dynamicRef" are URI References, this 1320 allows the possibility to externalise or divide a schema across 1321 multiple files, and provides the ability to validate recursive 1322 structures through self-reference. 1324 The resolved URI produced by these keywords is not necessarily a 1325 network locator, only an identifier. A schema need not be 1326 downloadable from the address if it is a network-addressable URL, and 1327 implementations SHOULD NOT assume they should perform a network 1328 operation when they encounter a network-addressable URI. 1330 8.2.3.1. Direct References with "$ref" 1332 The "$ref" keyword is an applicator that is used to reference a 1333 statically identified schema. Its results are the results of the 1334 referenced schema. [[CREF5: Note that this definition of how the 1335 results are determined means that other keywords can appear alongside 1336 of "$ref" in the same schema object. ]] 1338 The value of the "$ref" keyword MUST be a string which is a URI- 1339 Reference. Resolved against the current URI base, it produces the 1340 URI of the schema to apply. This resolution is safe to perform on 1341 schema load, as the process of evaluating an instance cannot change 1342 how the reference resolves. 1344 8.2.3.2. Dynamic References with "$dynamicRef" 1346 The "$dynamicRef" keyword is an applicator that allows for deferring 1347 the full resolution until runtime, at which point it is resolved each 1348 time it is encountered while evaluating an instance. 1350 Together with "$dynamicAnchor", "$dynamicRef" implements a 1351 cooperative extension mechanism that is primarily useful with 1352 recursive schemas (schemas that reference themselves). Both the 1353 extension point and the runtime-determined extension target are 1354 defined with "$dynamicAnchor", and only exhibit runtime dynamic 1355 behavior when referenced with "$dynamicRef". 1357 The value of the "$dynamicRef" property MUST be a string which is a 1358 URI-Reference. Resolved against the current URI base, it produces 1359 the URI used as the starting point for runtime resolution. This 1360 initial resolution is safe to perform on schema load. 1362 If the initially resolved starting point URI includes a fragment that 1363 was created by the "$dynamicAnchor" keyword, the initial URI MUST be 1364 replaced by the URI (including the fragment) for the outermost schema 1365 resource in the dynamic scope (Section 7.1) that defines an 1366 identically named fragment with "$dynamicAnchor". 1368 Otherwise, its behavior is identical to "$ref", and no runtime 1369 resolution is needed. 1371 For a full example using these keyword, see appendix C. [[CREF6: The 1372 difference between the hyper-schema meta-schema in pre-2019 drafts 1373 and an this draft dramatically demonstrates the utility of these 1374 keywords. ]] 1376 8.2.4. Schema Re-Use With "$defs" 1378 The "$defs" keyword reserves a location for schema authors to inline 1379 re-usable JSON Schemas into a more general schema. The keyword does 1380 not directly affect the validation result. 1382 This keyword's value MUST be an object. Each member value of this 1383 object MUST be a valid JSON Schema. 1385 As an example, here is a schema describing an array of positive 1386 integers, where the positive integer constraint is a subschema in 1387 "$defs": 1389 { 1390 "type": "array", 1391 "items": { "$ref": "#/$defs/positiveInteger" }, 1392 "$defs": { 1393 "positiveInteger": { 1394 "type": "integer", 1395 "exclusiveMinimum": 0 1396 } 1397 } 1398 } 1400 8.3. Comments With "$comment" 1402 This keyword reserves a location for comments from schema authors to 1403 readers or maintainers of the schema. 1405 The value of this keyword MUST be a string. Implementations MUST NOT 1406 present this string to end users. Tools for editing schemas SHOULD 1407 support displaying and editing this keyword. The value of this 1408 keyword MAY be used in debug or error output which is intended for 1409 developers making use of schemas. 1411 Schema vocabularies SHOULD allow "$comment" within any object 1412 containing vocabulary keywords. Implementations MAY assume 1413 "$comment" is allowed unless the vocabulary specifically forbids it. 1414 Vocabularies MUST NOT specify any effect of "$comment" beyond what is 1415 described in this specification. 1417 Tools that translate other media types or programming languages to 1418 and from application/schema+json MAY choose to convert that media 1419 type or programming language's native comments to or from "$comment" 1420 values. The behavior of such translation when both native comments 1421 and "$comment" properties are present is implementation-dependent. 1423 Implementations MAY strip "$comment" values at any point during 1424 processing. In particular, this allows for shortening schemas when 1425 the size of deployed schemas is a concern. 1427 Implementations MUST NOT take any other action based on the presence, 1428 absence, or contents of "$comment" properties. In particular, the 1429 value of "$comment" MUST NOT be collected as an annotation result. 1431 9. Loading and Processing Schemas 1432 9.1. Loading a Schema 1434 9.1.1. Initial Base URI 1436 RFC3986 Section 5.1 [RFC3986] defines how to determine the default 1437 base URI of a document. 1439 Informatively, the initial base URI of a schema is the URI at which 1440 it was found, whether that was a network location, a local 1441 filesystem, or any other situation identifiable by a URI of any known 1442 scheme. 1444 If a schema document defines no explicit base URI with "$id" 1445 (embedded in content), the base URI is that determined per RFC 3986 1446 section 5 [RFC3986]. 1448 If no source is known, or no URI scheme is known for the source, a 1449 suitable implementation-specific default URI MAY be used as described 1450 in RFC 3986 Section 5.1.4 [RFC3986]. It is RECOMMENDED that 1451 implementations document any default base URI that they assume. 1453 If a schema object is embedded in a document of another media type, 1454 then the initial base URI is determined according to the rules of 1455 that media type. 1457 Unless the "$id" keyword described in the next section is present in 1458 the root schema, this base URI SHOULD be considered the canonical URI 1459 of the schema document's root schema resource. 1461 9.1.2. Loading a referenced schema 1463 The use of URIs to identify remote schemas does not necessarily mean 1464 anything is downloaded, but instead JSON Schema implementations 1465 SHOULD understand ahead of time which schemas they will be using, and 1466 the URIs that identify them. 1468 When schemas are downloaded, for example by a generic user-agent that 1469 does not know until runtime which schemas to download, see Usage for 1470 Hypermedia (Section 9.5.1). 1472 Implementations SHOULD be able to associate arbitrary URIs with an 1473 arbitrary schema and/or automatically associate a schema's "$id"- 1474 given URI, depending on the trust that the validator has in the 1475 schema. Such URIs and schemas can be supplied to an implementation 1476 prior to processing instances, or may be noted within a schema 1477 document as it is processed, producing associations as shown in 1478 appendix A. 1480 A schema MAY (and likely will) have multiple URIs, but there is no 1481 way for a URI to identify more than one schema. When multiple 1482 schemas try to identify as the same URI, validators SHOULD raise an 1483 error condition. 1485 9.1.3. Detecting a Meta-Schema 1487 Implementations MUST recognize a schema as a meta-schema if it is 1488 being examined because it was identified as such by another schema's 1489 "$schema" keyword. This means that a single schema document might 1490 sometimes be considered a regular schema, and other times be 1491 considered a meta-schema. 1493 In the case of examining a schema which is its own meta-schema, when 1494 an implementation begins processing it as a regular schema, it is 1495 processed under those rules. However, when loaded a second time as a 1496 result of checking its own "$schema" value, it is treated as a meta- 1497 schema. So the same document is processed both ways in the course of 1498 one session. 1500 Implementations MAY allow a schema to be explicitly passed as a meta- 1501 schema, for implementation-specific purposes, such as pre-loading a 1502 commonly used meta-schema and checking its vocabulary support 1503 requirements up front. Meta-schema authors MUST NOT expect such 1504 features to be interoperable across implementations. 1506 9.2. Dereferencing 1508 Schemas can be identified by any URI that has been given to them, 1509 including a JSON Pointer or their URI given directly by "$id". In 1510 all cases, dereferencing a "$ref" reference involves first resolving 1511 its value as a URI reference against the current base URI per RFC 1512 3986 [RFC3986]. 1514 If the resulting URI identifies a schema within the current document, 1515 or within another schema document that has been made available to the 1516 implementation, then that schema SHOULD be used automatically. 1518 For example, consider this schema: 1520 { 1521 "$id": "https://example.net/root.json", 1522 "items": { 1523 "type": "array", 1524 "items": { "$ref": "#item" } 1525 }, 1526 "$defs": { 1527 "single": { 1528 "$anchor": "item", 1529 "type": "object", 1530 "additionalProperties": { "$ref": "other.json" } 1531 } 1532 } 1533 } 1535 When an implementation encounters the <#/$defs/single> schema, it 1536 resolves the "$anchor" value as a fragment name against the current 1537 base URI to form . 1539 When an implementation then looks inside the <#/items> schema, it 1540 encounters the <#item> reference, and resolves this to 1541 , which it has seen defined in 1542 this same document and can therefore use automatically. 1544 When an implementation encounters the reference to "other.json", it 1545 resolves this to , which is not 1546 defined in this document. If a schema with that identifier has 1547 otherwise been supplied to the implementation, it can also be used 1548 automatically. [[CREF7: What should implementations do when the 1549 referenced schema is not known? Are there circumstances in which 1550 automatic network dereferencing is allowed? A same origin policy? A 1551 user-configurable option? In the case of an evolving API described 1552 by Hyper-Schema, it is expected that new schemas will be added to the 1553 system dynamically, so placing an absolute requirement of pre-loading 1554 schema documents is not feasible. ]] 1556 9.2.1. JSON Pointer fragments and embedded schema resources 1558 Since JSON Pointer URI fragments are constructed based on the 1559 structure of the schema document, an embedded schema resource and its 1560 subschemas can be identified by JSON Pointer fragments relative to 1561 either its own canonical URI, or relative to the containing 1562 resource's URI. 1564 Conceptually, a set of linked schema resources should behave 1565 identically whether each resource is a separate document connected 1566 with schema references (Section 8.2.3), or is structured as a single 1567 document with one or more schema resources embedded as subschemas. 1569 Since URIs involving JSON Pointer fragments relative to the parent 1570 schema resource's URI cease to be valid when the embedded schema is 1571 moved to a separate document and referenced, applications and schemas 1572 SHOULD NOT use such URIs to identify embedded schema resources or 1573 locations within them. 1575 Consider the following schema document that contains another schema 1576 resource embedded within it: 1578 { 1579 "$id": "https://example.com/foo", 1580 "items": { 1581 "$id": "https://example.com/bar", 1582 "additionalProperties": { } 1583 } 1584 } 1586 The URI "https://example.com/foo#/items/additionalProperties" points 1587 to the schema of the "additionalProperties" keyword in the embedded 1588 resource. The canonical URI of that schema, however, is 1589 "https://example.com/bar#/additionalProperties". 1591 Now consider the following two schema resources linked by reference 1592 using a URI value for "$ref": 1594 { 1595 "$id": "https://example.com/foo", 1596 "items": { 1597 "$ref": "bar" 1598 } 1599 } 1601 { 1602 "$id": "https://example.com/bar", 1603 "additionalProperties": { } 1604 } 1606 Here we see that the canonical URI for that "additionalProperties" 1607 subschema is still valid, while the non-canonical URI with the 1608 fragment beginning with "#/items/$ref" now resolves to nothing. 1610 Note also that "https://example.com/foo#/items" is valid in both 1611 arrangements, but resolves to a different value. This URI ends up 1612 functioning similarly to a retrieval URI for a resource. While 1613 valid, examining the resolved value and either using the "$id" (if 1614 the value is a subschema), or resolving the reference and using the 1615 "$id" of the reference target, is preferable. 1617 An implementation MAY choose not to support addressing schemas by 1618 non-canonical URIs. As such, it is RECOMMENDED that schema authors 1619 only use canonical URIs, as using non-canonical URIs may reduce 1620 schema interoperability. [[CREF8: This is to avoid requiring 1621 implementations to keep track of a whole stack of possible base URIs 1622 and JSON Pointer fragments for each, given that all but one will be 1623 fragile if the schema resources are reorganized. Some have argued 1624 that this is easy so there is no point in forbidding it, while others 1625 have argued that it complicates schema identification and should be 1626 forbidden. Feedback on this topic is encouraged. ]] 1628 Further examples of such non-canonical URIs, as well as the 1629 appropriate canonical URIs to use instead, are provided in appendix 1630 A. 1632 9.3. Compound Documents 1634 A Compound Schema Document is defined as a JSON document (sometimes 1635 called a "bundled" schema) which has multiple embedded JSON Schema 1636 Resources bundled into the same document to ease transportation. 1638 Each embedded Schema Resource MUST be treated as an individual Schema 1639 Resource, following standard schema loading and processing 1640 requirements, including determining vocabulary support. 1642 9.3.1. Bundling 1644 The bundling process for creating a Compound Schema Document is 1645 defined as taking references (such as "$ref") to an external Schema 1646 Resource and embedding the referenced Schema Resources within the 1647 referring document. Bundling SHOULD be done in such a way that all 1648 URIs (used for referencing) in the base document and any referenced/ 1649 embedded documents do not require altering. 1651 Each embedded JSON Schema Resource MUST identify itself with a URI 1652 using the "$id" keyword, and SHOULD make use of the "$schema" keyword 1653 to identify the dialect it is using, in the root of the schema 1654 resource. It is RECOMMENDED that the URI identifier value of "$id" 1655 be an Absolute URI. 1657 When the Schema Resource referenced by a by-reference applicator is 1658 bundled, it is RECOMMENDED that the Schema Resource be located as a 1659 value of a "$defs" object at the containing schema's root. The key 1660 of the "$defs" for the now embedded Schema Resource MAY be the "$id" 1661 of the bundled schema or some other form of application defined 1662 unique identifer (such as a UUID). This key is not intended to be 1663 referenced in JSON Schema, but may be used by an application to aid 1664 the bundling process. 1666 A Schema Resource MAY be embedded in a location other than "$defs" 1667 where the location is defined as a schema value. 1669 A Bundled Schema Resource MUST NOT be bundled by replacing the schema 1670 object from which it was referenced, or by wrapping the Schema 1671 Resource in other applicator keywords. 1673 In order to produce identical output, references in the containing 1674 schema document to the previously external Schema Resources MUST NOT 1675 be changed, and now resolve to a schema using the "$id" of an 1676 embedded Schema Resource. Such identical output includes validation 1677 evaluation and URIs or paths used in resulting annotations or errors. 1679 While the bundling process will often be the main method for creating 1680 a Compound Schema Document, it is also possible and expected that 1681 some will be created by hand, potentially without individual Schema 1682 Resources existing on their own previously. 1684 9.3.2. Differing and Default Dialects 1686 When multiple schema resources are present in a single document, 1687 schema resources which do not define with which dialect they should 1688 be processed MUST be processed with the same dialect as the enclosing 1689 resource. 1691 Since any schema that can be referenced can also be embedded, 1692 embedded schema resources MAY specify different processing dialects 1693 using the "$schema" values from their enclosing resource. 1695 9.3.3. Validating 1697 Given that a Compound Schema Document may have embedded resources 1698 which identify as using different dialects, these documents SHOULD 1699 NOT be validated by applying a meta-schema to the Compound Schema 1700 Document as an instance. It is RECOMMENDED that an alternate 1701 validation process be provided in order to validate Schema Documents. 1702 Each Schema Resource SHOULD be separately validated against its 1703 associated meta-schema. [[CREF9: If you know a schema is what's 1704 being validated, you can identify if the schemas is a Compound Schema 1705 Document or not, by way of use of "$id", which identifies an embedded 1706 resource when used not at the document's root. ]] 1708 A Compound Schema Document in which all embedded resources identify 1709 as using the same dialect, or in which "$schema" is omitted and 1710 therefore defaults to that of the enclosing resource, MAY be 1711 validated by applying the appropriate meta-schema. 1713 9.4. Caveats 1715 9.4.1. Guarding Against Infinite Recursion 1717 A schema MUST NOT be run into an infinite loop against an instance. 1718 For example, if two schemas "#alice" and "#bob" both have an "allOf" 1719 property that refers to the other, a naive validator might get stuck 1720 in an infinite recursive loop trying to validate the instance. 1721 Schemas SHOULD NOT make use of infinite recursive nesting like this; 1722 the behavior is undefined. 1724 9.4.2. References to Possible Non-Schemas 1726 Subschema objects (or booleans) are recognized by their use with 1727 known applicator keywords or with location-reserving keywords such as 1728 "$defs" (Section 8.2.4) that take one or more subschemas as a value. 1729 These keywords may be "$defs" and the standard applicators from this 1730 document, or extension keywords from a known vocabulary, or 1731 implementation-specific custom keywords. 1733 Multi-level structures of unknown keywords are capable of introducing 1734 nested subschemas, which would be subject to the processing rules for 1735 "$id". Therefore, having a reference target in such an unrecognized 1736 structure cannot be reliably implemented, and the resulting behavior 1737 is undefined. Similarly, a reference target under a known keyword, 1738 for which the value is known not to be a schema, results in undefined 1739 behavior in order to avoid burdening implementations with the need to 1740 detect such targets. [[CREF10: These scenarios are analogous to 1741 fetching a schema over HTTP but receiving a response with a Content- 1742 Type other than application/schema+json. An implementation can 1743 certainly try to interpret it as a schema, but the origin server 1744 offered no guarantee that it actually is any such thing. Therefore, 1745 interpreting it as such has security implications and may produce 1746 unpredictable results. ]] 1748 Note that single-level custom keywords with identical syntax and 1749 semantics to "$defs" do not allow for any intervening "$id" keywords, 1750 and therefore will behave correctly under implementations that 1751 attempt to use any reference target as a schema. However, this 1752 behavior is implementation-specific and MUST NOT be relied upon for 1753 interoperability. 1755 9.5. Associating Instances and Schemas 1757 9.5.1. Usage for Hypermedia 1759 JSON has been adopted widely by HTTP servers for automated APIs and 1760 robots. This section describes how to enhance processing of JSON 1761 documents in a more RESTful manner when used with protocols that 1762 support media types and Web linking [RFC8288]. 1764 9.5.1.1. Linking to a Schema 1766 It is RECOMMENDED that instances described by a schema provide a link 1767 to a downloadable JSON Schema using the link relation "describedby", 1768 as defined by Linked Data Protocol 1.0, section 8.1 1769 [W3C.REC-ldp-20150226]. 1771 In HTTP, such links can be attached to any response using the Link 1772 header [RFC8288]. An example of such a header would be: 1774 Link: ; rel="describedby" 1776 9.5.1.2. Usage Over HTTP 1778 When used for hypermedia systems over a network, HTTP [RFC7231] is 1779 frequently the protocol of choice for distributing schemas. 1780 Misbehaving clients can pose problems for server maintainers if they 1781 pull a schema over the network more frequently than necessary, when 1782 it's instead possible to cache a schema for a long period of time. 1784 HTTP servers SHOULD set long-lived caching headers on JSON Schemas. 1785 HTTP clients SHOULD observe caching headers and not re-request 1786 documents within their freshness period. Distributed systems SHOULD 1787 make use of a shared cache and/or caching proxy. 1789 Clients SHOULD set or prepend a User-Agent header specific to the 1790 JSON Schema implementation or software product. Since symbols are 1791 listed in decreasing order of significance, the JSON Schema library 1792 name/version should precede the more generic HTTP library name (if 1793 any). For example: 1795 User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 1797 Clients SHOULD be able to make requests with a "From" header so that 1798 server operators can contact the owner of a potentially misbehaving 1799 script. 1801 10. A Vocabulary for Applying Subschemas 1803 This section defines a vocabulary of applicator keywords that are 1804 RECOMMENDED for use as the basis of other vocabularies. 1806 Meta-schemas that do not use "$vocabulary" SHOULD be considered to 1807 require this vocabulary as if its URI were present with a value of 1808 true. 1810 The current URI for this vocabulary, known as the Applicator 1811 vocabulary, is: . 1814 The current URI for the corresponding meta-schema is: . 1817 Updated vocabulary and meta-schema URIs MAY be published between 1818 specification drafts in order to correct errors. Implementations 1819 SHOULD consider URIs dated after this specification draft and before 1820 the next to indicate the same syntax and semantics as those listed 1821 here. 1823 10.1. Keyword Independence 1825 Schema keywords typically operate independently, without affecting 1826 each other's outcomes. 1828 For schema author convenience, there are some exceptions among the 1829 keywords in this vocabulary: 1831 "additionalProperties", whose behavior is defined in terms of 1832 "properties" and "patternProperties" 1834 "items", whose behavior is defined in terms of "prefixItems" 1836 "contains", whose behavior is defined in terms of "minContains" 1838 10.2. Keywords for Applying Subschemas in Place 1840 These keywords apply subschemas to the same location in the instance 1841 as the parent schema is being applied. They allow combining or 1842 modifying the subschema results in various ways. 1844 Subschemas of these keywords evaluate the instance completely 1845 independently such that the results of one such subschema MUST NOT 1846 impact the results of sibling subschemas. Therefore subschemas may 1847 be applied in any order. 1849 10.2.1. Keywords for Applying Subschemas With Logic 1851 These keywords correspond to logical operators for combining or 1852 modifying the boolean assertion results of the subschemas. They have 1853 no direct impact on annotation collection, although they enable the 1854 same annotation keyword to be applied to an instance location with 1855 different values. Annotation keywords define their own rules for 1856 combining such values. 1858 10.2.1.1. allOf 1860 This keyword's value MUST be a non-empty array. Each item of the 1861 array MUST be a valid JSON Schema. 1863 An instance validates successfully against this keyword if it 1864 validates successfully against all schemas defined by this keyword's 1865 value. 1867 10.2.1.2. anyOf 1869 This keyword's value MUST be a non-empty array. Each item of the 1870 array MUST be a valid JSON Schema. 1872 An instance validates successfully against this keyword if it 1873 validates successfully against at least one schema defined by this 1874 keyword's value. Note that when annotations are being collected, all 1875 subschemas MUST be examined so that annotations are collected from 1876 each subschema that validates successfully. 1878 10.2.1.3. oneOf 1880 This keyword's value MUST be a non-empty array. Each item of the 1881 array MUST be a valid JSON Schema. 1883 An instance validates successfully against this keyword if it 1884 validates successfully against exactly one schema defined by this 1885 keyword's value. 1887 10.2.1.4. not 1889 This keyword's value MUST be a valid JSON Schema. 1891 An instance is valid against this keyword if it fails to validate 1892 successfully against the schema defined by this keyword. 1894 10.2.2. Keywords for Applying Subschemas Conditionally 1896 Three of these keywords work together to implement conditional 1897 application of a subschema based on the outcome of another subschema. 1898 The fourth is a shortcut for a specific conditional case. 1900 "if", "then", and "else" MUST NOT interact with each other across 1901 subschema boundaries. In other words, an "if" in one branch of an 1902 "allOf" MUST NOT have an impact on a "then" or "else" in another 1903 branch. 1905 There is no default behavior for "if", "then", or "else" when they 1906 are not present. In particular, they MUST NOT be treated as if 1907 present with an empty schema, and when "if" is not present, both 1908 "then" and "else" MUST be entirely ignored. 1910 10.2.2.1. if 1912 This keyword's value MUST be a valid JSON Schema. 1914 This validation outcome of this keyword's subschema has no direct 1915 effect on the overall validation result. Rather, it controls which 1916 of the "then" or "else" keywords are evaluated. 1918 Instances that successfully validate against this keyword's subschema 1919 MUST also be valid against the subschema value of the "then" keyword, 1920 if present. 1922 Instances that fail to validate against this keyword's subschema MUST 1923 also be valid against the subschema value of the "else" keyword, if 1924 present. 1926 If annotations (Section 7.7) are being collected, they are collected 1927 from this keyword's subschema in the usual way, including when the 1928 keyword is present without either "then" or "else". 1930 10.2.2.2. then 1932 This keyword's value MUST be a valid JSON Schema. 1934 When "if" is present, and the instance successfully validates against 1935 its subschema, then validation succeeds against this keyword if the 1936 instance also successfully validates against this keyword's 1937 subschema. 1939 This keyword has no effect when "if" is absent, or when the instance 1940 fails to validate against its subschema. Implementations MUST NOT 1941 evaluate the instance against this keyword, for either validation or 1942 annotation collection purposes, in such cases. 1944 10.2.2.3. else 1946 This keyword's value MUST be a valid JSON Schema. 1948 When "if" is present, and the instance fails to validate against its 1949 subschema, then validation succeeds against this keyword if the 1950 instance successfully validates against this keyword's subschema. 1952 This keyword has no effect when "if" is absent, or when the instance 1953 successfully validates against its subschema. Implementations MUST 1954 NOT evaluate the instance against this keyword, for either validation 1955 or annotation collection purposes, in such cases. 1957 10.2.2.4. dependentSchemas 1959 This keyword specifies subschemas that are evaluated if the instance 1960 is an object and contains a certain property. 1962 This keyword's value MUST be an object. Each value in the object 1963 MUST be a valid JSON Schema. 1965 If the object key is a property in the instance, the entire instance 1966 must validate against the subschema. Its use is dependent on the 1967 presence of the property. 1969 Omitting this keyword has the same behavior as an empty object. 1971 10.3. Keywords for Applying Subschemas to Child Instances 1973 Each of these keywords defines a rule for applying its subschema(s) 1974 to child instances, specifically object properties and array items, 1975 and combining their results. 1977 10.3.1. Keywords for Applying Subschemas to Arrays 1979 10.3.1.1. prefixItems 1981 The value of "prefixItems" MUST be a non-empty array of valid JSON 1982 Schemas. 1984 Validation succeeds if each element of the instance validates against 1985 the schema at the same position, if any. This keyword does not 1986 constrain the length of the array. If the array is longer than this 1987 keyword's value, this keyword validates only the prefix of matching 1988 length. 1990 This keyword produces an annotation value which is the largest index 1991 to which this keyword applied a subschema. The value MAY be a 1992 boolean true if a subschema was applied to every index of the 1993 instance, such as is produced by the "items" keyword. This 1994 annotation affects the behavior of "items" and "unevaluatedItems". 1996 Omitting this keyword has the same assertion behavior as an empty 1997 array. 1999 10.3.1.2. items 2001 The value of "items" MUST be a valid JSON Schema. 2003 This keyword applies its subschema to all instance elements at 2004 indexes greater than the length of the "prefixItems" array in the 2005 same schema object, as reported by the annotation result of that 2006 "prefixItems" keyword. If no such annotation result exists, "items" 2007 applies its subschema to all instance array elements. [[CREF11: Note 2008 that the behavior of "items" without "prefixItems" is identical to 2009 that of the schema form of "items" in prior drafts. When 2010 "prefixItems" is present, the behavior of "items" is identical to the 2011 former "additionalItems" keyword. ]] 2013 If the "items" subschema is applied to any positions within the 2014 instance array, it produces an annotation result of boolean true, 2015 indicating that all remaining array elements have been evaluated 2016 against this keyword's subschema. 2018 Omitting this keyword has the same assertion behavior as an empty 2019 schema. 2021 Implementations MAY choose to implement or optimize this keyword in 2022 another way that produces the same effect, such as by directly 2023 checking for the presence and size of a "prefixItems" array. 2024 Implementations that do not support annotation collection MUST do so. 2026 10.3.1.3. contains 2028 The value of this keyword MUST be a valid JSON Schema. 2030 An array instance is valid against "contains" if at least one of its 2031 elements is valid against the given schema. The subschema MUST be 2032 applied to every array element even after the first match has been 2033 found, in order to collect annotations for use by other keywords. 2034 This is to ensure that all possible annotations are collected. 2036 Logically, the validation result of applying the value subschema to 2037 each item in the array MUST be ORed with "false", resulting in an 2038 overall validation result. 2040 This keyword produces an annotation value which is an array of the 2041 indexes to which this keyword validates successfully when applying 2042 its subschema, in ascending order. The value MAY be a boolean "true" 2043 if the subschema validates successfully when applied to every index 2044 of the instance. The annotation MUST be present if the instance 2045 array to which this keyword's schema applies is empty. 2047 10.3.2. Keywords for Applying Subschemas to Objects 2049 10.3.2.1. properties 2051 The value of "properties" MUST be an object. Each value of this 2052 object MUST be a valid JSON Schema. 2054 Validation succeeds if, for each name that appears in both the 2055 instance and as a name within this keyword's value, the child 2056 instance for that name successfully validates against the 2057 corresponding schema. 2059 The annotation result of this keyword is the set of instance property 2060 names matched by this keyword. 2062 Omitting this keyword has the same assertion behavior as an empty 2063 object. 2065 10.3.2.2. patternProperties 2067 The value of "patternProperties" MUST be an object. Each property 2068 name of this object SHOULD be a valid regular expression, according 2069 to the ECMA-262 regular expression dialect. Each property value of 2070 this object MUST be a valid JSON Schema. 2072 Validation succeeds if, for each instance name that matches any 2073 regular expressions that appear as a property name in this keyword's 2074 value, the child instance for that name successfully validates 2075 against each schema that corresponds to a matching regular 2076 expression. 2078 The annotation result of this keyword is the set of instance property 2079 names matched by this keyword. 2081 Omitting this keyword has the same assertion behavior as an empty 2082 object. 2084 10.3.2.3. additionalProperties 2086 The value of "additionalProperties" MUST be a valid JSON Schema. 2088 The behavior of this keyword depends on the presence and annotation 2089 results of "properties" and "patternProperties" within the same 2090 schema object. Validation with "additionalProperties" applies only 2091 to the child values of instance names that do not appear in the 2092 annotation results of either "properties" or "patternProperties". 2094 For all such properties, validation succeeds if the child instance 2095 validates against the "additionalProperties" schema. 2097 The annotation result of this keyword is the set of instance property 2098 names validated by this keyword's subschema. 2100 Omitting this keyword has the same assertion behavior as an empty 2101 schema. 2103 Implementations MAY choose to implement or optimize this keyword in 2104 another way that produces the same effect, such as by directly 2105 checking the names in "properties" and the patterns in 2106 "patternProperties" against the instance property set. 2107 Implementations that do not support annotation collection MUST do so. 2109 10.3.2.4. propertyNames 2111 The value of "propertyNames" MUST be a valid JSON Schema. 2113 If the instance is an object, this keyword validates if every 2114 property name in the instance validates against the provided schema. 2115 Note the property name that the schema is testing will always be a 2116 string. 2118 Omitting this keyword has the same behavior as an empty schema. 2120 11. A Vocabulary for Unevaluated Locations 2122 The purpose of these keywords is to enable schema authors to apply 2123 subschemas to array items or object properties that have not been 2124 successfully evaluated against any dynamic-scope subschema of any 2125 adjacent keywords. 2127 These instance items or properties may have been unsuccessfully 2128 evaluated against one or more adjacent keyword subschemas, such as 2129 when an assertion in a branch of an "anyOf" fails. Such failed 2130 evaluations are not considered to contribute to whether or not the 2131 item or property has been evaluated. Only successful evaluations are 2132 considered. 2134 If an item in an array or an object property is "successfully 2135 evaluated", it is logically considered to be valid in terms of the 2136 representation of the object or array that's expected. For example 2137 if a subschema represents a car, which requires between 2-4 wheels, 2138 and the value of "wheels" is 6, the instance object is not 2139 "evaluated" to be a car, and the "wheels" property is considered 2140 "unevaluated (successfully as a known thing)", and does not retain 2141 any annotations. 2143 Recall that adjacent keywords are keywords within the same schema 2144 object, and that the dynamic-scope subschemas include reference 2145 targets as well as lexical subschemas. 2147 The behavior of these keywords depend on the annotation results of 2148 adjacent keywords that apply to the instance location being 2149 validated. 2151 Meta-schemas that do not use "$vocabulary" SHOULD be considered to 2152 require this vocabulary as if its URI were present with a value of 2153 true. 2155 The current URI for this vocabulary, known as the Unevaluated 2156 Applicator vocabulary, is: . 2159 The current URI for the corresponding meta-schema is: . 2162 Updated vocabulary and meta-schema URIs MAY be published between 2163 specification drafts in order to correct errors. Implementations 2164 SHOULD consider URIs dated after this specification draft and before 2165 the next to indicate the same syntax and semantics as those listed 2166 here. 2168 11.1. Keyword Independence 2170 Schema keywords typically operate independently, without affecting 2171 each other's outcomes. However, the keywords in this vocabulary are 2172 notable exceptions: 2174 "unevaluatedItems", whose behavior is defined in terms of 2175 annotations from "prefixItems", "items", "contains", and itself 2176 "unevaluatedProperties", whose behavior is defined in terms of 2177 annotations from "properties", "patternProperties", 2178 "additionalProperties" and itself 2180 11.2. unevaluatedItems 2182 The value of "unevaluatedItems" MUST be a valid JSON Schema. 2184 The behavior of this keyword depends on the annotation results of 2185 adjacent keywords that apply to the instance location being 2186 validated. Specifically, the annotations from "prefixItems", 2187 "items", and "contains", which can come from those keywords when they 2188 are adjacent to the "unevaluatedItems" keyword. Those three 2189 annotations, as well as "unevaluatedItems", can also result from any 2190 and all adjacent in-place applicator (Section 10.2) keywords. This 2191 includes but is not limited to the in-place applicators defined in 2192 this document. 2194 If no relevant annotations are present, the "unevaluatedItems" 2195 subschema MUST be applied to all locations in the array. If a 2196 boolean true value is present from any of the relevant annotations, 2197 "unevaluatedItems" MUST be ignored. Otherwise, the subschema MUST be 2198 applied to any index greater than the largest annotation value for 2199 "prefixItems", which does not appear in any annotation value for 2200 "contains". 2202 This means that "prefixItems", "items", "contains", and all in-place 2203 applicators MUST be evaluated before this keyword can be evaluated. 2204 Authors of extension keywords MUST NOT define an in-place applicator 2205 that would need to be evaluated after this keyword. 2207 If the "unevaluatedItems" subschema is applied to any positions 2208 within the instance array, it produces an annotation result of 2209 boolean true, analogous to the behavior of "items". 2211 Omitting this keyword has the same assertion behavior as an empty 2212 schema. 2214 11.3. unevaluatedProperties 2216 The value of "unevaluatedProperties" MUST be a valid JSON Schema. 2218 The behavior of this keyword depends on the annotation results of 2219 adjacent keywords that apply to the instance location being 2220 validated. Specifically, the annotations from "properties", 2221 "patternProperties", and "additionalProperties", which can come from 2222 those keywords when they are adjacent to the "unevaluatedProperties" 2223 keyword. Those three annotations, as well as 2224 "unevaluatedProperties", can also result from any and all adjacent 2225 in-place applicator (Section 10.2) keywords. This includes but is 2226 not limited to the in-place applicators defined in this document. 2228 Validation with "unevaluatedProperties" applies only to the child 2229 values of instance names that do not appear in the "properties", 2230 "patternProperties", "additionalProperties", or 2231 "unevaluatedProperties" annotation results that apply to the instance 2232 location being validated. 2234 For all such properties, validation succeeds if the child instance 2235 validates against the "unevaluatedProperties" schema. 2237 This means that "properties", "patternProperties", 2238 "additionalProperties", and all in-place applicators MUST be 2239 evaluated before this keyword can be evaluated. Authors of extension 2240 keywords MUST NOT define an in-place applicator that would need to be 2241 evaluated after this keyword. 2243 The annotation result of this keyword is the set of instance property 2244 names validated by this keyword's subschema. 2246 Omitting this keyword has the same assertion behavior as an empty 2247 schema. 2249 12. Output Formatting 2251 JSON Schema is defined to be platform-independent. As such, to 2252 increase compatibility across platforms, implementations SHOULD 2253 conform to a standard validation output format. This section 2254 describes the minimum requirements that consumers will need to 2255 properly interpret validation results. 2257 12.1. Format 2259 JSON Schema output is defined using the JSON Schema data instance 2260 model as described in section 4.2.1. Implementations MAY deviate 2261 from this as supported by their specific languages and platforms, 2262 however it is RECOMMENDED that the output be convertible to the JSON 2263 format defined herein via serialization or other means. 2265 12.2. Output Formats 2267 This specification defines four output formats. See the "Output 2268 Structure" section for the requirements of each format. 2270 Flag - A boolean which simply indicates the overall validation 2271 result with no further details. 2273 Basic - Provides validation information in a flat list structure. 2275 Detailed - Provides validation information in a condensed 2276 hierarchical structure based on the structure of the schema. 2278 Verbose - Provides validation information in an uncondensed 2279 hierarchical structure that matches the exact structure of the 2280 schema. 2282 An implementation SHOULD provide at least one of the "flag", "basic", 2283 or "detailed" format and MAY provide the "verbose" format. If it 2284 provides one or more of the "detailed" or "verbose" formats, it MUST 2285 also provide the "flag" format. Implementations SHOULD specify in 2286 their documentation which formats they support. 2288 12.3. Minimum Information 2290 Beyond the simplistic "flag" output, additional information is useful 2291 to aid in debugging a schema or instance. Each sub-result SHOULD 2292 contain the information contained within this section at a minimum. 2294 A single object that contains all of these components is considered 2295 an output unit. 2297 Implementations MAY elect to provide additional information. 2299 12.3.1. Keyword Relative Location 2301 The relative location of the validating keyword that follows the 2302 validation path. The value MUST be expressed as a JSON Pointer, and 2303 it MUST include any by-reference applicators such as "$ref" or 2304 "$dynamicRef". 2306 #/properties/width/$ref/minimum 2308 Note that this pointer may not be resolvable by the normal JSON 2309 Pointer process due to the inclusion of these by-reference applicator 2310 keywords. 2312 The JSON key for this information is "keywordLocation". 2314 12.3.2. Keyword Absolute Location 2316 The absolute, dereferenced location of the validating keyword. The 2317 value MUST be expressed as a full URI using the canonical URI of the 2318 relevant schema object, and it MUST NOT include by-reference 2319 applicators such as "$ref" or "$dynamicRef" as non-terminal path 2320 components. It MAY end in such keywords if the error or annotation 2321 is for that keyword, such as an unresolvable reference. [[CREF12: 2322 Note that "absolute" here is in the sense of "absolute filesystem 2323 path" (meaning the complete location) rather than the "absolute-URI" 2324 terminology from RFC 3986 (meaning with scheme but without fragment). 2325 Keyword absolute locations will have a fragment in order to identify 2326 the keyword. ]] 2328 https://example.com/schemas/common#/$defs/count/minimum 2330 This information MAY be omitted only if either the dynamic scope did 2331 not pass over a reference or if the schema does not declare an 2332 absolute URI as its "$id". 2334 The JSON key for this information is "absoluteKeywordLocation". 2336 12.3.3. Instance Location 2338 The location of the JSON value within the instance being validated. 2339 The value MUST be expressed as a JSON Pointer. 2341 The JSON key for this information is "instanceLocation". 2343 12.3.4. Error or Annotation 2345 The error or annotation that is produced by the validation. 2347 For errors, the specific wording for the message is not defined by 2348 this specification. Implementations will need to provide this. 2350 For annotations, each keyword that produces an annotation specifies 2351 its format. By default, it is the keyword's value. 2353 The JSON key for failed validations is "error"; for successful 2354 validations it is "annotation". 2356 12.3.5. Nested Results 2358 For the two hierarchical structures, this property will hold nested 2359 errors and annotations. 2361 The JSON key for nested results in failed validations is "errors"; 2362 for successful validations it is "annotations". Note the plural 2363 forms, as a keyword with nested results can also have a local error 2364 or annotation. 2366 12.4. Output Structure 2368 The output MUST be an object containing a boolean property named 2369 "valid". When additional information about the result is required, 2370 the output MUST also contain "errors" or "annotations" as described 2371 below. 2373 "valid" - a boolean value indicating the overall validation 2374 success or failure 2376 "errors" - the collection of errors or annotations produced by a 2377 failed validation 2379 "annotations" - the collection of errors or annotations produced 2380 by a successful validation 2382 For these examples, the following schema and instance will be used. 2384 { 2385 "$id": "https://example.com/polygon", 2386 "$schema": "https://json-schema.org/draft/2020-12/schema", 2387 "$defs": { 2388 "point": { 2389 "type": "object", 2390 "properties": { 2391 "x": { "type": "number" }, 2392 "y": { "type": "number" } 2393 }, 2394 "additionalProperties": false, 2395 "required": [ "x", "y" ] 2396 } 2397 }, 2398 "type": "array", 2399 "items": { "$ref": "#/$defs/point" }, 2400 "minItems": 3 2401 } 2403 [ 2404 { 2405 "x": 2.5, 2406 "y": 1.3 2407 }, 2408 { 2409 "x": 1, 2410 "z": 6.7 2411 } 2412 ] 2414 This instance will fail validation and produce errors, but it's 2415 trivial to deduce examples for passing schemas that produce 2416 annotations. 2418 Specifically, the errors it will produce are: 2420 The second object is missing a "y" property. 2422 The second object has a disallowed "z" property. 2424 There are only two objects, but three are required. 2426 Note that the error message wording as depicted in these examples is 2427 not a requirement of this specification. Implementations SHOULD 2428 craft error messages tailored for their audience or provide a 2429 templating mechanism that allows their users to craft their own 2430 messages. 2432 12.4.1. Flag 2434 In the simplest case, merely the boolean result for the "valid" valid 2435 property needs to be fulfilled. 2437 { 2438 "valid": false 2439 } 2441 Because no errors or annotations are returned with this format, it is 2442 RECOMMENDED that implementations use short-circuiting logic to return 2443 failure or success as soon as the outcome can be determined. For 2444 example, if an "anyOf" keyword contains five sub-schemas, and the 2445 second one passes, there is no need to check the other three. The 2446 logic can simply return with success. 2448 12.4.2. Basic 2450 The "Basic" structure is a flat list of output units. 2452 { 2453 "valid": false, 2454 "errors": [ 2455 { 2456 "keywordLocation": "", 2457 "instanceLocation": "", 2458 "error": "A subschema had errors." 2459 }, 2460 { 2461 "keywordLocation": "/items/$ref", 2462 "absoluteKeywordLocation": 2463 "https://example.com/polygon#/$defs/point", 2464 "instanceLocation": "/1", 2465 "error": "A subschema had errors." 2466 }, 2467 { 2468 "keywordLocation": "/items/$ref/required", 2469 "absoluteKeywordLocation": 2470 "https://example.com/polygon#/$defs/point/required", 2471 "instanceLocation": "/1", 2472 "error": "Required property 'y' not found." 2473 }, 2474 { 2475 "keywordLocation": "/items/$ref/additionalProperties", 2476 "absoluteKeywordLocation": 2477 "https://example.com/polygon#/$defs/point/additionalProperties", 2478 "instanceLocation": "/1/z", 2479 "error": "Additional property 'z' found but was invalid." 2480 }, 2481 { 2482 "keywordLocation": "/minItems", 2483 "instanceLocation": "", 2484 "error": "Expected at least 3 items but found 2" 2485 } 2486 ] 2487 } 2489 12.4.3. Detailed 2491 The "Detailed" structure is based on the schema and can be more 2492 readable for both humans and machines. Having the structure 2493 organized this way makes associations between the errors more 2494 apparent. For example, the fact that the missing "y" property and 2495 the extra "z" property both stem from the same location in the 2496 instance is not immediately obvious in the "Basic" structure. In a 2497 hierarchy, the correlation is more easily identified. 2499 The following rules govern the construction of the results object: 2501 All applicator keywords ("*Of", "$ref", "if"/"then"/"else", etc.) 2502 require a node. 2504 Nodes that have no children are removed. 2506 Nodes that have a single child are replaced by the child. 2508 Branch nodes do not require an error message or an annotation. 2510 { 2511 "valid": false, 2512 "keywordLocation": "", 2513 "instanceLocation": "", 2514 "errors": [ 2515 { 2516 "valid": false, 2517 "keywordLocation": "/items/$ref", 2518 "absoluteKeywordLocation": 2519 "https://example.com/polygon#/$defs/point", 2520 "instanceLocation": "/1", 2521 "errors": [ 2522 { 2523 "valid": false, 2524 "keywordLocation": "/items/$ref/required", 2525 "absoluteKeywordLocation": 2526 "https://example.com/polygon#/$defs/point/required", 2527 "instanceLocation": "/1", 2528 "error": "Required property 'y' not found." 2529 }, 2530 { 2531 "valid": false, 2532 "keywordLocation": "/items/$ref/additionalProperties", 2533 "absoluteKeywordLocation": 2534 "https://example.com/polygon#/$defs/point/additionalProperties", 2535 "instanceLocation": "/1/z", 2536 "error": "Additional property 'z' found but was invalid." 2537 } 2538 ] 2539 }, 2540 { 2541 "valid": false, 2542 "keywordLocation": "/minItems", 2543 "instanceLocation": "", 2544 "error": "Expected at least 3 items but found 2" 2545 } 2546 ] 2547 } 2549 12.4.4. Verbose 2551 The "Verbose" structure is a fully realized hierarchy that exactly 2552 matches that of the schema. This structure has applications in form 2553 generation and validation where the error's location is important. 2555 The primary difference between this and the "Detailed" structure is 2556 that all results are returned. This includes sub-schema validation 2557 results that would otherwise be removed (e.g. annotations for failed 2558 validations, successful validations inside a `not` keyword, etc.). 2559 Because of this, it is RECOMMENDED that each node also carry a 2560 `valid` property to indicate the validation result for that node. 2562 Because this output structure can be quite large, a smaller example 2563 is given here for brevity. The URI of the full output structure of 2564 the example above is: . 2567 // schema 2568 { 2569 "$id": "https://example.com/polygon", 2570 "$schema": "https://json-schema.org/draft/2020-12/schema", 2571 "type": "object", 2572 "properties": { 2573 "validProp": true, 2574 }, 2575 "additionalProperties": false 2576 } 2578 // instance 2579 { 2580 "validProp": 5, 2581 "disallowedProp": "value" 2582 } 2584 // result 2585 { 2586 "valid": false, 2587 "keywordLocation": "", 2588 "instanceLocation": "", 2589 "errors": [ 2590 { 2591 "valid": true, 2592 "keywordLocation": "/type", 2593 "instanceLocation": "" 2594 }, 2595 { 2596 "valid": true, 2597 "keywordLocation": "/properties", 2598 "instanceLocation": "" 2599 }, 2600 { 2601 "valid": false, 2602 "keywordLocation": "/additionalProperties", 2603 "instanceLocation": "", 2604 "errors": [ 2605 { 2606 "valid": false, 2607 "keywordLocation": "/additionalProperties", 2608 "instanceLocation": "/disallowedProp", 2609 "error": "Additional property 'disallowedProp' found but was invalid." 2610 } 2611 ] 2612 } 2613 ] 2614 } 2616 12.4.5. Output validation schemas 2618 For convenience, JSON Schema has been provided to validate output 2619 generated by implementations. Its URI is: . 2622 13. Security Considerations 2624 Both schemas and instances are JSON values. As such, all security 2625 considerations defined in RFC 8259 [RFC8259] apply. 2627 Instances and schemas are both frequently written by untrusted third 2628 parties, to be deployed on public Internet servers. Validators 2629 should take care that the parsing and validating against schemas does 2630 not consume excessive system resources. Validators MUST NOT fall 2631 into an infinite loop. 2633 A malicious party could cause an implementation to repeatedly collect 2634 a copy of a very large value as an annotation. Implementations 2635 SHOULD guard against excessive consumption of system resources in 2636 such a scenario. 2638 Servers MUST ensure that malicious parties cannot change the 2639 functionality of existing schemas by uploading a schema with a pre- 2640 existing or very similar "$id". 2642 Individual JSON Schema vocabularies are liable to also have their own 2643 security considerations. Consult the respective specifications for 2644 more information. 2646 Schema authors should take care with "$comment" contents, as a 2647 malicious implementation can display them to end-users in violation 2648 of a spec, or fail to strip them if such behavior is expected. 2650 A malicious schema author could place executable code or other 2651 dangerous material within a "$comment". Implementations MUST NOT 2652 parse or otherwise take action based on "$comment" contents. 2654 14. IANA Considerations 2656 14.1. application/schema+json 2658 The proposed MIME media type for JSON Schema is defined as follows: 2660 Type name: application 2662 Subtype name: schema+json 2664 Required parameters: N/A 2666 Optional parameters: 2668 schema: A non-empty list of space-separated URIs, each 2669 identifying a JSON Schema resource. The instance SHOULD 2670 successfully validate against at least one of these meta- 2671 schemas. Non-validating meta-schemas MAY be included for 2672 purposes such as allowing clients to make use of older versions 2673 of a meta-schema as long as the runtime instance validates 2674 against that older version. 2676 Encoding considerations: Encoding considerations are identical to 2677 those specified for the "application/json" media type. See JSON 2678 [RFC8259]. 2680 Security considerations: See Section 13 above. 2682 Interoperability considerations: See Sections 6.2, 6.3, and 6.4 2683 above. 2685 Fragment identifier considerations: See Section 5 2687 14.2. application/schema-instance+json 2689 The proposed MIME media type for JSON Schema Instances that require a 2690 JSON Schema-specific media type is defined as follows: 2692 Type name: application 2694 Subtype name: schema-instance+json 2696 Required parameters: 2698 schema: A non-empty list of space-separated URIs, each 2699 identifying a JSON Schema resource. The instance SHOULD 2700 successfully validate against at least one of these schemas. 2701 Non-validating schemas MAY be included for purposes such as 2702 allowing clients to make use of older versions of a schema as 2703 long as the runtime instance validates against that older 2704 version. 2706 Encoding considerations: Encoding considerations are identical to 2707 those specified for the "application/json" media type. See JSON 2708 [RFC8259]. 2710 Security considerations: See Section 13 above. 2712 Interoperability considerations: See Sections 6.2, 6.3, and 6.4 2713 above. 2715 Fragment identifier considerations: See Section 5 2717 15. References 2719 15.1. Normative References 2721 [ecma262] "ECMA-262, 11th edition specification", June 2020, 2722 . 2725 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2726 Requirement Levels", BCP 14, RFC 2119, 2727 DOI 10.17487/RFC2119, March 1997, 2728 . 2730 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2731 Resource Identifier (URI): Generic Syntax", STD 66, 2732 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2733 . 2735 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 2736 Structured Syntax Suffixes", RFC 6839, 2737 DOI 10.17487/RFC6839, January 2013, 2738 . 2740 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 2741 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 2742 DOI 10.17487/RFC6901, April 2013, 2743 . 2745 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2746 Interchange Format", STD 90, RFC 8259, 2747 DOI 10.17487/RFC8259, December 2017, 2748 . 2750 [W3C.REC-ldp-20150226] 2751 Speicher, S., Arwe, J., and A. Malhotra, "Linked Data 2752 Platform 1.0", World Wide Web Consortium Recommendation 2753 REC-ldp-20150226, February 2015, 2754 . 2756 15.2. Informative References 2758 [json-hyper-schema] 2759 Andrews, H. and A. Wright, "JSON Hyper-Schema: A 2760 Vocabulary for Hypermedia Annotation of JSON", draft- 2761 handrews-json-schema-hyperschema-02 (work in progress), 2762 November 2017. 2764 [json-schema-validation] 2765 Wright, A., Andrews, H., and B. Hutton, "JSON Schema 2766 Validation: A Vocabulary for Structural Validation of 2767 JSON", draft-bhutton-json-schema-validation-00 (work in 2768 progress), December 2020. 2770 [RFC6596] Ohye, M. and J. Kupke, "The Canonical Link Relation", 2771 RFC 6596, DOI 10.17487/RFC6596, April 2012, 2772 . 2774 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2775 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2776 October 2013, . 2778 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2779 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 2780 DOI 10.17487/RFC7231, June 2014, 2781 . 2783 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 2784 DOI 10.17487/RFC8288, October 2017, 2785 . 2787 [W3C.WD-fragid-best-practices-20121025] 2788 Tennison, J., "Best Practices for Fragment Identifiers and 2789 Media Type Definitions", World Wide Web Consortium WD WD- 2790 fragid-best-practices-20121025, October 2012, 2791 . 2794 [xml-names] 2795 Bray, T., Ed., Hollander, D., Ed., Layman, A., Ed., and R. 2796 Tobin, Ed., "Namespaces in XML 1.1 (Second Edition)", 2797 August 2006, 2798 . 2800 Appendix A. Schema identification examples 2802 Consider the following schema, which shows "$id" being used to 2803 identify both the root schema and various subschemas, and "$anchor" 2804 being used to define plain name fragment identifiers. 2806 { 2807 "$id": "https://example.com/root.json", 2808 "$defs": { 2809 "A": { "$anchor": "foo" }, 2810 "B": { 2811 "$id": "other.json", 2812 "$defs": { 2813 "X": { "$anchor": "bar" }, 2814 "Y": { 2815 "$id": "t/inner.json", 2816 "$anchor": "bar" 2817 } 2818 } 2819 }, 2820 "C": { 2821 "$id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f" 2822 } 2823 } 2824 } 2826 The schemas at the following URI-encoded JSON Pointers [RFC6901] 2827 (relative to the root schema) have the following base URIs, and are 2828 identifiable by any listed URI in accordance with sections 5 and 2829 9.2.1 above. 2831 # (document root) 2833 canonical absolute-URI (and also base URI) https://example.com/ 2834 root.json 2836 canonical URI with pointer fragment https://example.com/ 2837 root.json# 2839 #/$defs/A 2841 base URI https://example.com/root.json 2843 canonical URI with plain fragment https://example.com/ 2844 root.json#foo 2846 canonical URI with pointer fragment 2847 https://example.com/root.json#/$defs/A 2849 #/$defs/B 2851 base URI https://example.com/other.json 2853 canonical URI with pointer fragment https://example.com/ 2854 other.json# 2856 non-canonical URI with fragment relative to root.json 2857 https://example.com/root.json#/$defs/B 2859 #/$defs/B/$defs/X 2861 base URI https://example.com/other.json 2863 canonical URI with plain fragment https://example.com/ 2864 other.json#bar 2866 canonical URI with pointer fragment 2867 https://example.com/other.json#/$defs/X 2869 non-canonical URI with fragment relative to root.json 2870 https://example.com/root.json#/$defs/B/$defs/X 2872 #/$defs/B/$defs/Y 2874 base URI https://example.com/t/inner.json 2876 canonical URI with plain fragment https://example.com/t/ 2877 inner.json#bar 2879 canonical URI with pointer fragment https://example.com/t/ 2880 inner.json# 2882 non-canonical URI with fragment relative to other.json 2883 https://example.com/other.json#/$defs/Y 2885 non-canonical URI with fragment relative to root.json 2886 https://example.com/root.json#/$defs/B/$defs/Y 2888 #/$defs/C 2890 base URI urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f 2892 canonical URI with pointer fragment urn:uuid:ee564b8a- 2893 7a87-4125-8c96-e9f123d6766f# 2895 non-canonical URI with fragment relative to root.json 2896 https://example.com/root.json#/$defs/C 2898 Appendix B. Manipulating schema documents and references 2900 Various tools have been created to rearrange schema documents based 2901 on how and where references ("$ref") appear. This appendix discusses 2902 which use cases and actions are compliant with this specification. 2904 B.1. Bundling schema resources into a single document 2906 A set of schema resources intended for use together can be organized 2907 with each in its own schema document, all in the same schema 2908 document, or any granularity of document grouping in between. 2910 Numerous tools exist to perform various sorts of reference removal. 2911 A common case of this is producing a single file where all references 2912 can be resolved within that file. This is typically done to simplify 2913 distribution, or to simplify coding so that various invocations of 2914 JSON Schema libraries do not have to keep track of and load a large 2915 number of resources. 2917 This transformation can be safely and reversibly done as long as all 2918 static references (e.g. "$ref") use URI-references that resolve to 2919 canonical URIs, and all schema resources have an absolute-URI as the 2920 "$id" in their root schema. 2922 With these conditions met, each external resource can be copied under 2923 "$defs", without breaking any references among the resources' schema 2924 objects, and without changing any aspect of validation or annotation 2925 results. The names of the schemas under "$defs" do not affect 2926 behavior, assuming they are each unique, as they do not appear in 2927 canonical URIs for the embedded resources. 2929 B.2. Reference removal is not always safe 2931 Attempting to remove all references and produce a single schema 2932 document does not, in all cases, produce a schema with identical 2933 behavior to the original form. 2935 Since "$ref" is now treated like any other keyword, with other 2936 keywords allowed in the same schema objects, fully supporting non- 2937 recursive "$ref" removal in all cases can require relatively complex 2938 schema manipulations. It is beyond the scope of this specification 2939 to determine or provide a set of safe "$ref" removal transformations, 2940 as they depend not only on the schema structure but also on the 2941 intended usage. 2943 Appendix C. Example of recursive schema extension 2945 Consider the following two schemas describing a simple recursive tree 2946 structure, where each node in the tree can have a "data" field of any 2947 type. The first schema allows and ignores other instance properties. 2948 The second is more strict and only allows the "data" and "children" 2949 properties. An example instance with "data" misspelled as "daat" is 2950 also shown. 2952 // tree schema, extensible 2953 { 2954 "$schema": "https://json-schema.org/draft/2020-12/schema", 2955 "$id": "https://example.com/tree", 2956 "$dynamicAnchor": "node", 2958 "type": "object", 2959 "properties": { 2960 "data": true, 2961 "children": { 2962 "type": "array", 2963 "items": { 2964 "$dynamicRef": "#node" 2965 } 2966 } 2967 } 2968 } 2970 // strict-tree schema, guards against misspelled properties 2971 { 2972 "$schema": "https://json-schema.org/draft/2020-12/schema", 2973 "$id": "https://example.com/strict-tree", 2974 "$dynamicAnchor": "node", 2976 "$ref": "tree", 2977 "unevaluatedProperties": false 2978 } 2980 // instance with misspelled field 2981 { 2982 "children": [ { "daat": 1 } ] 2983 } 2985 When we load these two schemas, we will notice the "$dynamicAnchor" 2986 named "node" (note the lack of "#" as this is just the name) present 2987 in each, resulting in the following full schema URIs: 2989 o "https://example.com/tree#node" 2991 o "https://example.com/strict-tree#node" 2993 In addition, JSON Schema implementations keep track of the fact that 2994 these fragments were created with "$dynamicAnchor". 2996 If we apply the "strict-tree" schema to the instance, we will follow 2997 the "$ref" to the "tree" schema, examine its "children" subschema, 2998 and find the "$dynamicRef": to "#node" (note the "#" for URI fragment 2999 syntax) in its "items" subschema. That reference resolves to 3000 "https://example.com/tree#node", which is a URI with a fragment 3001 created by "$dynamicAnchor". Therefore we must examine the dynamic 3002 scope before following the reference. 3004 At this point, the dynamic path is "#/$ref/properties/children/ 3005 items/$dynamicRef", with a dynamic scope containing (from the 3006 outermost scope to the innermost): 3008 1. "https://example.com/strict-tree#" 3010 2. "https://example.com/tree#" 3012 3. "https://example.com/tree#/properties/children" 3014 4. "https://example.com/tree#/properties/children/items" 3016 Since we are looking for a plain name fragment, which can be defined 3017 anywhere within a schema resource, the JSON Pointer fragments are 3018 irrelevant to this check. That means that we can remove those 3019 fragments and eliminate consecutive duplicates, producing: 3021 1. "https://example.com/strict-tree" 3023 2. "https://example.com/tree" 3025 In this case, the outermost resource also has a "node" fragment 3026 defined by "$dynamicAnchor". Therefore instead of resolving the 3027 "$dynamicRef" to "https://example.com/tree#node", we resolve it to 3028 "https://example.com/strict-tree#node". 3030 This way, the recursion in the "tree" schema recurses to the root of 3031 "strict-tree", instead of only applying "strict-tree" to the instance 3032 root, but applying "tree" to instance children. 3034 This example shows both "$dynamicAnchor"s in the same place in each 3035 schema, specifically the resource root schema. Since plain-name 3036 fragments are independent of the JSON structure, this would work just 3037 as well if one or both of the node schema objects were moved under 3038 "$defs". It is the matching "$dynamicAnchor" values which tell us 3039 how to resolve the dynamic reference, not any sort of correlation in 3040 JSON structure. 3042 Appendix D. Working with vocabularies 3044 D.1. Best practices for vocabulary and meta-schema authors 3046 Vocabulary authors should take care to avoid keyword name collisions 3047 if the vocabulary is intended for broad use, and potentially combined 3048 with other vocabularies. JSON Schema does not provide any formal 3049 namespacing system, but also does not constrain keyword names, 3050 allowing for any number of namespacing approaches. 3052 Vocabularies may build on each other, such as by defining the 3053 behavior of their keywords with respect to the behavior of keywords 3054 from another vocabulary, or by using a keyword from another 3055 vocabulary with a restricted or expanded set of acceptable values. 3056 Not all such vocabulary re-use will result in a new vocabulary that 3057 is compatible with the vocabulary on which it is built. Vocabulary 3058 authors should clearly document what level of compatibility, if any, 3059 is expected. 3061 Meta-schema authors should not use "$vocabulary" to combine multiple 3062 vocabularies that define conflicting syntax or semantics for the same 3063 keyword. As semantic conflicts are not generally detectable through 3064 schema validation, implementations are not expected to detect such 3065 conflicts. If conflicting vocabularies are declared, the resulting 3066 behavior is undefined. 3068 Vocabulary authors SHOULD provide a meta-schema that validates the 3069 expected usage of the vocabulary's keywords on their own. Such meta- 3070 schemas SHOULD not forbid additional keywords, and MUST not forbid 3071 any keywords from the Core vocabulary. 3073 It is recommended that meta-schema authors reference each 3074 vocabulary's meta-schema using the "allOf" (Section 10.2.1.1) 3075 keyword, although other mechanisms for constructing the meta-schema 3076 may be appropriate for certain use cases. 3078 The recursive nature of meta-schemas makes the "$dynamicAnchor" and 3079 "$dynamicRef" keywords particularly useful for extending existing 3080 meta-schemas, as can be seen in the JSON Hyper-Schema meta-schema 3081 which extends the Validation meta-schema. 3083 Meta-schemas may impose additional constraints, including describing 3084 keywords not present in any vocabulary, beyond what the meta-schemas 3085 associated with the declared vocabularies describe. This allows for 3086 restricting usage to a subset of a vocabulary, and for validating 3087 locally defined keywords not intended for re-use. 3089 However, meta-schemas should not contradict any vocabularies that 3090 they declare, such as by requiring a different JSON type than the 3091 vocabulary expects. The resulting behavior is undefined. 3093 Meta-schemas intended for local use, with no need to test for 3094 vocabulary support in arbitrary implementations, can safely omit 3095 "$vocabulary" entirely. 3097 D.2. Example meta-schema with vocabulary declarations 3099 This meta-schema explicitly declares both the Core and Applicator 3100 vocabularies, together with an extension vocabulary, and combines 3101 their meta-schemas with an "allOf". The extension vocabulary's meta- 3102 schema, which describes only the keywords in that vocabulary, is 3103 shown after the main example meta-schema. 3105 The main example meta-schema also restricts the usage of the 3106 Unevaluated vocabulary by forbidding the keywords prefixed with 3107 "unevaluated", which are particularly complex to implement. This 3108 does not change the semantics or set of keywords defined by the other 3109 vocabularies. It just ensures that schemas using this meta-schema 3110 that attempt to use the keywords prefixed with "unevaluated" will 3111 fail validation against this meta-schema. 3113 Finally, this meta-schema describes the syntax of a keyword, 3114 "localKeyword", that is not part of any vocabulary. Presumably, the 3115 implementors and users of this meta-schema will understand the 3116 semantics of "localKeyword". JSON Schema does not define any 3117 mechanism for expressing keyword semantics outside of vocabularies, 3118 making them unsuitable for use except in a specific environment in 3119 which they are understood. 3121 This meta-schema combines several vocabularies for general use. 3123 { 3124 "$schema": "https://json-schema.org/draft/2020-12/schema", 3125 "$id": "https://example.com/meta/general-use-example", 3126 "$dynamicAnchor": "meta", 3127 "$vocabulary": { 3128 "https://json-schema.org/draft/2020-12/vocab/core": true, 3129 "https://json-schema.org/draft/2020-12/vocab/applicator": true, 3130 "https://json-schema.org/draft/2020-12/vocab/validation": true, 3131 "https://example.com/vocab/example-vocab": true 3132 }, 3133 "allOf": [ 3134 {"$ref": "https://json-schema.org/draft/2020-12/meta/core"}, 3135 {"$ref": "https://json-schema.org/draft/2020-12/meta/applicator"}, 3136 {"$ref": "https://json-schema.org/draft/2020-12/meta/validation"}, 3137 {"$ref": "https://example.com/meta/example-vocab", 3138 ], 3139 "patternProperties": { 3140 "^unevaluated": false 3141 }, 3142 "properties": { 3143 "localKeyword": { 3144 "$comment": "Not in vocabulary, but validated if used", 3145 "type": "string" 3146 } 3147 } 3148 } 3149 This meta-schema describes only a single extension vocabulary. 3151 { 3152 "$schema": "https://json-schema.org/draft/2020-12/schema", 3153 "$id": "https://example.com/meta/example-vocab", 3154 "$dynamicAnchor": "meta", 3155 "$vocabulary": { 3156 "https://example.com/vocab/example-vocab": true, 3157 }, 3158 "type": ["object", "boolean"], 3159 "properties": { 3160 "minDate": { 3161 "type": "string", 3162 "pattern": "\d\d\d\d-\d\d-\d\d", 3163 "format": "date", 3164 } 3165 } 3166 } 3168 As shown above, even though each of the single-vocabulary meta- 3169 schemas referenced in the general-use meta-schema's "allOf" declares 3170 its corresponding vocabulary, this new meta-schema must re-declare 3171 them. 3173 The standard meta-schemas that combine all vocabularies defined by 3174 the Core and Validation specification, and that combine all 3175 vocabularies defined by those specifications as well as the Hyper- 3176 Schema specification, demonstrate additional complex combinations. 3177 These URIs for these meta-schemas may be found in the Validation and 3178 Hyper-Schema specifications, respectively. 3180 While the general-use meta-schema can validate the syntax of 3181 "minDate", it is the vocabulary that defines the logic behind the 3182 semantic meaning of "minDate". Without an understanding of the 3183 semantics (in this example, that the instance value must be a date 3184 equal to or after the date provided as the keyword's value in the 3185 schema), an implementation can only validate the syntactic usage. In 3186 this case, that means validating that it is a date-formatted string 3187 (using "pattern" to ensure that it is validated even when "format" 3188 functions purely as an annotation, as explained in the Validation 3189 specification [json-schema-validation]. 3191 Appendix E. References and generative use cases 3193 While the presence of references is expected to be transparent to 3194 validation results, generative use cases such as code generators and 3195 UI renderers often consider references to be semantically 3196 significant. 3198 To make such use case-specific semantics explicit, the best practice 3199 is to create an annotation keyword for use in the same schema object 3200 alongside of a reference keyword such as "$ref". 3202 For example, here is a hypothetical keyword for determining whether a 3203 code generator should consider the reference target to be a distinct 3204 class, and how those classes are related. Note that this example is 3205 solely for illustrative purposes, and is not intended to propose a 3206 functional code generation keyword. 3208 { 3209 "allOf": [ 3210 { 3211 "classRelation": "is-a", 3212 "$ref": "classes/base.json" 3213 }, 3214 { 3215 "$ref": "fields/common.json" 3216 } 3217 ], 3218 "properties": { 3219 "foo": { 3220 "classRelation": "has-a", 3221 "$ref": "classes/foo.json" 3222 }, 3223 "date": { 3224 "$ref": "types/dateStruct.json", 3225 } 3226 } 3227 } 3229 Here, this schema represents some sort of object-oriented class. The 3230 first reference in the "allOf" is noted as the base class. The 3231 second is not assigned a class relationship, meaning that the code 3232 generator should combine the target's definition with this one as if 3233 no reference were involved. 3235 Looking at the properties, "foo" is flagged as object composition, 3236 while the "date" property is not. It is simply a field with sub- 3237 fields, rather than an instance of a distinct class. 3239 This style of usage requires the annotation to be in the same object 3240 as the reference, which must be recognizable as a reference. 3242 Appendix F. Acknowledgments 3244 Thanks to Gary Court, Francis Galiegue, Kris Zyp, and Geraint Luff 3245 for their work on the initial drafts of JSON Schema. 3247 Thanks to Jason Desrosiers, Daniel Perrett, Erik Wilde, Evgeny 3248 Poberezkin, Brad Bowman, Gowry Sankar, Donald Pipowitch, Dave Finlay, 3249 Denis Laxalde, Phil Sturgeon, Shawn Silverman, and Karen Etheridge 3250 for their submissions and patches to the document. 3252 Appendix G. ChangeLog 3254 [[CREF13: This section to be removed before leaving Internet-Draft 3255 status.]] 3257 draft-bhutton-json-schema-00 3259 * "$schema" MAY change for embedded resources 3261 * Array-value "items" functionality is now "prefixItems" 3263 * "items" subsumes the old function of "additionalItems" 3265 * "contains" and "unevaluatedItems" interactions now specified 3267 * Rename $recursive* to $dynamic* 3269 * $dynamicAnchor defines a fragment like $anchor 3271 * $dynamic* (previously $recursive) no longer use runtime base 3272 URI determination 3274 * Define Compound Schema Documents (bundle) and processing 3276 * Reference ECMA-262, 11th edition for regular expression support 3278 * Regular expression should support unicode 3280 * Remove media type parameters 3282 * Specify Unknown keywords are collected as annotations 3283 * Moved "unevaluatedItems" and "unevaluatedProperties" from core 3284 into their own vocabulary 3286 draft-handrews-json-schema-02 3288 * Update to RFC 8259 for JSON specification 3290 * Moved "definitions" from the Validation specification here as 3291 "$defs" 3293 * Moved applicator keywords from the Validation specification as 3294 their own vocabulary 3296 * Moved the schema form of "dependencies" from the Validation 3297 specification as "dependentSchemas" 3299 * Formalized annotation collection 3301 * Specified recommended output formats 3303 * Defined keyword interactions in terms of annotation and 3304 assertion results 3306 * Added "unevaluatedProperties" and "unevaluatedItems" 3308 * Define "$ref" behavior in terms of the assertion, applicator, 3309 and annotation model 3311 * Allow keywords adjacent to "$ref" 3313 * Note undefined behavior for "$ref" targets involving unknown 3314 keywords 3316 * Add recursive referencing, primarily for meta-schema extension 3318 * Add the concept of formal vocabularies, and how they can be 3319 recognized through meta-schemas 3321 * Additional guidance on initial base URIs beyond network 3322 retrieval 3324 * Allow "schema" media type parameter for "application/ 3325 schema+json" 3327 * Better explanation of media type parameters and the HTTP Accept 3328 header 3330 * Use "$id" to establish canonical and base absolute-URIs only, 3331 no fragments 3333 * Replace plain-name-fragment-only form of "$id" with "$anchor" 3335 * Clarified that the behavior of JSON Pointers across "$id" 3336 boundary is unreliable 3338 draft-handrews-json-schema-01 3340 * This draft is purely a clarification with no functional changes 3342 * Emphasized annotations as a primary usage of JSON Schema 3344 * Clarified $id by use cases 3346 * Exhaustive schema identification examples 3348 * Replaced "external referencing" with how and when an 3349 implementation might know of a schema from another document 3351 * Replaced "internal referencing" with how an implementation 3352 should recognized schema identifiers during parsing 3354 * Dereferencing the former "internal" or "external" references is 3355 always the same process 3357 * Minor formatting improvements 3359 draft-handrews-json-schema-00 3361 * Make the concept of a schema keyword vocabulary more clear 3363 * Note that the concept of "integer" is from a vocabulary, not 3364 the data model 3366 * Classify keywords as assertions or annotations and describe 3367 their general behavior 3369 * Explain the boolean schemas in terms of generalized assertions 3371 * Reserve "$comment" for non-user-visible notes about the schema 3373 * Wording improvements around "$id" and fragments 3375 * Note the challenges of extending meta-schemas with recursive 3376 references 3378 * Add "application/schema-instance+json" media type 3380 * Recommend a "schema" link relation / parameter instead of 3381 "profile" 3383 draft-wright-json-schema-01 3385 * Updated intro 3387 * Allowed for any schema to be a boolean 3389 * "$schema" SHOULD NOT appear in subschemas, although that may 3390 change 3392 * Changed "id" to "$id"; all core keywords prefixed with "$" 3394 * Clarify and formalize fragments for application/schema+json 3396 * Note applicability to formats such as CBOR that can be 3397 represented in the JSON data model 3399 draft-wright-json-schema-00 3401 * Updated references to JSON 3403 * Updated references to HTTP 3405 * Updated references to JSON Pointer 3407 * Behavior for "id" is now specified in terms of RFC3986 3409 * Aligned vocabulary usage for URIs with RFC3986 3411 * Removed reference to draft-pbryan-zyp-json-ref-03 3413 * Limited use of "$ref" to wherever a schema is expected 3415 * Added definition of the "JSON Schema data model" 3417 * Added additional security considerations 3419 * Defined use of subschema identifiers for "id" 3421 * Rewrote section on usage with HTTP 3423 * Rewrote section on usage with rel="describedBy" and 3424 rel="profile" 3426 * Fixed numerous invalid examples 3428 draft-zyp-json-schema-04 3430 * Salvaged from draft v3. 3432 * Split validation keywords into separate document. 3434 * Split hypermedia keywords into separate document. 3436 * Initial post-split draft. 3438 * Mandate the use of JSON Reference, JSON Pointer. 3440 * Define the role of "id". Define URI resolution scope. 3442 * Add interoperability considerations. 3444 draft-zyp-json-schema-00 3446 * Initial draft. 3448 Authors' Addresses 3450 Austin Wright (editor) 3452 EMail: aaa@bzfx.net 3454 Henry Andrews (editor) 3456 EMail: andrews_henry@yahoo.com 3458 Ben Hutton (editor) 3460 EMail: ben@jsonschema.dev 3461 URI: https://jsonschema.dev 3463 Greg Dennis 3465 EMail: gregsdennis@yahoo.com 3466 URI: https://github.com/gregsdennis