idnits 2.17.1 draft-handrews-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 290 has weird spacing: '...ertions produ...' == Line 292 has weird spacing: '...tations attac...' -- The document date (November 19, 2017) is 2350 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 527, but not defined == Missing Reference: '0-9' is mentioned on line 528, 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 (~~), 5 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: May 23, 2018 Cloudflare, Inc. 6 November 19, 2017 8 JSON Schema: A Media Type for Describing JSON Documents 9 draft-handrews-json-schema-00 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 May 23, 2018. 48 Copyright Notice 50 Copyright (c) 2017 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. Hypermedia and Linking . . . . . . . . . . . . . . . . . 4 70 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 71 4.1. JSON Document . . . . . . . . . . . . . . . . . . . . . . 4 72 4.2. Instance . . . . . . . . . . . . . . . . . . . . . . . . 4 73 4.2.1. Instance Data Model . . . . . . . . . . . . . . . . . 4 74 4.2.2. Instance Media Types . . . . . . . . . . . . . . . . 5 75 4.2.3. Instance Equality . . . . . . . . . . . . . . . . . . 6 76 4.3. JSON Schema Documents . . . . . . . . . . . . . . . . . . 6 77 4.3.1. JSON Schema Values and Keywords . . . . . . . . . . . 7 78 4.3.2. JSON Schema Vocabularies . . . . . . . . . . . . . . 7 79 4.3.3. Root Schema and Subschemas . . . . . . . . . . . . . 8 80 5. Fragment Identifiers . . . . . . . . . . . . . . . . . . . . 8 81 6. General Considerations . . . . . . . . . . . . . . . . . . . 9 82 6.1. Range of JSON Values . . . . . . . . . . . . . . . . . . 9 83 6.2. Programming Language Independence . . . . . . . . . . . . 9 84 6.3. Mathematical Integers . . . . . . . . . . . . . . . . . . 9 85 6.4. Extending JSON Schema . . . . . . . . . . . . . . . . . . 10 86 7. The "$schema" Keyword . . . . . . . . . . . . . . . . . . . . 10 87 8. Schema References With "$ref" . . . . . . . . . . . . . . . . 11 88 9. Base URI and Dereferencing . . . . . . . . . . . . . . . . . 11 89 9.1. Initial Base URI . . . . . . . . . . . . . . . . . . . . 11 90 9.2. The "$id" Keyword . . . . . . . . . . . . . . . . . . . . 11 91 9.2.1. Internal References . . . . . . . . . . . . . . . . . 13 92 9.2.2. External References . . . . . . . . . . . . . . . . . 14 93 10. Comments With "$comment" . . . . . . . . . . . . . . . . . . 14 94 11. Usage for Hypermedia . . . . . . . . . . . . . . . . . . . . 14 95 11.1. Linking to a Schema . . . . . . . . . . . . . . . . . . 15 96 11.2. Identifying a Schema via a Media Type Parameter . . . . 15 97 11.3. Usage Over HTTP . . . . . . . . . . . . . . . . . . . . 16 98 12. Security Considerations . . . . . . . . . . . . . . . . . . . 16 99 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 100 13.1. application/schema+json . . . . . . . . . . . . . . . . 17 101 13.2. application/schema-instance+json . . . . . . . . . . . . 17 102 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 103 14.1. Normative References . . . . . . . . . . . . . . . . . . 18 104 14.2. Informative References . . . . . . . . . . . . . . . . . 19 105 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 20 106 Appendix B. ChangeLog . . . . . . . . . . . . . . . . . . . . . 20 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 109 1. Introduction 111 JSON Schema is a JSON media type for defining the structure of JSON 112 data. JSON Schema is intended to define validation, documentation, 113 hyperlink navigation, and interaction control of JSON data. 115 This specification defines JSON Schema core terminology and 116 mechanisms, including pointing to another JSON Schema by reference, 117 dereferencing a JSON Schema reference, and specifying the vocabulary 118 being used. 120 Other specifications define the vocabularies that perform assertions 121 about validation, linking, annotation, navigation, and interaction. 123 2. Conventions and Terminology 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 127 document are to be interpreted as described in RFC 2119 [RFC2119]. 129 The terms "JSON", "JSON text", "JSON value", "member", "element", 130 "object", "array", "number", "string", "boolean", "true", "false", 131 and "null" in this document are to be interpreted as defined in RFC 132 7159 [RFC7159]. 134 3. Overview 136 This document proposes a new media type "application/schema+json" to 137 identify a JSON Schema for describing JSON data. It also proposes a 138 further optional media type, "application/schema-instance+json", to 139 provide additional integration features. JSON Schemas are themselves 140 JSON documents. This, and related specifications, define keywords 141 allowing authors to describe JSON data in several ways. 143 3.1. Validation 145 JSON Schema describes the structure of a JSON document (for instance, 146 required properties and length limitations). Applications can use 147 this information to validate instances (check that constraints are 148 met), or inform interfaces to collect user input such that the 149 constraints are satisfied. 151 Validation behaviour and keywords are specified in a separate 152 document [json-schema-validation]. 154 3.2. Hypermedia and Linking 156 JSON Hyper-Schema describes the hypertext structure of a JSON 157 document. This includes link relations from the instance to other 158 resources, interpretation of instances as multimedia data, and 159 submission data required to use an API. 161 Hyper-schema behaviour and keywords are specified in a separate 162 document [json-hyper-schema]. 164 4. Definitions 166 4.1. JSON Document 168 A JSON document is an information resource (series of octets) 169 described by the application/json media type. 171 In JSON Schema, the terms "JSON document", "JSON text", and "JSON 172 value" are interchangeable because of the data model it defines. 174 JSON Schema is only defined over JSON documents. However, any 175 document or memory structure that can be parsed into or processed 176 according to the JSON Schema data model can be interpreted against a 177 JSON Schema, including media types like CBOR [RFC7049]. 179 4.2. Instance 181 A JSON document to which a schema is applied is known as an 182 "instance". 184 4.2.1. Instance Data Model 186 JSON Schema interprets documents according to a data model. A JSON 187 value interpreted according to this data model is called an 188 "instance". 190 An instance has one of six primitive types, and a range of possible 191 values depending on the type: 193 null A JSON "null" production 195 boolean A "true" or "false" value, from the JSON "true" or "false" 196 productions 198 object An unordered set of properties mapping a string to an 199 instance, from the JSON "object" production 201 array An ordered list of instances, from the JSON "array" production 203 number An arbitrary-precision, base-10 decimal number value, from 204 the JSON "number" production 206 string A string of Unicode code points, from the JSON "string" 207 production 209 Whitespace and formatting concerns, including different lexical 210 representations of numbers that are equal within the data model, are 211 thus outside the scope of JSON Schema. JSON Schema vocabularies 212 (Section 4.3.2) that wish to work with such differences in lexical 213 representations SHOULD define keywords to precisely interpret 214 formatted strings within the data model rather than relying on having 215 the original JSON representation Unicode characters available. 217 Since an object cannot have two properties with the same key, 218 behavior for a JSON document that tries to define two properties (the 219 "member" production) with the same key (the "string" production) in a 220 single object is undefined. 222 Note that JSON Schema vocabularies are free to define their own 223 extended type system. This should not be confused with the core data 224 model types defined here. As an example, "integer" is a reasonable 225 type for a vocabulary to define as a value for a keyword, but the 226 data model makes no distinction between integers and other numbers. 228 4.2.2. Instance Media Types 230 JSON Schema is designed to fully work with "application/json" 231 documents, as well as media types using the "+json" structured syntax 232 suffix. 234 Some functionality that is useful for working with schemas is defined 235 by each media type, namely media type parameters and URI fragment 236 identifier syntax and semantics. These features are useful in 237 content negotiation and in calculating URIs for specific locations 238 within an instance, respectively. 240 This specification defines the "application/schema-instance+json" 241 media type in order to allow instance authors to take full advantage 242 of parameters and fragment identifiers for these purposes. 244 4.2.3. Instance Equality 246 Two JSON instances are said to be equal if and only if they are of 247 the same type and have the same value according to the data model. 248 Specifically, this means: 250 both are null; or 252 both are true; or 254 both are false; or 256 both are strings, and are the same codepoint-for-codepoint; or 258 both are numbers, and have the same mathematical value; or 260 both are arrays, and have an equal value item-for-item; or 262 both are objects, and each property in one has exactly one 263 property with a key equal to the other's, and that other property 264 has an equal value. 266 Implied in this definition is that arrays must be the same length, 267 objects must have the same number of members, properties in objects 268 are unordered, there is no way to define multiple properties with the 269 same key, and mere formatting differences (indentation, placement of 270 commas, trailing zeros) are insignificant. 272 4.3. JSON Schema Documents 274 A JSON Schema document, or simply a schema, is a JSON document used 275 to describe an instance. A schema is itself interpreted as an 276 instance, but SHOULD always be given the media type "application/ 277 schema+json" rather than "application/schema-instance+json". The 278 "application/schema+json" media type is defined to offer a superset 279 of the media type parameter and fragment identifier syntax and 280 semantics provided by "application/schema-instance+json". 282 4.3.1. JSON Schema Values and Keywords 284 A JSON Schema MUST be an object or a boolean. 286 Object properties that are applied to the instance are called 287 keywords, or schema keywords. Broadly speaking, keywords fall into 288 one or both of two categories: 290 assertions produce a boolean result when applied to an instance 292 annotations attach information to an instance for application use 294 Keywords may fall into either or both categories. Extension 295 keywords, meaning those defined outside of this document and its 296 companions, are free to define other behaviors as well. 298 The boolean schema values "true" and "false" are trivial assertions 299 that always return themselves regardless of the instance value. As 300 an example, in terms of the validation vocabulary, boolean schemas 301 are equivalent to the following behaviors: 303 true Always passes validation, as if the empty schema {} 305 false Always fails validation, as if the schema { "not":{} } 307 A JSON Schema MAY contain properties which are not schema keywords. 308 Unknown keywords SHOULD be ignored. 310 An empty schema is a JSON Schema with no properties, or only unknown 311 properties. 313 4.3.2. JSON Schema Vocabularies 315 A JSON Schema vocabulary is a set of keywords defined for a 316 particular purpose. The vocabulary specifies the meaning of its 317 keywords as assertions, annotations, and/or any vocabulary-defined 318 keyword category. The two companion standards to this document each 319 define a vocabulary: One for instance validation, and one for 320 hypermedia annotations. Vocabularies are the primary mechanism for 321 extensibility within the JSON Schema media type. 323 Vocabularies may be defined by any entity. Vocabulary authors SHOULD 324 take care to avoid keyword name collisions if the vocabulary is 325 intended for broad use, and potentially combined with other 326 vocabularies. JSON Schema does not provide any formal namespacing 327 system, but also does not constrain keyword names, allowing for any 328 number of namespacing approaches. 330 Vocabularies may build on each other, such as by defining the 331 behavior of their keywords with respect to the behavior of keywords 332 from another vocabulary, or by using a keyword from another 333 vocabulary with a restricted or expanded set of acceptable values. 334 Not all such vocabulary re-use will result in a new vocabulary that 335 is compatible with the vocabulary on which it is built. Vocabulary 336 authors SHOULD clearly document what level of compatibility, if any, 337 is expected. 339 A schema that itself describes a schema is called a meta-schema. 340 Meta-schemas are used to validate JSON Schemas and specify which 341 vocabulary it is using. [[CREF1: Currently, only a single meta- 342 schema may be specified per schema, meaning that in order to use 343 multiple vocabularies, a meta-schema must be written that encompasses 344 all of them. The hyper-schema meta-schema is an example of this, as 345 it encompasses the validation vocabulary as well as the hypermedia 346 vocabulary. ]] 348 4.3.3. Root Schema and Subschemas 350 The root schema is the schema that comprises the entire JSON document 351 in question. 353 Some keywords take schemas themselves, allowing JSON Schemas to be 354 nested: 356 { 357 "title": "root", 358 "items": { 359 "title": "array item" 360 } 361 } 363 In this example document, the schema titled "array item" is a 364 subschema, and the schema titled "root" is the root schema. 366 As with the root schema, a subschema is either an object or a 367 boolean. 369 5. Fragment Identifiers 371 In accordance with section 3.1 of [RFC6839], the syntax and semantics 372 of fragment identifiers specified for any +json media type SHOULD be 373 as specified for "application/json". (At publication of this 374 document, there is no fragment identification syntax defined for 375 "application/json".) 376 Additionally, the "application/schema+json" media type supports two 377 fragment identifier structures: plain names and JSON Pointers. The 378 "application/schema-instance+json" media type supports one fragment 379 identifier structure: JSON Pointers. 381 The use of JSON Pointers as URI fragment identifiers is described in 382 RFC 6901 [RFC6901]. For "application/schema+json", which supports 383 two fragment identifier syntaxes, fragment identifiers matching the 384 JSON Pointer syntax, including the empty string, MUST be interpreted 385 as JSON Pointer fragment identifiers. 387 Per the W3C's best practices for fragment identifiers 388 [W3C.WD-fragid-best-practices-20121025], plain name fragment 389 identifiers in "application/schema+json" are reserved for referencing 390 locally named schemas. All fragment identifiers that do not match 391 the JSON Pointer syntax MUST be interpreted as plain name fragment 392 identifiers. 394 Defining and referencing a plain name fragment identifier within an 395 "application/schema+json" document are specified in the "$id" keyword 396 (Section 9.2) section. 398 6. General Considerations 400 6.1. Range of JSON Values 402 An instance may be any valid JSON value as defined by JSON [RFC7159]. 403 JSON Schema imposes no restrictions on type: JSON Schema can describe 404 any JSON value, including, for example, null. 406 6.2. Programming Language Independence 408 JSON Schema is programming language agnostic, and supports the full 409 range of values described in the data model. Be aware, however, that 410 some languages and JSON parsers may not be able to represent in 411 memory the full range of values describable by JSON. 413 6.3. Mathematical Integers 415 Some programming languages and parsers use different internal 416 representations for floating point numbers than they do for integers. 418 For consistency, integer JSON numbers SHOULD NOT be encoded with a 419 fractional part. 421 6.4. Extending JSON Schema 423 Implementations MAY define additional keywords to JSON Schema. Save 424 for explicit agreement, schema authors SHALL NOT expect these 425 additional keywords to be supported by peer implementations. 426 Implementations SHOULD ignore keywords they do not support. 428 Authors of extensions to JSON Schema are encouraged to write their 429 own meta-schemas, which extend the existing meta-schemas using 430 "allOf". This extended meta-schema SHOULD be referenced using the 431 "$schema" keyword, to allow tools to follow the correct behaviour. 433 Note that the recursive nature of meta-schemas requires re-defining 434 recursive keywords in the extended meta-schema, as can be seen in the 435 JSON Hyper-Schema meta-schema. 437 7. The "$schema" Keyword 439 The "$schema" keyword is both used as a JSON Schema version 440 identifier and the location of a resource which is itself a JSON 441 Schema, which describes any schema written for this particular 442 version. 444 The value of this keyword MUST be a URI [RFC3986] (containing a 445 scheme) and this URI MUST be normalized. The current schema MUST be 446 valid against the meta-schema identified by this URI. 448 If this URI identifies a retrievable resource, that resource SHOULD 449 be of media type "application/schema+json". 451 The "$schema" keyword SHOULD be used in a root schema. It MUST NOT 452 appear in subschemas. 454 [[CREF2: Using multiple "$schema" keywords in the same document would 455 imply that the vocabulary and therefore behavior can change within a 456 document. This would necessitate resolving a number of 457 implementation concerns that have not yet been clearly defined. So, 458 while the pattern of using "$schema" only in root schemas is likely 459 to remain the best practice for schema authoring, implementation 460 behavior is subject to be revised or liberalized in future drafts. 461 ]] 463 Values for this property are defined in other documents and by other 464 parties. JSON Schema implementations SHOULD implement support for 465 current and previous published drafts of JSON Schema vocabularies as 466 deemed reasonable. 468 8. Schema References With "$ref" 470 The "$ref" keyword is used to reference a schema, and provides the 471 ability to validate recursive structures through self-reference. 473 An object schema with a "$ref" property MUST be interpreted as a 474 "$ref" reference. The value of the "$ref" property MUST be a URI 475 Reference. Resolved against the current URI base, it identifies the 476 URI of a schema to use. All other properties in a "$ref" object MUST 477 be ignored. 479 The URI is not a network locator, only an identifier. A schema need 480 not be downloadable from the address if it is a network-addressable 481 URL, and implementations SHOULD NOT assume they should perform a 482 network operation when they encounter a network-addressable URI. 484 A schema MUST NOT be run into an infinite loop against a schema. For 485 example, if two schemas "#alice" and "#bob" both have an "allOf" 486 property that refers to the other, a naive validator might get stuck 487 in an infinite recursive loop trying to validate the instance. 488 Schemas SHOULD NOT make use of infinite recursive nesting like this; 489 the behavior is undefined. 491 9. Base URI and Dereferencing 493 9.1. Initial Base URI 495 RFC3986 Section 5.1 [RFC3986] defines how to determine the default 496 base URI of a document. 498 Informatively, the initial base URI of a schema is the URI at which 499 it was found, or a suitable substitute URI if none is known. 501 9.2. The "$id" Keyword 503 The "$id" keyword defines a URI for the schema, and the base URI that 504 other URI references within the schema are resolved against. A 505 subschema's "$id" is resolved against the base URI of its parent 506 schema. If no parent sets an explicit base with "$id", the base URI 507 is that of the entire document, as determined per RFC 3986 section 5 508 [RFC3986]. 510 If present, the value for this keyword MUST be a string, and MUST 511 represent a valid URI-reference [RFC3986]. This value SHOULD be 512 normalized, and SHOULD NOT be an empty fragment <#> or an empty 513 string <>. 515 The root schema of a JSON Schema document SHOULD contain an "$id" 516 keyword with a URI (containing a scheme). This URI SHOULD either not 517 have a fragment, or have one that is an empty string. [[CREF3: How 518 should an "$id" URI reference containing a fragment with other 519 components be interpreted? There are two cases: when the other 520 components match the current base URI and when they change the base 521 URI. ]] 523 To name subschemas in a JSON Schema document, subschemas can use 524 "$id" to give themselves a document-local identifier. This is done 525 by setting "$id" to a URI reference consisting only of a plain name 526 fragment (not a JSON Pointer fragment). The fragment identifier MUST 527 begin with a letter ([A-Za-z]), followed by any number of letters, 528 digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), or 529 periods ("."). 531 Providing a plain name fragment enables a subschema to be relocated 532 within a schema without requiring that JSON Pointer references are 533 updated. 535 The effect of defining a fragment-only "$id" URI reference that 536 neither matches the above requirements nor is a valid JSON pointer is 537 not defined. 539 For example: 541 { 542 "$id": "http://example.com/root.json", 543 "definitions": { 544 "A": { "$id": "#foo" }, 545 "B": { 546 "$id": "other.json", 547 "definitions": { 548 "X": { "$id": "#bar" }, 549 "Y": { "$id": "t/inner.json" } 550 } 551 }, 552 "C": { 553 "$id": "urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f" 554 } 555 } 556 } 558 The schemas at the following URI-encoded JSON Pointers [RFC6901] 559 (relative to the root schema) have the following base URIs, and are 560 identifiable by either URI in accordance with Section 5 above: 562 # (document root) http://example.com/root.json# 564 #/definitions/A http://example.com/root.json#foo 566 #/definitions/B http://example.com/other.json 568 #/definitions/B/definitions/X http://example.com/other.json#bar 570 #/definitions/B/definitions/Y http://example.com/t/inner.json 572 #/definitions/C urn:uuid:ee564b8a-7a87-4125-8c96-e9f123d6766f 574 9.2.1. Internal References 576 Schemas can be identified by any URI that has been given to them, 577 including a JSON Pointer or their URI given directly by "$id". 579 Tools SHOULD take note of the URIs that schemas, including 580 subschemas, provide for themselves using "$id". This is known as 581 "Internal referencing". 583 For example, consider this schema: 585 { 586 "$id": "http://example.net/root.json", 587 "items": { 588 "type": "array", 589 "items": { "$ref": "#item" } 590 }, 591 "definitions": { 592 "single": { 593 "$id": "#item", 594 "type": "integer" 595 } 596 } 597 } 599 When an implementation encounters the <#/definitions/single> schema, 600 it resolves the "$id" URI reference against the current base URI to 601 form . 603 When an implementation then looks inside the <#/items> schema, it 604 encounters the <#item> reference, and resolves this to 605 which is understood as the schema 606 defined elsewhere in the same document without needing to resolve the 607 fragment against the base URI. 609 9.2.2. External References 611 To differentiate schemas between each other in a vast ecosystem, 612 schemas are identified by URI. As specified above, this does not 613 necessarily mean anything is downloaded, but instead JSON Schema 614 implementations SHOULD already understand the schemas they will be 615 using, including the URIs that identify them. 617 Implementations SHOULD be able to associate arbitrary URIs with an 618 arbitrary schema and/or automatically associate a schema's "$id"- 619 given URI, depending on the trust that the validator has in the 620 schema. 622 A schema MAY (and likely will) have multiple URIs, but there is no 623 way for a URI to identify more than one schema. When multiple 624 schemas try to identify with the same URI, validators SHOULD raise an 625 error condition. 627 10. Comments With "$comment" 629 This keyword is reserved for comments from schema authors to readers 630 or maintainers of the schema. The value of this keyword MUST be a 631 string. Implementations MUST NOT present this string to end users. 632 Tools for editing schemas SHOULD support displaying and editing this 633 keyword. The value of this keyword MAY be used in debug or error 634 output which is intended for developers making use of schemas. 635 Schema vocabularies SHOULD allow "$comment" within any object 636 containing vocabulary keywords. Implementations MAY assume 637 "$comment" is allowed unless the vocabulary specifically forbids it. 638 Vocabularies MUST NOT specify any effect of "$comment" beyond what is 639 described in this specification. Tools that translate other media 640 types or programming languages to and from application/schema+json 641 MAY choose to convert that media type or programming language's 642 native comments to or from "$comment" values. The behavior of such 643 translation when both native comments and "$comment" properties are 644 present is implementation-dependent. Implementations SHOULD treat 645 "$comment" identically to an unknown extension keyword. They MAY 646 strip "$comment" values at any point during processing. In 647 particular, this allows for shortening schemas when the size of 648 deployed schemas is a concern. Implementations MUST NOT take any 649 other action based on the presence, absence, or contents of 650 "$comment" properties. 652 11. Usage for Hypermedia 654 JSON has been adopted widely by HTTP servers for automated APIs and 655 robots. This section describes how to enhance processing of JSON 656 documents in a more RESTful manner when used with protocols that 657 support media types and Web linking [RFC8288]. 659 11.1. Linking to a Schema 661 It is RECOMMENDED that instances described by a schema provide a link 662 to a downloadable JSON Schema using the link relation "describedby", 663 as defined by Linked Data Protocol 1.0, section 8.1 664 [W3C.REC-ldp-20150226]. 666 In HTTP, such links can be attached to any response using the Link 667 header [RFC8288]. An example of such a header would be: 669 Link: ; rel="describedby" 671 11.2. Identifying a Schema via a Media Type Parameter 673 Media types MAY allow for a "schema" media type parameter, which 674 gives HTTP servers the ability to perform Content-Type Negotiation 675 based on schema. The media-type parameter MUST be a whitespace- 676 separated list of URIs (i.e. relative references are invalid). 678 When using the media type application/schema-instance+json, the 679 "schema" parameter MUST be supplied. 681 The schema URI is opaque and SHOULD NOT automatically be 682 dereferenced. If the implementation does not understand the 683 semantics of the provided schema, the implementation can instead 684 follow the "describedby" links, if any, which may provide information 685 on how to handle the schema. Since "schema" doesn't necessarily 686 point to a network location, the "describedby" relation is used for 687 linking to a downloadable schema. However, for simplicity, schema 688 authors should make these URIs point to the same resource when 689 possible. 691 In HTTP, the media-type parameter would be sent inside the Content- 692 Type header: 694 Content-Type: application/json; 695 schema="http://example.com/my-hyper-schema#" 697 Multiple schemas are whitespace separated: 699 Content-Type: application/json; 700 schema="http://example.com/alice http://example.com/bob" 702 [[CREF4: This paragraph assumes that we can register a "schema" link 703 relation. Should we instead specify something like "tag:json- 704 schema.org,2017:schema" for now? ]] HTTP can also send the "schema" 705 in a Link, though this may impact media-type semantics and Content- 706 Type negotiation if this replaces the media-type parameter entirely: 708 Link: ;rel="schema", ;rel="schema" 710 11.3. Usage Over HTTP 712 When used for hypermedia systems over a network, HTTP [RFC7231] is 713 frequently the protocol of choice for distributing schemas. 714 Misbehaving clients can pose problems for server maintainers if they 715 pull a schema over the network more frequently than necessary, when 716 it's instead possible to cache a schema for a long period of time. 718 HTTP servers SHOULD set long-lived caching headers on JSON Schemas. 719 HTTP clients SHOULD observe caching headers and not re-request 720 documents within their freshness period. Distributed systems SHOULD 721 make use of a shared cache and/or caching proxy. 723 Clients SHOULD set or prepend a User-Agent header specific to the 724 JSON Schema implementation or software product. Since symbols are 725 listed in decreasing order of significance, the JSON Schema library 726 name/version should precede the more generic HTTP library name (if 727 any). For example: 729 User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0 731 Clients SHOULD be able to make requests with a "From" header so that 732 server operators can contact the owner of a potentially misbehaving 733 script. 735 12. Security Considerations 737 Both schemas and instances are JSON values. As such, all security 738 considerations defined in RFC 7159 [RFC7159] apply. 740 Instances and schemas are both frequently written by untrusted third 741 parties, to be deployed on public Internet servers. Validators 742 should take care that the parsing of schemas doesn't consume 743 excessive system resources. Validators MUST NOT fall into an 744 infinite loop. 746 Servers need to take care that malicious parties can't change the 747 functionality of existing schemas by uploading a schema with an pre- 748 existing or very similar "$id". 750 Individual JSON Schema vocabularies are liable to also have their own 751 security considerations. Consult the respective specifications for 752 more information. 754 Schema authors should take care with "$comment" contents, as a 755 malicious implementation can display them to end-users in violation 756 of a spec, or fail to strip them if such behavior is expected. 758 A malicious schema author could place executable code or other 759 dangerous material within a "$comment". Implementations MUST NOT 760 parse or otherwise take action based on "$comment" contents. 762 13. IANA Considerations 764 13.1. application/schema+json 766 The proposed MIME media type for JSON Schema is defined as follows: 768 Type name: application 770 Subtype name: schema+json 772 Required parameters: N/A 774 Encoding considerations: Encoding considerations are identical to 775 those specified for the "application/json" media type. See JSON 776 [RFC7159]. 778 Security considerations: See Section 12 above. 780 Interoperability considerations: See Sections 6.2 and 6.3 above. 782 Fragment identifier considerations: See Section 5 784 13.2. application/schema-instance+json 786 The proposed MIME media type for JSON Schema Instances that require a 787 JSON Schema-specific media type is defined as follows: 789 Type name: application 790 Subtype name: schema-instance+json 792 Required parameters: 794 schema A non-empty list of space-separated URIs, each identifying 795 a JSON Schema resource. The instance SHOULD successfully 796 validate against at least one of these schemas. Non-validating 797 schemas MAY be included for purposes such as allowing clients 798 to make use of older versions of a schema as long as the 799 runtime instance validates against that older version. 801 Encoding considerations: Encoding considerations are identical to 802 those specified for the "application/json" media type. See JSON 803 [RFC7159]. 805 Security considerations: See Section 12 above. 807 Interoperability considerations: See Sections 6.2 and 6.3 above. 809 Fragment identifier considerations: See Section 5 811 14. References 813 14.1. Normative References 815 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 816 Requirement Levels", BCP 14, RFC 2119, 817 DOI 10.17487/RFC2119, March 1997, 818 . 820 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 821 Resource Identifier (URI): Generic Syntax", STD 66, 822 RFC 3986, DOI 10.17487/RFC3986, January 2005, 823 . 825 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 826 Structured Syntax Suffixes", RFC 6839, 827 DOI 10.17487/RFC6839, January 2013, 828 . 830 [RFC6901] Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., 831 "JavaScript Object Notation (JSON) Pointer", RFC 6901, 832 DOI 10.17487/RFC6901, April 2013, 833 . 835 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 836 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 837 2014, . 839 [W3C.REC-ldp-20150226] 840 Speicher, S., Arwe, J., and A. Malhotra, "Linked Data 841 Platform 1.0", World Wide Web Consortium Recommendation 842 REC-ldp-20150226, February 2015, 843 . 845 14.2. Informative References 847 [json-hyper-schema] 848 Andrews, H. and A. Wright, "JSON Hyper-Schema: A 849 Vocabulary for Hypermedia Annotation of JSON", draft- 850 handrews-json-schema-hyperschema-00 (work in progress), 851 November 2017. 853 [json-schema-validation] 854 Wright, A., Andrews, H., and G. Luff, "JSON Schema 855 Validation: A Vocabulary for Structural Validation of 856 JSON", draft-handrews-json-schema-validation-00 (work in 857 progress), November 2017. 859 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 860 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 861 October 2013, . 863 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 864 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 865 DOI 10.17487/RFC7231, June 2014, 866 . 868 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 869 DOI 10.17487/RFC8288, October 2017, 870 . 872 [W3C.WD-fragid-best-practices-20121025] 873 Tennison, J., "Best Practices for Fragment Identifiers and 874 Media Type Definitions", World Wide Web Consortium 875 LastCall WD-fragid-best-practices-20121025, October 2012, 876 . 879 Appendix A. Acknowledgments 881 Thanks to Gary Court, Francis Galiegue, Kris Zyp, and Geraint Luff 882 for their work on the initial drafts of JSON Schema. 884 Thanks to Jason Desrosiers, Daniel Perrett, Erik Wilde, Ben Hutton, 885 Evgeny Poberezkin, Brad Bowman, Gowry Sankar, Donald Pipowitch, and 886 Dave Finlay for their submissions and patches to the document. 888 Appendix B. ChangeLog 890 [[CREF5: This section to be removed before leaving Internet-Draft 891 status.]] 893 draft-handrews-json-schema-00 895 * Make the concept of a schema keyword vocabulary more clear 897 * Note that the concept of "integer" is from a vocabulary, not 898 the data model 900 * Classify keywords as assertions or annotations and describe 901 their general behavior 903 * Explain the boolean schemas in terms of generalized assertions 905 * Reserve "$comment" for non-user-visible notes about the schema 907 * Wording improvements around "$id" and fragments 909 * Note the challenges of extending meta-schemas with recursive 910 references 912 * Add "application/schema-instance+json" media type 914 * Recommend a "schema" link relation / parameter instead of 915 "profile" 917 draft-wright-json-schema-01 919 * Updated intro 921 * Allowed for any schema to be a boolean 923 * "$schema" SHOULD NOT appear in subschemas, although that may 924 change 926 * Changed "id" to "$id"; all core keywords prefixed with "$" 927 * Clarify and formalize fragments for application/schema+json 929 * Note applicability to formats such as CBOR that can be 930 represented in the JSON data model 932 draft-wright-json-schema-00 934 * Updated references to JSON 936 * Updated references to HTTP 938 * Updated references to JSON Pointer 940 * Behavior for "id" is now specified in terms of RFC3986 942 * Aligned vocabulary usage for URIs with RFC3986 944 * Removed reference to draft-pbryan-zyp-json-ref-03 946 * Limited use of "$ref" to wherever a schema is expected 948 * Added definition of the "JSON Schema data model" 950 * Added additional security considerations 952 * Defined use of subschema identifiers for "id" 954 * Rewrote section on usage with HTTP 956 * Rewrote section on usage with rel="describedBy" and 957 rel="profile" 959 * Fixed numerous invalid examples 961 draft-zyp-json-schema-04 963 * Split validation keywords into separate document 965 draft-zyp-json-schema-00 967 * Initial draft. 969 * Salvaged from draft v3. 971 * Mandate the use of JSON Reference, JSON Pointer. 973 * Define the role of "id". Define URI resolution scope. 975 * Add interoperability considerations. 977 Authors' Addresses 979 Austin Wright (editor) 981 EMail: aaa@bzfx.net 983 Henry Andrews (editor) 984 Cloudflare, Inc. 985 San Francisco, CA 986 USA 988 EMail: henry@cloudflare.com