idnits 2.17.1 draft-handrews-json-schema-01.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 19, 2018) is 2230 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 543, but not defined == Missing Reference: '0-9' is mentioned on line 544, but not defined ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- 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 (~~), 3 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: September 20, 2018 Cloudflare, Inc. 6 March 19, 2018 8 JSON Schema: A Media Type for Describing JSON Documents 9 draft-handrews-json-schema-01 11 Abstract 13 JSON Schema defines the media type "application/schema+json", a JSON- 14 based format for describing the structure of JSON data. JSON Schema 15 asserts what a JSON document must look like, ways to extract 16 information from it, and how to interact with it. The "application/ 17 schema-instance+json" media type provides additional feature-rich 18 integration with "application/schema+json" beyond what can be offered 19 for "application/json" documents. 21 Note to Readers 23 The issues list for this draft can be found at . 26 For additional information, see . 28 To provide feedback, use this issue tracker, the communication 29 methods listed on the homepage, or email the document editors. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on September 20, 2018. 48 Copyright Notice 50 Copyright (c) 2018 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (https://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3 67 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 3.1. Validation . . . . . . . . . . . . . . . . . . . . . . . 4 69 3.2. Annotation . . . . . . . . . . . . . . . . . . . . . . . 4 70 3.3. Hypermedia and Linking . . . . . . . . . . . . . . . . . 4 71 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 72 4.1. JSON Document . . . . . . . . . . . . . . . . . . . . . . 4 73 4.2. Instance . . . . . . . . . . . . . . . . . . . . . . . . 5 74 4.2.1. Instance Data Model . . . . . . . . . . . . . . . . . 5 75 4.2.2. Instance Media Types . . . . . . . . . . . . . . . . 6 76 4.2.3. Instance Equality . . . . . . . . . . . . . . . . . . 6 77 4.3. JSON Schema Documents . . . . . . . . . . . . . . . . . . 7 78 4.3.1. JSON Schema Values and Keywords . . . . . . . . . . . 7 79 4.3.2. JSON Schema Vocabularies . . . . . . . . . . . . . . 8 80 4.3.3. Root Schema and Subschemas . . . . . . . . . . . . . 8 81 5. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . 9 82 6. General Considerations . . . . . . . . . . . . . . . . . . . 10 83 6.1. Range of JSON Values . . . . . . . . . . . . . . . . . . 10 84 6.2. Programming Language Independence . . . . . . . . . . . . 10 85 6.3. Mathematical Integers . . . . . . . . . . . . . . . . . . 10 86 6.4. Extending JSON Schema . . . . . . . . . . . . . . . . . . 10 87 7. The "$schema" Keyword . . . . . . . . . . . . . . . . . . . . 10 88 8. Base URI and Dereferencing . . . . . . . . . . . . . . . . . 11 89 8.1. Initial Base URI . . . . . . . . . . . . . . . . . . . . 11 90 8.2. The "$id" Keyword . . . . . . . . . . . . . . . . . . . . 11 91 8.2.1. Identifying the root schema . . . . . . . . . . . . . 12 92 8.2.2. Changing the base URI within a schema file . . . . . 12 93 8.2.3. Location-independent identifiers . . . . . . . . . . 12 94 8.2.4. Schema identification examples . . . . . . . . . . . 13 95 8.3. Schema References With "$ref" . . . . . . . . . . . . . . 14 96 8.3.1. Loading a referenced schema . . . . . . . . . . . . . 15 97 8.3.2. Dereferencing . . . . . . . . . . . . . . . . . . . . 15 98 9. Comments With "$comment" . . . . . . . . . . . . . . . . . . 16 99 10. Usage for Hypermedia . . . . . . . . . . . . . . . . . . . . 17 100 10.1. Linking to a Schema . . . . . . . . . . . . . . . . . . 17 101 10.2. Identifying a Schema via a Media Type Parameter . . . . 17 102 10.3. Usage Over HTTP . . . . . . . . . . . . . . . . . . . . 18 103 11. Security Considerations . . . . . . . . . . . . . . . . . . . 19 104 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 105 12.1. application/schema+json . . . . . . . . . . . . . . . . 19 106 12.2. application/schema-instance+json . . . . . . . . . . . . 20 107 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 108 13.1. Normative References . . . . . . . . . . . . . . . . . . 20 109 13.2. Informative References . . . . . . . . . . . . . . . . . 21 110 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 23 111 Appendix B. ChangeLog . . . . . . . . . . . . . . . . . . . . . 23 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 114 1. Introduction 116 JSON Schema is a JSON media type for defining the structure of JSON 117 data. JSON Schema is intended to define validation, documentation, 118 hyperlink navigation, and interaction control of JSON data. 120 This specification defines JSON Schema core terminology and 121 mechanisms, including pointing to another JSON Schema by reference, 122 dereferencing a JSON Schema reference, and specifying the vocabulary 123 being used. 125 Other specifications define the vocabularies that perform assertions 126 about validation, linking, annotation, navigation, and interaction. 128 2. Conventions and Terminology 130 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 131 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 132 document are to be interpreted as described in RFC 2119 [RFC2119]. 134 The terms "JSON", "JSON text", "JSON value", "member", "element", 135 "object", "array", "number", "string", "boolean", "true", "false", 136 and "null" in this document are to be interpreted as defined in RFC 137 7159 [RFC7159]. 139 3. Overview 141 This document proposes a new media type "application/schema+json" to 142 identify a JSON Schema for describing JSON data. It also proposes a 143 further optional media type, "application/schema-instance+json", to 144 provide additional integration features. JSON Schemas are themselves 145 JSON documents. This, and related specifications, define keywords 146 allowing authors to describe JSON data in several ways. 148 3.1. Validation 150 JSON Schema describes the structure of a JSON document (for instance, 151 required properties and length limitations). Applications can use 152 this information to validate instances (check that constraints are 153 met), or inform interfaces to collect user input such that the 154 constraints are satisfied. 156 Validation behaviour and keywords are specified in a separate 157 document [json-schema-validation]. 159 3.2. Annotation 161 JSON Schema can annotate an instance with information, whenever the 162 instance validates against the schema object containing the 163 annotation, and all of its parent schema objects. 165 Detailed annotation behavior, along with a small set of basic 166 annotation keywords are defined in the validation specification 167 [json-schema-validation]. 169 3.3. Hypermedia and Linking 171 JSON Hyper-Schema describes the hypertext structure of a JSON 172 document. This includes link relations from the instance to other 173 resources, interpretation of instances as multimedia data, and 174 submission data required to use an API. 176 Hyper-schema behaviour and keywords are specified in a separate 177 document [json-hyper-schema]. 179 4. Definitions 181 4.1. JSON Document 183 A JSON document is an information resource (series of octets) 184 described by the application/json media type. 186 In JSON Schema, the terms "JSON document", "JSON text", and "JSON 187 value" are interchangeable because of the data model it defines. 189 JSON Schema is only defined over JSON documents. However, any 190 document or memory structure that can be parsed into or processed 191 according to the JSON Schema data model can be interpreted against a 192 JSON Schema, including media types like CBOR [RFC7049]. 194 4.2. Instance 196 A JSON document to which a schema is applied is known as an 197 "instance". 199 4.2.1. Instance Data Model 201 JSON Schema interprets documents according to a data model. A JSON 202 value interpreted according to this data model is called an 203 "instance". 205 An instance has one of six primitive types, and a range of possible 206 values depending on the type: 208 null: A JSON "null" production 210 boolean: A "true" or "false" value, from the JSON "true" or "false" 211 productions 213 object: An unordered set of properties mapping a string to an 214 instance, from the JSON "object" production 216 array: An ordered list of instances, from the JSON "array" 217 production 219 number: An arbitrary-precision, base-10 decimal number value, from 220 the JSON "number" production 222 string: A string of Unicode code points, from the JSON "string" 223 production 225 Whitespace and formatting concerns, including different lexical 226 representations of numbers that are equal within the data model, are 227 thus outside the scope of JSON Schema. JSON Schema vocabularies 228 (Section 4.3.2) that wish to work with such differences in lexical 229 representations SHOULD define keywords to precisely interpret 230 formatted strings within the data model rather than relying on having 231 the original JSON representation Unicode characters available. 233 Since an object cannot have two properties with the same key, 234 behavior for a JSON document that tries to define two properties (the 235 "member" production) with the same key (the "string" production) in a 236 single object is undefined. 238 Note that JSON Schema vocabularies are free to define their own 239 extended type system. This should not be confused with the core data 240 model types defined here. As an example, "integer" is a reasonable 241 type for a vocabulary to define as a value for a keyword, but the 242 data model makes no distinction between integers and other numbers. 244 4.2.2. Instance Media Types 246 JSON Schema is designed to fully work with "application/json" 247 documents, as well as media types using the "+json" structured syntax 248 suffix. 250 Some functionality that is useful for working with schemas is defined 251 by each media type, namely media type parameters and URI fragment 252 identifier syntax and semantics. These features are useful in 253 content negotiation and in calculating URIs for specific locations 254 within an instance, respectively. 256 This specification defines the "application/schema-instance+json" 257 media type in order to allow instance authors to take full advantage 258 of parameters and fragment identifiers for these purposes. 260 4.2.3. Instance Equality 262 Two JSON instances are said to be equal if and only if they are of 263 the same type and have the same value according to the data model. 264 Specifically, this means: 266 both are null; or 268 both are true; or 270 both are false; or 272 both are strings, and are the same codepoint-for-codepoint; or 274 both are numbers, and have the same mathematical value; or 276 both are arrays, and have an equal value item-for-item; or 278 both are objects, and each property in one has exactly one 279 property with a key equal to the other's, and that other property 280 has an equal value. 282 Implied in this definition is that arrays must be the same length, 283 objects must have the same number of members, properties in objects 284 are unordered, there is no way to define multiple properties with the 285 same key, and mere formatting differences (indentation, placement of 286 commas, trailing zeros) are insignificant. 288 4.3. JSON Schema Documents 290 A JSON Schema document, or simply a schema, is a JSON document used 291 to describe an instance. A schema is itself interpreted as an 292 instance, but SHOULD always be given the media type "application/ 293 schema+json" rather than "application/schema-instance+json". The 294 "application/schema+json" media type is defined to offer a superset 295 of the media type parameter and fragment identifier syntax and 296 semantics provided by "application/schema-instance+json". 298 4.3.1. JSON Schema Values and Keywords 300 A JSON Schema MUST be an object or a boolean. 302 Object properties that are applied to the instance are called 303 keywords, or schema keywords. Broadly speaking, keywords fall into 304 one or both of two categories: 306 assertions: produce a boolean result when applied to an instance 308 annotations: attach information to an instance for application use 310 Keywords may fall into either or both categories. Extension 311 keywords, meaning those defined outside of this document and its 312 companions, are free to define other behaviors as well. 314 The boolean schema values "true" and "false" are trivial assertions 315 that always return themselves regardless of the instance value. As 316 an example, in terms of the validation vocabulary, boolean schemas 317 are equivalent to the following behaviors: 319 true: Always passes validation, as if the empty schema {} 321 false: Always fails validation, as if the schema { "not":{} } 323 A JSON Schema MAY contain properties which are not schema keywords. 324 Unknown keywords SHOULD be ignored. 326 An empty schema is a JSON Schema with no properties, or only unknown 327 properties. 329 4.3.2. JSON Schema Vocabularies 331 A JSON Schema vocabulary is a set of keywords defined for a 332 particular purpose. The vocabulary specifies the meaning of its 333 keywords as assertions, annotations, and/or any vocabulary-defined 334 keyword category. The two companion standards to this document each 335 define a vocabulary: One for instance validation, and one for 336 hypermedia annotations. Vocabularies are the primary mechanism for 337 extensibility within the JSON Schema media type. 339 Vocabularies may be defined by any entity. Vocabulary authors SHOULD 340 take care to avoid keyword name collisions if the vocabulary is 341 intended for broad use, and potentially combined with other 342 vocabularies. JSON Schema does not provide any formal namespacing 343 system, but also does not constrain keyword names, allowing for any 344 number of namespacing approaches. 346 Vocabularies may build on each other, such as by defining the 347 behavior of their keywords with respect to the behavior of keywords 348 from another vocabulary, or by using a keyword from another 349 vocabulary with a restricted or expanded set of acceptable values. 350 Not all such vocabulary re-use will result in a new vocabulary that 351 is compatible with the vocabulary on which it is built. Vocabulary 352 authors SHOULD clearly document what level of compatibility, if any, 353 is expected. 355 A schema that itself describes a schema is called a meta-schema. 356 Meta-schemas are used to validate JSON Schemas and specify which 357 vocabulary it is using. [[CREF1: Currently, only a single meta- 358 schema may be specified per schema, meaning that in order to use 359 multiple vocabularies, a meta-schema must be written that encompasses 360 all of them. The hyper-schema meta-schema is an example of this, as 361 it encompasses the validation vocabulary as well as the hypermedia 362 vocabulary. ]] 364 4.3.3. Root Schema and Subschemas 366 The root schema is the schema that comprises the entire JSON document 367 in question. 369 Some keywords take schemas themselves, allowing JSON Schemas to be 370 nested: 372 { 373 "title": "root", 374 "items": { 375 "title": "array item" 376 } 377 } 379 In this example document, the schema titled "array item" is a 380 subschema, and the schema titled "root" is the root schema. 382 As with the root schema, a subschema is either an object or a 383 boolean. 385 5. Fragment Identifiers 387 In accordance with section 3.1 of [RFC6839], the syntax and semantics 388 of fragment identifiers specified for any +json media type SHOULD be 389 as specified for "application/json". (At publication of this 390 document, there is no fragment identification syntax defined for 391 "application/json".) 393 Additionally, the "application/schema+json" media type supports two 394 fragment identifier structures: plain names and JSON Pointers. The 395 "application/schema-instance+json" media type supports one fragment 396 identifier structure: JSON Pointers. 398 The use of JSON Pointers as URI fragment identifiers is described in 399 RFC 6901 [RFC6901]. For "application/schema+json", which supports 400 two fragment identifier syntaxes, fragment identifiers matching the 401 JSON Pointer syntax, including the empty string, MUST be interpreted 402 as JSON Pointer fragment identifiers. 404 Per the W3C's best practices for fragment identifiers 405 [W3C.WD-fragid-best-practices-20121025], plain name fragment 406 identifiers in "application/schema+json" are reserved for referencing 407 locally named schemas. All fragment identifiers that do not match 408 the JSON Pointer syntax MUST be interpreted as plain name fragment 409 identifiers. 411 Defining and referencing a plain name fragment identifier within an 412 "application/schema+json" document are specified in the "$id" keyword 413 (Section 8.2) section. 415 6. General Considerations 417 6.1. Range of JSON Values 419 An instance may be any valid JSON value as defined by JSON [RFC7159]. 420 JSON Schema imposes no restrictions on type: JSON Schema can describe 421 any JSON value, including, for example, null. 423 6.2. Programming Language Independence 425 JSON Schema is programming language agnostic, and supports the full 426 range of values described in the data model. Be aware, however, that 427 some languages and JSON parsers may not be able to represent in 428 memory the full range of values describable by JSON. 430 6.3. Mathematical Integers 432 Some programming languages and parsers use different internal 433 representations for floating point numbers than they do for integers. 435 For consistency, integer JSON numbers SHOULD NOT be encoded with a 436 fractional part. 438 6.4. Extending JSON Schema 440 Implementations MAY define additional keywords to JSON Schema. Save 441 for explicit agreement, schema authors SHALL NOT expect these 442 additional keywords to be supported by peer implementations. 443 Implementations SHOULD ignore keywords they do not support. 445 Authors of extensions to JSON Schema are encouraged to write their 446 own meta-schemas, which extend the existing meta-schemas using 447 "allOf". This extended meta-schema SHOULD be referenced using the 448 "$schema" keyword, to allow tools to follow the correct behaviour. 450 Note that the recursive nature of meta-schemas requires re-defining 451 recursive keywords in the extended meta-schema, as can be seen in the 452 JSON Hyper-Schema meta-schema. 454 7. The "$schema" Keyword 456 The "$schema" keyword is both used as a JSON Schema version 457 identifier and the location of a resource which is itself a JSON 458 Schema, which describes any schema written for this particular 459 version. 461 The value of this keyword MUST be a URI [RFC3986] (containing a 462 scheme) and this URI MUST be normalized. The current schema MUST be 463 valid against the meta-schema identified by this URI. 465 If this URI identifies a retrievable resource, that resource SHOULD 466 be of media type "application/schema+json". 468 The "$schema" keyword SHOULD be used in a root schema. It MUST NOT 469 appear in subschemas. 471 [[CREF2: Using multiple "$schema" keywords in the same document would 472 imply that the vocabulary and therefore behavior can change within a 473 document. This would necessitate resolving a number of 474 implementation concerns that have not yet been clearly defined. So, 475 while the pattern of using "$schema" only in root schemas is likely 476 to remain the best practice for schema authoring, implementation 477 behavior is subject to be revised or liberalized in future drafts. 478 ]] 480 Values for this property are defined in other documents and by other 481 parties. JSON Schema implementations SHOULD implement support for 482 current and previous published drafts of JSON Schema vocabularies as 483 deemed reasonable. 485 8. Base URI and Dereferencing 487 To differentiate between schemas in a vast ecosystem, schemas are 488 identified by URI [RFC3986], and can embed references to other 489 schemas by specifying their URI. 491 8.1. Initial Base URI 493 RFC3986 Section 5.1 [RFC3986] defines how to determine the default 494 base URI of a document. 496 Informatively, the initial base URI of a schema is the URI at which 497 it was found, or a suitable substitute URI if none is known. 499 8.2. The "$id" Keyword 501 The "$id" keyword defines a URI for the schema, and the base URI that 502 other URI references within the schema are resolved against. A 503 subschema's "$id" is resolved against the base URI of its parent 504 schema. If no parent sets an explicit base with "$id", the base URI 505 is that of the entire document, as determined per RFC 3986 section 5 506 [RFC3986]. 508 If present, the value for this keyword MUST be a string, and MUST 509 represent a valid URI-reference [RFC3986]. This value SHOULD be 510 normalized, and SHOULD NOT be an empty fragment <#> or an empty 511 string <>. 513 8.2.1. Identifying the root schema 515 The root schema of a JSON Schema document SHOULD contain an "$id" 516 keyword with an absolute-URI [RFC3986] (containing a scheme, but no 517 fragment), or this absolute URI but with an empty fragment. 519 8.2.2. Changing the base URI within a schema file 521 When an "$id" sets the base URI, the object containing that "$id" and 522 all of its subschemas can be identified by using a JSON Pointer 523 fragment starting from that location. This is true even of 524 subschemas that further change the base URI. Therefore, a single 525 subschema may be accessible by multiple URIs, each consisting of base 526 URI declared in the subschema or a parent, along with a JSON Pointer 527 fragment identifying the path from the schema object that declares 528 the base to the subschema being identified. Examples of this are 529 shown in section 8.2.4. 531 8.2.3. Location-independent identifiers 533 Using JSON Pointer fragments requires knowledge of the structure of 534 the schema. When writing schema documents with the intention to 535 provide re-usable schemas, it may be preferable to use a plain name 536 fragment that is not tied to any particular structural location. 537 This allows a subschema to be relocated without requiring JSON 538 Pointer references to be updated. 540 To specify such a subschema identifier, the "$id" keyword is set to a 541 URI reference with a plain name fragment (not a JSON Pointer 542 fragment). This value MUST begin with the number sign that specifies 543 a fragment ("#"), then a letter ([A-Za-z]), followed by any number of 544 letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons 545 (":"), or periods ("."). 547 The effect of using a fragment in "$id" that isn't blank or doesn't 548 follow the plain name syntax is undefined. [[CREF3: How should an 549 "$id" URI reference containing a fragment with other components be 550 interpreted? There are two cases: when the other components match 551 the current base URI and when they change the base URI. ]] 553 8.2.4. Schema identification examples 555 Consider the following schema, which shows "$id" being used to 556 identify the root schema, change the base URI for subschemas, and 557 assign plain name fragments to subschemas: 559 { 560 "$id": "http://example.com/root.json", 561 "definitions": { 562 "A": { "$id": "#foo" }, 563 "B": { 564 "$id": "other.json", 565 "definitions": { 566 "X": { "$id": "#bar" }, 567 "Y": { "$id": "t/inner.json" } 568 } 569 }, 570 "C": { 571 "$id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f" 572 } 573 } 574 } 576 The schemas at the following URI-encoded JSON Pointers [RFC6901] 577 (relative to the root schema) have the following base URIs, and are 578 identifiable by any listed URI in accordance with Section 5 above: 580 # (document root) 582 http://example.com/root.json 584 http://example.com/root.json# 586 #/definitions/A 588 http://example.com/root.json#foo 590 http://example.com/root.json#/definitions/A 592 #/definitions/B 594 http://example.com/other.json 596 http://example.com/other.json# 598 http://example.com/root.json#/definitions/B 600 #/definitions/B/definitions/X 602 http://example.com/other.json#bar 604 http://example.com/other.json#/definitions/X 606 http://example.com/root.json#/definitions/B/definitions/X 608 #/definitions/B/definitions/Y 610 http://example.com/t/inner.json 612 http://example.com/t/inner.json# 614 http://example.com/other.json#/definitions/Y 616 http://example.com/root.json#/definitions/B/definitions/Y 618 #/definitions/C 620 urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f 622 urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f# 624 http://example.com/root.json#/definitions/C 626 8.3. Schema References With "$ref" 628 The "$ref" keyword is used to reference a schema, and provides the 629 ability to validate recursive structures through self-reference. 631 An object schema with a "$ref" property MUST be interpreted as a 632 "$ref" reference. The value of the "$ref" property MUST be a URI 633 Reference. Resolved against the current URI base, it identifies the 634 URI of a schema to use. All other properties in a "$ref" object MUST 635 be ignored. 637 The URI is not a network locator, only an identifier. A schema need 638 not be downloadable from the address if it is a network-addressable 639 URL, and implementations SHOULD NOT assume they should perform a 640 network operation when they encounter a network-addressable URI. 642 A schema MUST NOT be run into an infinite loop against a schema. For 643 example, if two schemas "#alice" and "#bob" both have an "allOf" 644 property that refers to the other, a naive validator might get stuck 645 in an infinite recursive loop trying to validate the instance. 646 Schemas SHOULD NOT make use of infinite recursive nesting like this; 647 the behavior is undefined. 649 8.3.1. Loading a referenced schema 651 The use of URIs to identify remote schemas does not necessarily mean 652 anything is downloaded, but instead JSON Schema implementations 653 SHOULD understand ahead of time which schemas they will be using, and 654 the URIs that identify them. 656 When schemas are downloaded, for example by a generic user-agent that 657 doesn't know until runtime which schemas to download, see Usage for 658 Hypermedia (Section 10). 660 Implementations SHOULD be able to associate arbitrary URIs with an 661 arbitrary schema and/or automatically associate a schema's "$id"- 662 given URI, depending on the trust that the validator has in the 663 schema. Such URIs and schemas can be supplied to an implementation 664 prior to processing instances, or may be noted within a schema 665 document as it is processed, producing associations as shown in 666 section 8.2.4. 668 A schema MAY (and likely will) have multiple URIs, but there is no 669 way for a URI to identify more than one schema. When multiple 670 schemas try to identify as the same URI, validators SHOULD raise an 671 error condition. 673 8.3.2. Dereferencing 675 Schemas can be identified by any URI that has been given to them, 676 including a JSON Pointer or their URI given directly by "$id". In 677 all cases, dereferencing a "$ref" reference involves first resolving 678 its value as a URI reference against the current base URI per RFC 679 3986 [RFC3986]. 681 If the resulting URI identifies a schema within the current document, 682 or within another schema document that has been made available to the 683 implementation, then that schema SHOULD be used automatically. 685 For example, consider this schema: 687 { 688 "$id": "http://example.net/root.json", 689 "items": { 690 "type": "array", 691 "items": { "$ref": "#item" } 692 }, 693 "definitions": { 694 "single": { 695 "$id": "#item", 696 "type": "object", 697 "additionalProperties": { "$ref": "other.json" } 698 } 699 } 700 } 702 When an implementation encounters the <#/definitions/single> schema, 703 it resolves the "$id" URI reference against the current base URI to 704 form . 706 When an implementation then looks inside the <#/items> schema, it 707 encounters the <#item> reference, and resolves this to 708 , which it has seen defined in 709 this same document and can therefore use automatically. 711 When an implementation encounters the reference to "other.json", it 712 resolves this to , which is not 713 defined in this document. If a schema with that identifier has 714 otherwise been supplied to the implementation, it can also be used 715 automatically. [[CREF4: What should implementations do when the 716 referenced schema is not known? Are there circumstances in which 717 automatic network dereferencing is allowed? A same origin policy? A 718 user-configurable option? In the case of an evolving API described 719 by Hyper-Schema, it is expected that new schemas will be added to the 720 system dynamically, so placing an absolute requirement of pre-loading 721 schema documents is not feasible. ]] 723 9. Comments With "$comment" 725 This keyword is reserved for comments from schema authors to readers 726 or maintainers of the schema. The value of this keyword MUST be a 727 string. Implementations MUST NOT present this string to end users. 728 Tools for editing schemas SHOULD support displaying and editing this 729 keyword. The value of this keyword MAY be used in debug or error 730 output which is intended for developers making use of schemas. 731 Schema vocabularies SHOULD allow "$comment" within any object 732 containing vocabulary keywords. Implementations MAY assume 733 "$comment" is allowed unless the vocabulary specifically forbids it. 735 Vocabularies MUST NOT specify any effect of "$comment" beyond what is 736 described in this specification. Tools that translate other media 737 types or programming languages to and from application/schema+json 738 MAY choose to convert that media type or programming language's 739 native comments to or from "$comment" values. The behavior of such 740 translation when both native comments and "$comment" properties are 741 present is implementation-dependent. Implementations SHOULD treat 742 "$comment" identically to an unknown extension keyword. They MAY 743 strip "$comment" values at any point during processing. In 744 particular, this allows for shortening schemas when the size of 745 deployed schemas is a concern. Implementations MUST NOT take any 746 other action based on the presence, absence, or contents of 747 "$comment" properties. 749 10. Usage for Hypermedia 751 JSON has been adopted widely by HTTP servers for automated APIs and 752 robots. This section describes how to enhance processing of JSON 753 documents in a more RESTful manner when used with protocols that 754 support media types and Web linking [RFC8288]. 756 10.1. Linking to a Schema 758 It is RECOMMENDED that instances described by a schema provide a link 759 to a downloadable JSON Schema using the link relation "describedby", 760 as defined by Linked Data Protocol 1.0, section 8.1 761 [W3C.REC-ldp-20150226]. 763 In HTTP, such links can be attached to any response using the Link 764 header [RFC8288]. An example of such a header would be: 766 Link: ; rel="describedby" 768 10.2. Identifying a Schema via a Media Type Parameter 770 Media types MAY allow for a "schema" media type parameter, which 771 gives HTTP servers the ability to perform Content-Type Negotiation 772 based on schema. The media-type parameter MUST be a whitespace- 773 separated list of URIs (i.e. relative references are invalid). 775 When using the media type application/schema-instance+json, the 776 "schema" parameter MUST be supplied. 778 The schema URI is opaque and SHOULD NOT automatically be 779 dereferenced. If the implementation does not understand the 780 semantics of the provided schema, the implementation can instead 781 follow the "describedby" links, if any, which may provide information 782 on how to handle the schema. Since "schema" doesn't necessarily 783 point to a network location, the "describedby" relation is used for 784 linking to a downloadable schema. However, for simplicity, schema 785 authors should make these URIs point to the same resource when 786 possible. 788 In HTTP, the media-type parameter would be sent inside the Content- 789 Type header: 791 Content-Type: application/json; 792 schema="http://example.com/my-hyper-schema#" 794 Multiple schemas are whitespace separated: 796 Content-Type: application/json; 797 schema="http://example.com/alice http://example.com/bob" 799 [[CREF5: This paragraph assumes that we can register a "schema" link 800 relation. Should we instead specify something like "tag:json- 801 schema.org,2017:schema" for now? ]] HTTP can also send the "schema" 802 in a Link, though this may impact media-type semantics and Content- 803 Type negotiation if this replaces the media-type parameter entirely: 805 Link: ;rel="schema", ;rel="schema" 807 10.3. Usage Over HTTP 809 When used for hypermedia systems over a network, HTTP [RFC7231] is 810 frequently the protocol of choice for distributing schemas. 811 Misbehaving clients can pose problems for server maintainers if they 812 pull a schema over the network more frequently than necessary, when 813 it's instead possible to cache a schema for a long period of time. 815 HTTP servers SHOULD set long-lived caching headers on JSON Schemas. 816 HTTP clients SHOULD observe caching headers and not re-request 817 documents within their freshness period. Distributed systems SHOULD 818 make use of a shared cache and/or caching proxy. 820 Clients SHOULD set or prepend a User-Agent header specific to the 821 JSON Schema implementation or software product. Since symbols are 822 listed in decreasing order of significance, the JSON Schema library 823 name/version should precede the more generic HTTP library name (if 824 any). For example: 826 User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 828 Clients SHOULD be able to make requests with a "From" header so that 829 server operators can contact the owner of a potentially misbehaving 830 script. 832 11. Security Considerations 834 Both schemas and instances are JSON values. As such, all security 835 considerations defined in RFC 7159 [RFC7159] apply. 837 Instances and schemas are both frequently written by untrusted third 838 parties, to be deployed on public Internet servers. Validators 839 should take care that the parsing and validating against schemas 840 doesn't consume excessive system resources. Validators MUST NOT fall 841 into an infinite loop. 843 Servers MUST ensure that malicious parties can't change the 844 functionality of existing schemas by uploading a schema with an pre- 845 existing or very similar "$id". 847 Individual JSON Schema vocabularies are liable to also have their own 848 security considerations. Consult the respective specifications for 849 more information. 851 Schema authors should take care with "$comment" contents, as a 852 malicious implementation can display them to end-users in violation 853 of a spec, or fail to strip them if such behavior is expected. 855 A malicious schema author could place executable code or other 856 dangerous material within a "$comment". Implementations MUST NOT 857 parse or otherwise take action based on "$comment" contents. 859 12. IANA Considerations 861 12.1. application/schema+json 863 The proposed MIME media type for JSON Schema is defined as follows: 865 Type name: application 867 Subtype name: schema+json 868 Required parameters: N/A 870 Encoding considerations: Encoding considerations are identical to 871 those specified for the "application/json" media type. See JSON 872 [RFC7159]. 874 Security considerations: See Section 11 above. 876 Interoperability considerations: See Sections 6.2 and 6.3 above. 878 Fragment identifier considerations: See Section 5 880 12.2. application/schema-instance+json 882 The proposed MIME media type for JSON Schema Instances that require a 883 JSON Schema-specific media type is defined as follows: 885 Type name: application 887 Subtype name: schema-instance+json 889 Required parameters: 891 schema: A non-empty list of space-separated URIs, each 892 identifying a JSON Schema resource. The instance SHOULD 893 successfully validate against at least one of these schemas. 894 Non-validating schemas MAY be included for purposes such as 895 allowing clients to make use of older versions of a schema as 896 long as the runtime instance validates against that older 897 version. 899 Encoding considerations: Encoding considerations are identical to 900 those specified for the "application/json" media type. See JSON 901 [RFC7159]. 903 Security considerations: See Section 11 above. 905 Interoperability considerations: See Sections 6.2 and 6.3 above. 907 Fragment identifier considerations: See Section 5 909 13. References 911 13.1. Normative References 913 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 914 Requirement Levels", BCP 14, RFC 2119, 915 DOI 10.17487/RFC2119, March 1997, 916 . 918 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 919 Resource Identifier (URI): Generic Syntax", STD 66, 920 RFC 3986, DOI 10.17487/RFC3986, January 2005, 921 . 923 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 924 Structured Syntax Suffixes", RFC 6839, 925 DOI 10.17487/RFC6839, January 2013, 926 . 928 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 929 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 930 DOI 10.17487/RFC6901, April 2013, 931 . 933 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 934 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 935 2014, . 937 [W3C.REC-ldp-20150226] 938 Speicher, S., Arwe, J., and A. Malhotra, "Linked Data 939 Platform 1.0", World Wide Web Consortium Recommendation 940 REC-ldp-20150226, February 2015, 941 . 943 13.2. Informative References 945 [json-hyper-schema] 946 Andrews, H. and A. Wright, "JSON Hyper-Schema: A 947 Vocabulary for Hypermedia Annotation of JSON", draft- 948 handrews-json-schema-hyperschema-01 (work in progress), 949 November 2017. 951 [json-schema-validation] 952 Wright, A., Andrews, H., and G. Luff, "JSON Schema 953 Validation: A Vocabulary for Structural Validation of 954 JSON", draft-handrews-json-schema-validation-01 (work in 955 progress), November 2017. 957 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 958 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 959 October 2013, . 961 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 962 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 963 DOI 10.17487/RFC7231, June 2014, 964 . 966 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 967 DOI 10.17487/RFC8288, October 2017, 968 . 970 [W3C.WD-fragid-best-practices-20121025] 971 Tennison, J., "Best Practices for Fragment Identifiers and 972 Media Type Definitions", World Wide Web Consortium WD WD- 973 fragid-best-practices-20121025, October 2012, 974 . 977 Appendix A. Acknowledgments 979 Thanks to Gary Court, Francis Galiegue, Kris Zyp, and Geraint Luff 980 for their work on the initial drafts of JSON Schema. 982 Thanks to Jason Desrosiers, Daniel Perrett, Erik Wilde, Ben Hutton, 983 Evgeny Poberezkin, Brad Bowman, Gowry Sankar, Donald Pipowitch, and 984 Dave Finlay for their submissions and patches to the document. 986 Appendix B. ChangeLog 988 [[CREF6: This section to be removed before leaving Internet-Draft 989 status.]] 991 draft-handrews-json-schema-01 993 * This draft is purely a clarification with no functional changes 995 * Emphasized annotations as a primary usage of JSON Schema 997 * Clarified $id by use cases 999 * Exhaustive schema identification examples 1001 * Replaced "external referencing" with how and when an 1002 implementation might know of a schema from another doucment 1004 * Replaced "internal referencing" with how an implementation 1005 should recognized schema identifiers during parsing 1007 * Dereferencing the former "internal" or "external" references is 1008 always the same process 1010 * Minor formatting improvements 1012 draft-handrews-json-schema-00 1014 * Make the concept of a schema keyword vocabulary more clear 1016 * Note that the concept of "integer" is from a vocabulary, not 1017 the data model 1019 * Classify keywords as assertions or annotations and describe 1020 their general behavior 1022 * Explain the boolean schemas in terms of generalized assertions 1024 * Reserve "$comment" for non-user-visible notes about the schema 1025 * Wording improvements around "$id" and fragments 1027 * Note the challenges of extending meta-schemas with recursive 1028 references 1030 * Add "application/schema-instance+json" media type 1032 * Recommend a "schema" link relation / parameter instead of 1033 "profile" 1035 draft-wright-json-schema-01 1037 * Updated intro 1039 * Allowed for any schema to be a boolean 1041 * "$schema" SHOULD NOT appear in subschemas, although that may 1042 change 1044 * Changed "id" to "$id"; all core keywords prefixed with "$" 1046 * Clarify and formalize fragments for application/schema+json 1048 * Note applicability to formats such as CBOR that can be 1049 represented in the JSON data model 1051 draft-wright-json-schema-00 1053 * Updated references to JSON 1055 * Updated references to HTTP 1057 * Updated references to JSON Pointer 1059 * Behavior for "id" is now specified in terms of RFC3986 1061 * Aligned vocabulary usage for URIs with RFC3986 1063 * Removed reference to draft-pbryan-zyp-json-ref-03 1065 * Limited use of "$ref" to wherever a schema is expected 1067 * Added definition of the "JSON Schema data model" 1069 * Added additional security considerations 1071 * Defined use of subschema identifiers for "id" 1072 * Rewrote section on usage with HTTP 1074 * Rewrote section on usage with rel="describedBy" and 1075 rel="profile" 1077 * Fixed numerous invalid examples 1079 draft-zyp-json-schema-04 1081 * Salvaged from draft v3. 1083 * Split validation keywords into separate document. 1085 * Split hypermedia keywords into separate document. 1087 * Initial post-split draft. 1089 * Mandate the use of JSON Reference, JSON Pointer. 1091 * Define the role of "id". Define URI resolution scope. 1093 * Add interoperability considerations. 1095 draft-zyp-json-schema-00 1097 * Initial draft. 1099 Authors' Addresses 1101 Austin Wright (editor) 1103 EMail: aaa@bzfx.net 1105 Henry Andrews (editor) 1106 Cloudflare, Inc. 1107 San Francisco, CA 1108 USA 1110 EMail: henry@cloudflare.com