idnits 2.17.1 draft-zyp-json-schema-04.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 413 has weird spacing: '.../nested http:...' == Line 414 has weird spacing: '...onested http:...' -- The document date (January 31, 2013) is 4096 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 ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force F. Galiegue, Ed. 3 Internet-Draft 4 Intended status: Informational K. Zyp, Ed. 5 Expires: August 4, 2013 SitePen (USA) 6 G. Court 7 January 31, 2013 9 JSON Schema: core definitions and terminology 10 draft-zyp-json-schema-04 12 Abstract 14 JSON Schema defines the media type "application/schema+json", a JSON 15 based format for defining the structure of JSON data. JSON Schema 16 provides a contract for what JSON data is required for a given 17 application and how to interact with it. JSON Schema is intended to 18 define validation, documentation, hyperlink navigation, and 19 interaction control of JSON data. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on August 4, 2013. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3 57 3. Core terminology . . . . . . . . . . . . . . . . . . . . . . . 3 58 3.1. Property, item . . . . . . . . . . . . . . . . . . . . . . 3 59 3.2. JSON Schema, keywords . . . . . . . . . . . . . . . . . . 3 60 3.3. Empty schema . . . . . . . . . . . . . . . . . . . . . . . 3 61 3.4. Root schema, subschema . . . . . . . . . . . . . . . . . . 4 62 3.5. JSON Schema primitive types . . . . . . . . . . . . . . . 4 63 3.6. JSON value equality . . . . . . . . . . . . . . . . . . . 5 64 3.7. Instance . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 4.1. Validation . . . . . . . . . . . . . . . . . . . . . . . . 5 67 4.2. Hypermedia and linking . . . . . . . . . . . . . . . . . . 6 68 5. General considerations . . . . . . . . . . . . . . . . . . . . 6 69 5.1. Applicability to all JSON values . . . . . . . . . . . . . 6 70 5.2. Programming language independence . . . . . . . . . . . . 6 71 5.3. JSON Schema and HTTP . . . . . . . . . . . . . . . . . . . 6 72 5.4. JSON Schema and other protocols . . . . . . . . . . . . . 6 73 5.5. Mathematical integers . . . . . . . . . . . . . . . . . . 7 74 5.6. Extending JSON Schema . . . . . . . . . . . . . . . . . . 7 75 5.7. Security considerations . . . . . . . . . . . . . . . . . 7 76 6. The "$schema" keyword . . . . . . . . . . . . . . . . . . . . 7 77 6.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 7 78 6.2. Customization . . . . . . . . . . . . . . . . . . . . . . 8 79 7. URI resolution scopes and dereferencing . . . . . . . . . . . 8 80 7.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 8 81 7.2. URI resolution scope alteration with the "id" keyword . . 8 82 7.2.1. Valid values . . . . . . . . . . . . . . . . . . . . . 8 83 7.2.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . 9 84 7.2.3. Canonical dereferencing and inline dereferencing . . . 10 85 7.2.4. Inline dereferencing and fragments . . . . . . . . . . 11 86 7.3. Interoperability considerations . . . . . . . . . . . . . 11 87 8. Recommended correlation mechanisms for use with the HTTP 88 protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 89 8.1. Correlation by means of the "Content-Type" header . . . . 11 90 8.2. Correlation by means of the "Link" header . . . . . . . . 12 91 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 92 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 93 10.1. Normative References . . . . . . . . . . . . . . . . . . . 12 94 10.2. Informative References . . . . . . . . . . . . . . . . . . 12 95 Appendix A. ChangeLog . . . . . . . . . . . . . . . . . . . . . . 13 97 1. Introduction 99 JSON Schema is a JSON media type for defining the structure of JSON 100 data. JSON Schema provides a contract for what JSON data is required 101 for a given application and how to interact with it. JSON Schema is 102 intended to define validation, documentation, hyperlink navigation, 103 and interaction control of JSON data. 105 This specification defines JSON Schema core terminology and 106 mechanisms; related specifications build upon this specification and 107 define different applications of JSON Schema. 109 2. Conventions and Terminology 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in RFC 2119 [RFC2119]. 115 The terms "JSON", "JSON text", "JSON value", "member", "element", 116 "object", "array", "number", "string", "boolean", "true", "false", 117 and "null" in this document are to be interpreted as defined in RFC 118 4627 [RFC4627]. 120 3. Core terminology 122 3.1. Property, item 124 When refering to a JSON Object, as defined by [RFC4627], the terms 125 "member" and "property" may be used interchangeably. 127 When refering to a JSON Array, as defined by [RFC4627], the terms 128 "element" and "item" may be used interchangeably. 130 3.2. JSON Schema, keywords 132 A JSON Schema is a JSON document, and that document MUST be an 133 object. Object members (or properties) defined by JSON Schema (this 134 specification, or related specifications) are called keywords, or 135 schema keywords. 137 A JSON Schema MAY contain properties which are not schema keywords. 139 3.3. Empty schema 141 An empty schema is a JSON Schema with no properties, or with 142 properties which are not schema keywords. 144 3.4. Root schema, subschema 146 This example of a JSON Schema has no subschemas: 148 { 149 "title": "root" 150 } 152 JSON Schemas can also be nested, as in this example: 154 { 155 "title": "root", 156 "otherSchema": { 157 "title": "nested", 158 "anotherSchema": { 159 "title": "alsoNested" 160 } 161 } 162 } 164 In this example, "nested" and "alsoNested" are subschemas, and "root" 165 is a root schema. 167 3.5. JSON Schema primitive types 169 JSON Schema defines seven primitive types for JSON values: 171 array A JSON array. 173 boolean A JSON boolean. 175 integer A JSON number without a fraction or exponent part. 177 number Any JSON number. Number includes integer. 179 null The JSON null value. 181 object A JSON object. 183 string A JSON string. 185 3.6. JSON value equality 187 Two JSON values are said to be equal if and only if: 189 both are nulls; or 191 both are booleans, and have the same value; or 193 both are strings, and have the same value; or 195 both are numbers, and have the same mathematical value; or 197 both are arrays, and: 199 have the same number of items; and 201 items at the same index are equal according to this definition; 202 or 204 both are objects, and: 206 have the same set of property names; and 208 values for a same property name are equal according to this 209 definition. 211 3.7. Instance 213 An instance is any JSON value. An instance may be described by one 214 or more schemas. 216 An instance may also be referred to as "JSON instance", or "JSON 217 data". 219 4. Overview 221 This document proposes a new media type "application/schema+json" to 222 identify JSON Schema for describing JSON data. JSON Schemas are 223 themselves written in JSON. This, and related specifications, define 224 keywords allowing to describe this data in terms of allowable values, 225 textual descriptions and interpreting relations with other resources. 226 The following sections are a summary of features defined by related 227 specifications. 229 4.1. Validation 231 JSON Schema allows applications to validate instances, either non 232 interactively or interactively. For instance, an application may 233 collect JSON data and check that this data matches a given set of 234 constraints; another application may use a JSON Schema to build an 235 interactive interface in order to collect user input according to 236 constraints described by JSON Schema. 238 4.2. Hypermedia and linking 240 JSON Schema provides a method for extracting link relations from 241 instances to other resources, as well as describing interpretations 242 of instances as multimedia data. This allows JSON data to be 243 interpreted as rich hypermedia documents, placed in the context of a 244 larger set of related resources. 246 5. General considerations 248 5.1. Applicability to all JSON values 250 It is acknowledged that an instance may be any valid JSON value as 251 defined by [RFC4627]. As such, JSON Schema does not mandate that an 252 instance be of a particular type: JSON Schema can describe any JSON 253 value, including null. 255 5.2. Programming language independence 257 JSON Schema is programming language agnostic. The only limitations 258 are the ones expressed by [RFC4627] and those of the host programming 259 language. 261 5.3. JSON Schema and HTTP 263 This specification acknowledges the role of HTTP [RFC2616] as the 264 dominant protocol in use on the Internet, and the wealth of official 265 specifications related to it. 267 This specification uses a subset of these specifications to recommend 268 a set of mechanisms, usable by this protocol, to associate JSON 269 instances to one or more schemas. 271 5.4. JSON Schema and other protocols 273 JSON Schema does not define any semantics for the client-server 274 interface for any other protocols than HTTP. These semantics are 275 application dependent, or subject to agreement between the parties 276 involved in the use of JSON Schema for their own needs. 278 5.5. Mathematical integers 280 It is acknowledged by this specification that some programming 281 languages, and their associated parsers, use different internal 282 representations for floating point numbers and integers, while others 283 do not. 285 As a consequence, for interoperability reasons, JSON values used in 286 the context of JSON Schema, whether that JSON be a JSON Schema or an 287 instance, SHOULD ensure that mathematical integers be represented as 288 integers as defined by this specification. 290 5.6. Extending JSON Schema 292 Implementations MAY choose to define additional keywords to JSON 293 Schema. Save for explicit agreement, schema authors SHALL NOT expect 294 these additional keywords to be supported by peer implementations. 295 Implementations SHOULD ignore keywords they do not support. 297 5.7. Security considerations 299 Both schemas and instances are JSON values. As such, all security 300 considerations defined in RFC 4627 [RFC4627] apply. 302 6. The "$schema" keyword 304 6.1. Purpose 306 The "$schema" keyword is both used as a JSON Schema version 307 identifier and the location of a resource which is itself a JSON 308 Schema, which describes any schema written for this particular 309 version. 311 This keyword MUST be located at the root of a JSON Schema. The value 312 of this keyword MUST be a URI [RFC3986] and a valid JSON Reference 313 [json-reference]; this URI MUST be both absolute and normalized. The 314 resource located at this URI MUST successfully describe itself. It 315 is RECOMMENDED that schema authors include this keyword in their 316 schemas. 318 The following values are predefined: 320 http://json-schema.org/schema# JSON Schema written against the 321 current version of the specification. 323 http://json-schema.org/hyper-schema# JSON Schema written against the 324 current version of the specification. 326 http://json-schema.org/draft-04/schema# JSON Schema written against 327 this version. 329 http://json-schema.org/draft-04/hyper-schema# JSON Schema 330 hyperschema written against this version. 332 http://json-schema.org/draft-03/schema# JSON Schema written against 333 JSON Schema, draft v3 [json-schema-03]. 335 http://json-schema.org/draft-03/hyper-schema# JSON Schema 336 hyperschema written against JSON Schema, draft v3 337 [json-schema-03]. 339 6.2. Customization 341 When extending JSON Schema with custom keywords, schema authors 342 SHOULD define a custom URI for "$schema". This custom URI MUST NOT 343 be one of the predefined values. 345 7. URI resolution scopes and dereferencing 347 7.1. Definition 349 JSON Schema uses JSON Reference [json-reference] as a mechanism for 350 schema addressing. It extends this specification in two ways: 352 JSON Schema offers facilities to alter the base URI against which 353 a reference must resolve by the means of the "id" keyword; 355 it defines a specific dereferencing mechanism extending JSON 356 Reference to accept arbitrary fragment parts. 358 Altering the URI within a schema is called defining a new resolution 359 scope. The initial resolution scope of a schema is the URI of the 360 schema itself, if any, or the empty URI if the schema was not loaded 361 from a URI. 363 7.2. URI resolution scope alteration with the "id" keyword 365 7.2.1. Valid values 367 The value for this keyword MUST be a string, and MUST be a valid URI. 368 This URI MUST be normalized, and SHOULD NOT be an empty fragment (#) 369 or the empty URI. 371 7.2.2. Usage 373 The "id" keyword (or "id", for short) is used to alter the resolution 374 scope. When an id is encountered, an implementation MUST resolve 375 this id against the most immediate parent scope. The resolved URI 376 will be the new resolution scope for this subschema and all its 377 children, until another id is encountered. 379 When using "id" to alter resolution scopes, schema authors SHOULD 380 ensure that resolution scopes are unique within the schema. 382 This schema will be taken as an example: 384 { 385 "id": "http://x.y.z/rootschema.json#", 386 "schema1": { 387 "id": "#foo" 388 }, 389 "schema2": { 390 "id": "otherschema.json", 391 "nested": { 392 "id": "#bar" 393 }, 394 "alsonested": { 395 "id": "t/inner.json#a" 396 } 397 }, 398 "schema3": { 399 "id": "some://where.else/completely#" 400 } 401 } 403 Subschemas at the following URI-encoded JSON Pointer [json-pointer]s 404 (starting from the root schema) define the following resolution 405 scopes: 407 # (document root) http://x.y.z/rootschema.json# 409 #/schema1 http://x.y.z/rootschema.json#foo 411 #/schema2 http://x.y.z/otherschema.json# 413 #/schema2/nested http://x.y.z/otherschema.json#bar 414 #/schema2/alsonested http://x.y.z/t/inner.json#a 416 #/schema3 some://where.else/completely# 418 7.2.3. Canonical dereferencing and inline dereferencing 420 When resolving a URI against a resolution scope, an implementation 421 may choose two modes of operation: 423 canonical dereferencing The implementation dereferences all resolved 424 URIs. 426 inline dereferencing The implementation chooses to dereference URIs 427 within the schema. 429 Implementations MUST support canonical dereferencing, and MAY support 430 inline dereferencing. 432 For example, consider this schema: 434 { 435 "id": "http://my.site/myschema#", 436 "definitions": { 437 "schema1": { 438 "id": "schema1", 439 "type": "integer" 440 }, 441 "schema2", { 442 "type": "array", 443 "items": { "$ref": "schema1" } 444 } 445 } 446 } 448 When an implementation encounters the "schema1" reference, it 449 resolves it against the most immediate parent scope, leading to URI 450 "http://my.site/schema1#". The way to process this URI will differ 451 according to the chosen dereferencing mode: 453 if canonical dereferencing is used, the implementation will 454 dereference this URI, and fetch the content at this URI; 456 if inline dereferencing is used, the implementation will notice 457 that URI scope "http://my.site/schema1#" is already defined within 458 the schema, and choose to use the appropriate subschema. 460 7.2.4. Inline dereferencing and fragments 462 When using inline dereferencing, a resolution scope may lead to a URI 463 which has a non empty fragment part which is not a JSON Pointer, as 464 in this example: 466 { 467 "id": "http://some.site/schema#", 468 "not": { "$ref": "#inner" }, 469 "definitions": { 470 "schema1": { 471 "id": "#inner", 472 "type": "boolean" 473 } 474 } 475 } 477 An implementation choosing to support inline dereferencing SHOULD be 478 able to use this kind of reference. Implementations choosing to use 479 canonical dereferencing, however, are not required to support it. 481 7.3. Interoperability considerations 483 Inline dereferencing can produce canonical URIs which differ from the 484 canonical URI of the root schema. Schema authors SHOULD ensure that 485 implementations using canonical dereferencing obtain the same content 486 as implementations using inline dereferencing. 488 Extended JSON References using fragments which are not JSON Pointers 489 are not dereferenceable by implementations choosing not to support 490 inline dereferencing. This kind of reference is defined for 491 backwards compatibility, and SHOULD NOT be used in new schemas. 493 8. Recommended correlation mechanisms for use with the HTTP protocol 495 It is acknowledged by this specification that the majority of 496 interactive JSON Schema processing will be over HTTP. This section 497 therefore gives recommendations for materializing an instance/schema 498 correlation using mechanisms currently available for this protocol. 499 An instance is said to be described by one (or more) schema(s). 501 8.1. Correlation by means of the "Content-Type" header 503 It is RECOMMENDED that a MIME type parameter by the name of "profile" 504 be appended to the "Content-Type" header of the instance being 505 processed. If present, the value of this parameter MUST be a valid 506 URI, and this URI SHOULD resolve to a valid JSON Schema. The MIME 507 type MUST be "application/json", or any other subtype. 509 An example of such a header would be: 511 Content-Type: application/my-media-type+json; 512 profile=http://example.com/my-hyper-schema# 514 8.2. Correlation by means of the "Link" header 516 When using the "Link" header, the relation type used MUST be 517 "describedBy", as defined by RFC 5988, section 5.3 [RFC5988]. The 518 target URI of the "Link" header MUST be a valid JSON Schema. 520 An example of such a header would be: 522 Link: ; rel="describedBy" 524 9. IANA Considerations 526 The proposed MIME media type for JSON Schema is defined as follows: 528 type name: application; 530 subtype name: schema+json. 532 10. References 534 10.1. Normative References 536 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 537 Requirement Levels", BCP 14, RFC 2119, March 1997. 539 10.2. Informative References 541 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 542 Masinter, L., Leach, P., and T. Berners-Lee, 543 "Hypertext Transfer Protocol -- HTTP/1.1", 544 RFC 2616, June 1999. 546 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, 547 "Uniform Resource Identifier (URI): Generic 548 Syntax", STD 66, RFC 3986, January 2005. 550 [RFC4627] Crockford, D., "The application/json Media Type for 551 JavaScript Object Notation (JSON)", RFC 4627, 552 July 2006. 554 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 555 October 2010. 557 [json-reference] Bryan, P. and K. Zyp, "JSON Reference (work in 558 progress)", September 2012, . 561 [json-pointer] Bryan, P. and K. Zyp, "JSON Pointer (work in 562 progress)", September 2012, . 565 [json-schema-03] Court, G. and K. Zyp, "JSON Schema, draft 3", 566 September 2012, . 569 Appendix A. ChangeLog 571 draft-00 573 * Initial draft. 575 * Salvaged from draft v3. 577 * Mandate the use of JSON Reference, JSON Pointer. 579 * Define the role of "id". Define URI resolution scope. 581 * Add interoperability considerations. 583 Authors' Addresses 585 Francis Galiegue (editor) 587 EMail: fgaliegue@gmail.com 588 Kris Zyp (editor) 589 SitePen (USA) 590 530 Lytton Avenue 591 Palo Alto, CA 94301 592 USA 594 Phone: +1 650 968 8787 595 EMail: kris@sitepen.com 597 Gary Court 598 Calgary, AB 599 Canada 601 EMail: gary.court@gmail.com