idnits 2.17.1 draft-zyp-json-schema-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC4120, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 790 has weird spacing: '...ntifier res...' == Line 797 has weird spacing: '...rop.baz the s...' (Using the creation date from RFC4120, updated by this document, for RFC5378 checks: 2002-02-27) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 5, 2009) is 5256 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2119' is defined on line 921, but no explicit reference was found in the text == Unused Reference: 'RFC4287' is defined on line 926, but no explicit reference was found in the text == Unused Reference: 'RFC3339' is defined on line 930, but no explicit reference was found in the text == Unused Reference: 'RFC2045' is defined on line 934, but no explicit reference was found in the text == Unused Reference: 'RFC4627' is defined on line 942, but no explicit reference was found in the text == Unused Reference: 'RFC2616' is defined on line 947, but no explicit reference was found in the text == Unused Reference: 'I-D.hammer-discovery' is defined on line 958, but no explicit reference was found in the text == Unused Reference: 'I-D.gregorio-uritemplate' is defined on line 963, but no explicit reference was found in the text == Unused Reference: 'I-D.nottingham-http-link-header' is defined on line 967, but no explicit reference was found in the text -- Obsolete informational reference (is this intentional?): RFC 4627 (Obsoleted by RFC 7158, RFC 7159) -- 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 5226 (Obsoleted by RFC 8126) == Outdated reference: A later version (-06) exists of draft-hammer-discovery-03 == Outdated reference: A later version (-08) exists of draft-gregorio-uritemplate-03 Summary: 1 error (**), 0 flaws (~~), 14 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force K. Zyp, Ed. 3 Internet-Draft SitePen (USA) 4 Updates: 4120 (if approved) December 5, 2009 5 Intended status: Standards Track 6 Expires: June 8, 2010 8 A JSON Media Type for Describing the Structure and Meaning of JSON 9 Documents 10 draft-zyp-json-schema-00 12 Abstract 14 JSON (JavaScript Object Notation) Schema defines the media type 15 application/schema+json, a JSON based format for defining the 16 structure of JSON data. JSON Schema provides a contract for what 17 JSON data is required for a given application and how to interact 18 with it. JSON Schema is intended to define validation, 19 documentation, hyperlink navigation, and interaction control of JSON 20 data. 22 Status of This Memo 24 This Internet-Draft is submitted to IETF in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF), its areas, and its working groups. Note that 29 other groups may also distribute working documents as Internet- 30 Drafts. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 The list of current Internet-Drafts can be accessed at 38 http://www.ietf.org/ietf/1id-abstracts.txt. 40 The list of Internet-Draft Shadow Directories can be accessed at 41 http://www.ietf.org/shadow.html. 43 This Internet-Draft will expire on June 8, 2010. 45 Copyright Notice 47 Copyright (c) 2009 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 3.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 66 3.2. Design Considerations . . . . . . . . . . . . . . . . . . 6 67 4. Schema/Instance Association . . . . . . . . . . . . . . . . . 6 68 4.1. Self-Descriptive Schema . . . . . . . . . . . . . . . . . 7 69 5. Core Schema Definition . . . . . . . . . . . . . . . . . . . . 7 70 5.1. type . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 5.2. properties . . . . . . . . . . . . . . . . . . . . . . . . 8 72 5.3. items . . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 5.4. optional . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 5.5. additionalProperties . . . . . . . . . . . . . . . . . . . 9 75 5.6. requires . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 5.7. minimum . . . . . . . . . . . . . . . . . . . . . . . . . 10 77 5.8. maximum . . . . . . . . . . . . . . . . . . . . . . . . . 10 78 5.9. minimumCanEqual . . . . . . . . . . . . . . . . . . . . . 10 79 5.10. maximumCanEqual . . . . . . . . . . . . . . . . . . . . . 10 80 5.11. minItems . . . . . . . . . . . . . . . . . . . . . . . . . 10 81 5.12. maxItems . . . . . . . . . . . . . . . . . . . . . . . . . 10 82 5.13. pattern . . . . . . . . . . . . . . . . . . . . . . . . . 10 83 5.14. maxLength . . . . . . . . . . . . . . . . . . . . . . . . 10 84 5.15. minLength . . . . . . . . . . . . . . . . . . . . . . . . 10 85 5.16. enum . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 86 5.17. title . . . . . . . . . . . . . . . . . . . . . . . . . . 11 87 5.18. description . . . . . . . . . . . . . . . . . . . . . . . 11 88 5.19. format . . . . . . . . . . . . . . . . . . . . . . . . . . 11 89 5.20. contentEncoding . . . . . . . . . . . . . . . . . . . . . 12 90 5.21. default . . . . . . . . . . . . . . . . . . . . . . . . . 12 91 5.22. maxDecimal . . . . . . . . . . . . . . . . . . . . . . . . 12 92 5.23. disallow . . . . . . . . . . . . . . . . . . . . . . . . . 13 93 5.24. extends . . . . . . . . . . . . . . . . . . . . . . . . . 13 94 6. Hyper Schema . . . . . . . . . . . . . . . . . . . . . . . . . 13 95 6.1. links . . . . . . . . . . . . . . . . . . . . . . . . . . 13 96 6.1.1. Link Description Object . . . . . . . . . . . . . . . 13 97 6.2. fragmentResolution . . . . . . . . . . . . . . . . . . . . 17 98 6.2.1. dot-delimited fragment resolution . . . . . . . . . . 18 99 6.3. root . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 100 6.4. readonly . . . . . . . . . . . . . . . . . . . . . . . . . 19 101 6.5. pathStart . . . . . . . . . . . . . . . . . . . . . . . . 19 102 6.6. mediaType . . . . . . . . . . . . . . . . . . . . . . . . 19 103 6.7. alternate . . . . . . . . . . . . . . . . . . . . . . . . 20 104 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 105 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 106 8.1. Registry of Link Relations . . . . . . . . . . . . . . . . 21 107 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 108 9.1. Normative References . . . . . . . . . . . . . . . . . . . 21 109 9.2. Informative References . . . . . . . . . . . . . . . . . . 22 110 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 23 111 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 23 113 1. Introduction 115 JSON (JavaScript Object Notation) Schema is a JSON media type for 116 defining the structure of JSON data. JSON Schema provides a contract 117 for what JSON data is required for a given application and how to 118 interact with it. JSON Schema is intended to define validation, 119 documentation, hyperlink navigation, and interaction control of JSON 120 data. 122 2. Conventions 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 126 document are to be interpreted as described in RFC 2119. 128 3. Overview 130 JSON Schema defines the media type application/schema+json for 131 describing the structure of other JSON documents. JSON Schema is 132 JSON-based and includes facilities for describing the structure of 133 JSON documents in terms of allowable values, descriptions, and 134 interpreting relations with other resources. 136 JSON Schema format is organized into several separate definitions. 137 The first definition is the core schema specification. This 138 definition is primary concerned with describing a JSON structure and 139 specifying valid elements in the structure. The second definition is 140 the Hyper Schema specification which is intended define elements in a 141 structure that can be interpreted as hyperlinks. Hyper Schema builds 142 on JSON Schema to describe the hyperlink structure of other JSON 143 documents. This allows user agents to be able to successfully 144 navigate JSON documents based on their schemas. 146 Cumulatively JSON Schema acts as a meta-document that can be used to 147 define the required type and constraints on property values, as well 148 as define the meaning of the property values for the purpose of 149 describing a resource and determining hyperlinks within the 150 representation. 152 An example JSON Schema that describes products might look like: 154 { 155 "name":"Product", 156 "properties":{ 157 "id":{ 158 "type":"number", 159 "description":"Product identifier" 160 }, 161 "name":{ 162 "description":"Name of the product", 163 "type":"string" 164 }, 165 "price":{ 166 "type": "number", 167 "minimum":0 168 }, 169 "tags":{ 170 "optional":true, 171 "type":"array", 172 "items":{ 173 "type":"string" 174 } 175 } 176 }, 177 "links":[ 178 { 179 "rel":"full", 180 "href":"{id}" 181 }, 182 { 183 "rel":"comments", 184 "href":"comments/?id={id}" 185 } 186 ] 187 } 189 This schema defines the properties of the instance JSON documents and 190 their required properties (id, name, and price) as well as an 191 optional property (tags). This also defines the link relations of 192 the instance JSON documents. 194 3.1. Terminology 196 For this specification, a schema will be used to denote a JSON Schema 197 definition, and an instance refers to the JSON object or array that 198 the schema will be describing and validating 200 3.2. Design Considerations 202 The JSON Schema media type does not attempt to dictate the structure 203 of JSON representations that contain data, but rather provides a 204 separate format for flexibly communicating how a JSON representation 205 should be interpreted and validated, such that user agents can 206 properly understand acceptable structures and extrapolate hyperlink 207 information with the JSON document. This specification does not 208 define a protocol. The underlying protocol (such as HTTP) should 209 sufficiently define the semantics of the client-server interface, the 210 retrieval of resource representations linked to by JSON 211 representations, and modification of those resources. The goal of 212 this format is to sufficiently describe JSON structures such that one 213 can utilize existing information available in existing JSON 214 representations from a large variety of services that leverage a REST 215 architecture using existing protocols. 217 4. Schema/Instance Association 219 JSON Schema instances are correlated to their schema by the 220 "describedby" relation, where the schema is defined to be the target 221 of the relation. Instance representations may be of the application/ 222 json media type or any other subtype. Consequently, dictating how an 223 instance representation should specify the relation to the schema is 224 beyond the normative scope of this document (since this document 225 specifically defines the JSON Schema media type, and no other), but 226 it is recommended that instances specify their schema so that user 227 agents can interpret the instance representation and messages may 228 retain the self-descriptive characteristic, avoiding the need for 229 out-of-band information about instance data. Two approaches are 230 recommended for declaring the relation to the schema that describes 231 the meaning of a JSON instance's (or collection of instances) 232 structure. A MIME type parameter named "describedby" or a Link 233 header with a relation of "describedby" SHOULD be used: 235 Content-Type: application/json; 236 describedby=http://json.com/my-hyper-schema 238 or if the content is being transferred by a protocol (such as HTTP) 239 that provides headers, a Link header can be used: 241 Link: ; rel="describedby" 243 Instances MAY specify multiple schemas, to indicate all the schemas 244 that are applicable to the data. The instance data may have multiple 245 schemas that it is defined by (the instance data should be valid for 246 those schemas). Or if the document is a collection of instances, the 247 collection may contain instances from different schemas. When 248 collections contain heterogeneous instances, the pathStart attribute 249 MAY be specified in the schema to disambiguate which schema should be 250 applied for each item in the collection. 252 4.1. Self-Descriptive Schema 254 JSON Schemas are themselves instances for the schema schemas. A 255 self-describing JSON Schema for the core JSON Schema can be found at 256 http://json-schema.org/schema and the hyper schema self-description 257 can be found at: http://json-schema.org/hyper-schema. All schemas 258 used within a protocol with media type definitions SHOULD include a 259 MIME parameter that refers to the self-descriptive hyper schema or 260 another schema that extends this hyper schema: 262 Content-Type: application/json; 263 describedby=http://www.json-schema.org/hyper-schema 265 5. Core Schema Definition 267 A JSON Schema is a JSON Object that defines various attributes of the 268 instance and defines it's usage and valid values. A JSON Schema is a 269 JSON Object with schema attribute properties. The following is the 270 grammar of a JSON Schema: 272 And an example JSON Schema definition could look like: 274 {"description":"A person", 275 "type":"object", 277 "properties": 278 {"name": {"type":"string"}, 279 "age" : {"type":"integer", 280 "maximum":125}} 281 } 283 A JSON Schema object may have any of the following properties, called 284 schema attributes (all attributes are optional): 286 5.1. type 288 Union type definition - An array with two or more items which 289 indicates a union of type definitions. Each item in the array may 290 be a simple type definition or a schema. The instance value is 291 valid if it is of the same type as one the type definitions in the 292 array or if it is valid by one of the schemas in the array. For 293 example to indicate that a string or number is a valid: {"type": 294 ["string","number"]} 296 Simple type definition - A string indicating a primitive or simple 297 type. The following are acceptable strings: 299 string - Value must be a string. 301 number - Value must be a number, floating point numbers are 302 allowed. 304 integer - Value must be an integer, no floating point numbers 305 are allowed. This is a subset of the number type. 307 boolean - Value must be a boolean. 309 object - Value must be an object. 311 array - Value must be an array. 313 null - Value must be null. Note this is mainly for purpose of 314 being able use union types to define nullability. 316 any - Value may be of any type including null. If the property 317 is not defined or is not in this list, than any type of value 318 is acceptable. Other type values may be used for custom 319 purposes, but minimal validators of the specification 320 implementation can allow any instance value on unknown type 321 values. 323 5.2. properties 325 This should be an object type definition, which is an object with 326 property definitions that correspond to instance object properties. 327 When the instance value is an object, the property values of the 328 instance object must conform to the property definitions in this 329 object. In this object, each property definition's value should be a 330 schema, and the property's name should be the name of the instance 331 property that it defines. 333 5.3. items 335 This should be a schema or an array of schemas. When this is an 336 object/schema and the instance value is an array, all the items in 337 the array must conform to this schema. When this is an array of 338 schemas and the instance value is an array, each position in the 339 instance array must conform to the schema in the corresponding 340 position for this array. This called tuple typing. When tuple 341 typing is used, additional items are allowed, disallowed, or 342 constrained by the additionalProperties attribute using the same 343 rules as extra properties for objects.. 345 5.4. optional 347 This indicates that the instance property in the instance object is 348 optional. This is false by default. 350 5.5. additionalProperties 352 This provides a default property definition for all properties that 353 are not explicitly defined in an object type definition. The value 354 must be a schema. If false is provided, no additional properties are 355 allowed, and the schema can not be extended. The default value is an 356 empty schema which allows any value for additional properties. 358 5.6. requires 360 This indicates that if this property is present in the containing 361 instance object, the property given by requires attribute must also 362 be present in the containing instance object. The value of this 363 property may be a string, indicating the require property name. Or 364 the value may be a schema, in which case the containing instance must 365 be valid by the schema if the property is present. For example if a 366 object type definition is defined: 368 { 369 "state": 370 { 371 "optional":true 372 }, 373 "town": 374 { 375 "requires":"state", 376 "optional":true 377 } 378 } 380 An instance must include a state property if a town property is 381 included. If a town property is not included, the state property is 382 optional. 384 5.7. minimum 386 This indicates the minimum value for the instance property when the 387 type of the instance value is a number. 389 5.8. maximum 391 This indicates the minimum value for the instance property when the 392 type of the instance value is a number. 394 5.9. minimumCanEqual 396 If the minimum is defined, this indicates whether or not the instance 397 property value can equal the minimum. 399 5.10. maximumCanEqual 401 If the maximum is defined, this indicates whether or not the instance 402 property value can equal the maximum. 404 5.11. minItems 406 This indicates the minimum number of values in an array when an array 407 is the instance value. 409 5.12. maxItems 411 This indicates the maximum number of values in an array when an array 412 is the instance value. 414 5.13. pattern 416 When the instance value is a string, this provides a regular 417 expression that a instance string value should match in order to be 418 valid. Regular expressions should follow the regular expression 419 specification from ECMA 262/Perl 5 421 5.14. maxLength 423 When the instance value is a string, this indicates maximum length of 424 the string. 426 5.15. minLength 428 When the instance value is a string, this indicates minimum length of 429 the string. 431 5.16. enum 433 This provides an enumeration of possible values that are valid for 434 the instance property. This should be an array, and each item in the 435 array represents a possible value for the instance value. If "enum" 436 is included, the instance value must be one of the values in enum 437 array in order for the schema to be valid. 439 5.17. title 441 This provides a short description of the instance property. The 442 value must be a string. 444 5.18. description 446 This provides a full description of the of purpose the instance 447 property. The value must be a string. 449 5.19. format 451 This property indicates the type of data, content type, or 452 microformat to be expected in the instance property values. A format 453 attribute may be one of the values listed below, and if so, should 454 adhere to the semantics describing for the format. A format should 455 only be used give meaning to primitive types (string, integer, 456 number, or boolean). Validators are not required to validate that 457 the instance values conform to a format. The following formats are 458 defined: 460 Any valid MIME media type may be used as a format value, in which 461 case the instance property value must be a string, representing 462 the contents of the MIME file. 464 date-time - This should be a date in ISO 8601 format of YYYY-MM- 465 DDThh:mm:ssZ in UTC time. This is the recommended form of date/ 466 timestamp. 468 date - This should be a date in the format of YYYY-MM-DD. It is 469 recommended that you use the "date-time" format instead of "date" 470 unless you need to transfer only the date part. 472 time - This should be a time in the format of hh:mm:ss. It is 473 recommended that you use the "date-time" format instead of "time" 474 unless you need to transfer only the time part. 476 utc-millisec - This should be the difference, measured in 477 milliseconds, between the specified time and midnight, January 1, 478 1970 UTC. The value should be a number (integer or float). 480 regex - A regular expression. 482 color - This is a CSS color (like "#FF0000" or "red"). 484 style - This is a CSS style definition (like "color: red; 485 background-color:#FFF"). 487 phone - This should be a phone number (format may follow E.123). 489 uri - This value should be a URI.. 491 email - This should be an email address. 493 ip-address - This should be an ip version 4 address. 495 ipv6 - This should be an ip version 6 address. 497 street-address - This should be a street address. 499 locality - This should be a city or town. 501 region - This should be a region (a state in the US, province in 502 Canada, etc.) 504 postal-code - This should be a postal code (AKA zip code). 506 country - This should be the name of a country. 508 Additional custom formats may be defined with a URL to a 509 definition of the format. 511 5.20. contentEncoding 513 If the instance property value is a string, this indicates that the 514 string should be interpreted as binary data and decoded using the 515 encoding named by this schema property. RFC 2045, Sec 6.1 lists 516 possible values. 518 5.21. default 520 This indicates the default for the instance property. 522 5.22. maxDecimal 524 This indicates the maximum number of decimal places in a floating 525 point number. By default there is no maximum. 527 5.23. disallow 529 This attribute may take the same values as the "type" attribute, 530 however if the instance matches the type or if this value is an array 531 and the instance matches any type or schema in the array, than this 532 instance is not valid. 534 5.24. extends 536 The value of this property should be another schema which will 537 provide a base schema which the current schema will inherit from. 538 The inheritance rules are such that any instance that is valid 539 according to the current schema must be valid according to the 540 referenced schema. This may also be an array, in which case, the 541 instance must be valid for all the schemas in the array. 543 6. Hyper Schema 545 This section defines hypermedia definitions of JSON schema. The 546 following attributes are specified in addition to those attributes 547 that already provided by JSON schema with the specific purpose of 548 informing user agents of relations between resources based on JSON 549 data. Just as with JSON schema attributes, all the attributes in 550 hyper-schema are optional. Therefore an empty object is a valid 551 (non-informative) schema, and essentially describes plain JSON (no 552 constraints on the structures). Addition of attributes provides 553 additive information for user agents. 555 6.1. links 557 The value of the links property should be an array, where each item 558 in the array is a link description object which describes the link 559 relations of the instances. 561 6.1.1. Link Description Object 563 A link description object is used to describe the link relations of 564 instances of a schema. 566 6.1.1.1. href 568 The value of the "href" link description property indicates the 569 target URI of the related resource. The value of the instance 570 property should be resolved as a URI-Reference per [RFC3986] and may 571 be a relative URI. The base URI to be used for relative resolution 572 should be the URI used to retrieve the instance object (not the 573 schema). Also, the URI may be parametrized by the property values of 574 the instance object. 576 Instance property values should be substituted into the URIs where 577 matching braces ('{', '}') are found surrounding zero or more 578 characters, creating an expanded URI. Instance property value 579 substitutions are resolved by using the text between the braces to 580 denote the property name from the instance to get the value to 581 substitute. For example, if an href value is defined: 583 http://somesite.com/{id} 585 Then it would be resolved by replace the value of the "id" property 586 value from the instance object. If the value of the "id" property 587 was "45", the expanded URI would be: 589 http://somesite.com/45 591 If matching braces are found with the string "-this" (no quotes) 592 between the braces, than the actual instance value should be used to 593 replace the braces, rather than a property value. This should only 594 be used in situations where the instance is a scalar (string, 595 boolean, or number), and not for objects or arrays. 597 6.1.1.2. rel 599 The value of the "rel" property indicates the name of the relation to 600 the target resource. The relation to the target should be 601 interpreted as specifically from the instance object that the schema 602 (or sub-schema) applies to, not just the top level resource that 603 contains the object within its hierarchy. If a resource JSON 604 representation contains a sub object with a property interpreted as a 605 link, that sub-object holds the relation with the target. A relation 606 to target from the top level resource must be indicated with the 607 schema describing the top level JSON representation. 609 Relationship definitions SHOULD NOT be media type dependent, and 610 users are encouraged to utilize existing accepted relation 611 definitions, including those in existing relation registries (see 612 &rfc4287). However, we define these relation here for clarity of 613 normative interpretation within the context of JSON hyper schema 614 defined relations: 616 self - If the relation value is "self", when this property is 617 encountered in the instance object, the object represents a 618 resource and the instance object is treated as a full 619 representation of the target resource identified by the specified 620 URI. 622 full - This indicates that the target of the link is the full 623 representation for the instance object. The object that contains 624 this link may not be the full representation. 626 describedby - This indicates the target of the link is the schema 627 for the instance object. This may be used to specifically denote 628 the schemas of objects within a JSON object hierarchy, 629 facilitating polymorphic type data structures. 631 The following relations are applicable for schemas (the schema as 632 the "from" resource in the relation). 634 instances - This indicates the target resource that represents 635 collection of instances of a schema. 637 create - This indicates a target to use for creating new instances 638 of a schema. This link definition SHOULD be a submission link 639 with a non-safe method (like POST). 641 For example, if a schema is defined: 643 { 644 "links": [ 645 { 646 "rel": "self" 647 "href": "{id}" 648 }, 649 { 650 "rel": "up" 651 "href": "{upId}" 652 }, 653 { 654 "rel": "children" 655 "href": "?upId={id}" 656 } 657 ] 658 } 660 And if a collection of instance resource's JSON representation was 661 retrieved: 663 GET /Resource/ 665 [ 666 { 667 "id": "thing", 668 "upId": "parent" 669 }, 670 { 671 "id": "thing2", 672 "upId": "parent" 673 } 674 ] 676 This would indicate that for the first item in the collection, it's 677 own (self) URI would resolve to "/Resource/thing" and the first 678 item's "up" relation should be resolved to the resource at 679 "/Resource/parent". The "children" collection would be located at 680 "/Resource/?upId=thing". 682 6.1.1.3. Submission Link Properties 684 The following properties also apply to link definition objects, and 685 provide functionality analogous to HTML forms, in providing a means 686 for submitting extra (often user supplied) information to send to a 687 server. 689 6.1.1.3.1. method 691 This indicates which method should be used to access the target 692 resource. In an HTTP environment, this would be "GET" or "POST" 693 (other HTTP methods such as "PUT" and "DELETE" have semantics that 694 are clearly implied by accessed resources, and do not need to be 695 defined here). This defaults to "GET". 697 6.1.1.3.2. enctype 699 If present, this property indicates a query media type format that 700 the server supports for querying or posting to the collection of 701 instances at the target resource. The query can be suffixed to the 702 target URI to query the collection with property-based constraints on 703 the resources that SHOULD be returned from the server or used to post 704 data to the resource (depending on the method). For example, with 705 the following schema: 707 { 708 "links":[ 709 { 710 "enctype": "application/x-www-form-urlencoded", 711 "method": "GET", 712 "href": "/Product/", 713 "properties":{ 714 "name":{"description":"name of the product"} 715 } 716 } 717 ] 718 } 720 This indicates that the client can query the server for instances 721 that have a specific name: 723 /Product/?name=Slinky 725 If no enctype or method is specified, only the single URI specified 726 by the href property is defined. If the method is POST, application/ 727 json is the default media type. 729 6.1.1.3.3. properties 731 This is inherited from the base JSON schema definition, and can 732 follow the same structure, but its meaning should be used to define 733 the acceptable property names and values for the action (whether it 734 be for the GET query or POST body). If properties are omitted, and 735 this form is the child of a schema, the properties from the parent 736 schema should be used as the basis for the form action. 738 6.2. fragmentResolution 740 This property indicates the fragment resolution protocol to use for 741 resolving fragment identifiers in URIs within the instance 742 representations. This applies to the instance object URIs and all 743 children of the instance object's URIs. The default fragment 744 resolution protocol is "dot-delimited", which is defined below. 745 Other fragment resolution protocols may be used, but are not defined 746 in this document. 748 The fragment identifier is based on RFC 2396 Sec 5, and defines the 749 mechanism for resolving references to entities within a document. 751 6.2.1. dot-delimited fragment resolution 753 With the dot-delimited fragment resolution protocol, the fragment 754 identifier is interpreted as a series of property reference tokens 755 that are delimited by the "." character (\x2E). Each property 756 reference token is a series of any legal URI component characters 757 except the "." character. Each property reference token should be 758 interpreted, starting from the beginning of the fragment identifier, 759 as a path reference in the target JSON structure. The final target 760 value of the fragment can be determined by starting with the root of 761 the JSON structure from the representation of the resource identified 762 by the pre-fragment URI. If the target is a JSON object, than the 763 new target is the value of the property with the name identified by 764 the next property reference token in the fragment. If the target is 765 a JSON array, than the target is determined by finding the item in 766 array the array with the index defined by the next property reference 767 token (which MUST be a number). The target is successively updated 768 for each property reference token, until the entire fragment has been 769 traversed. 771 Property names SHOULD be URI-encoded. In particular, any "." in a 772 property name MUST be encoded to avoid being interpreted as a 773 property delimiter. 775 For example, for the following JSON representation: 777 { 778 "foo":{ 779 "anArray":[ 780 {"prop":44} 781 ], 782 "another prop":{ 783 "baz":"A string" 784 } 785 } 786 } 788 The following fragment identifiers would be resolved: 790 fragment identifier resolution 791 ------------------- ---------- 792 # self, the root of the resource itself 793 #foo the object referred to by the foo property 794 #foo.another prop the object referred to by the "another prop" 795 property of the object referred to by the 796 "foo" property 797 #foo.another prop.baz the string referred to by the value of "baz" 798 property of the "another prop" property of 799 the object referred to by the "foo" property 800 #foo.anArray.0 the first object in the "anArray" array 802 6.3. root 804 This attribute indicates that the value of the instance property 805 value SHOULD be treated as the root or the body of the representation 806 for the purposes of user agent interaction and fragment resolution 807 (all other properties of the instance objects are can be regarded as 808 meta-data descriptions for the data). 810 6.4. readonly 812 This indicates that the instance property should not be changed. 813 Attempts by a user agent to modify the value of this property are 814 expected to be rejected by a server. 816 6.5. pathStart 818 This property value is a URI-Reference that indicates the URI that 819 all the URIs for the instances of the schema should start with. When 820 multiple schemas have been referenced for an instance, the user agent 821 can determine if this schema is applicable for a particular instance 822 by determining if URI of the instance begins with the pathStart's 823 referenced URI. pathStart MUST be resolved as per [RFC3986] section 824 5. If the URI of the instance does not start with URI indicated by 825 pathStart, or if another schema specifies a starting URI that is 826 longer and also matches the instance, this schema should not be 827 applied to the instance. Any schema that does not have a pathStart 828 attribute should be considered applicable to all the instances for 829 which it is referenced. 831 6.6. mediaType 833 This indicates the media type of the instance representations that 834 this schema is defining. 836 6.7. alternate 838 This is an array of JSON schema definitions that define any other 839 schemas for alternate JSON-based representations of the instance 840 resources. 842 7. Security Considerations 844 This specification is a sub-type of the JSON format, and consequently 845 the security considerations are generally the same as RFC 4627. 846 However, an additional issue is that when link relation of "self" is 847 used to denote a full representation of an object, the user agent 848 SHOULD NOT consider the representation to be the authoritative 849 representation of the resource denoted by the target URI if the 850 target URI is not equivalent to or a sub-path of the the URI used to 851 request the resource representation which contains the target URI 852 with the "self" link. For example, if a hyper schema was defined: 854 { 855 "links":[ 856 { 857 "rel":"self", 858 "href":"{id}" 859 } 860 ] 861 } 863 And a resource was requested from somesite.com: 865 GET /foo/ 867 With a response of: 869 Content-Type: application/json; describedby=/schema-for-this-data 870 [ 871 {"id":"bar", "name":"This representation can be safely treated \ 872 as authoritative "}, 873 {"id":"/baz", "name":"This representation should not be treated as \ 874 authoritative the user agent should make request the resource\ 875 from "/baz" to ensure it has the authoritative representation"}, 876 {"id":"http://othersite.com/something", "name":"This representation\ 877 should also not be treated as authoritative and the target\ 878 resource representation should be retrieved for the\ 879 authoritative representation"} 880 ] 881 8. IANA Considerations 883 The proposed MIME media type for JSON Schema is application/ 884 schema+json 886 Type name: application 888 Subtype name: schema+json 890 Required parameters: describedby 892 The value of the describedby parameter should be a URI (relative or 893 absolute) that refers to the schema used to define the structure of 894 this structure (the meta-schema). Normally the value would be 895 http://json-schema.org/hyper-schema, but it is allowable to use other 896 schemas that extend the hyper schema's meta- schema. 898 Optional parameters: pretty 900 The value of the pretty parameter may be true or false to indicate if 901 additional whitespace has been included to make the JSON 902 representation easier to read. 904 8.1. Registry of Link Relations 906 This registry is maintained by IANA per RFC 4287 and this 907 specification adds three values: "full", "create", "instances". New 908 assignments are subject to IESG Approval, as outlined in [RFC5226]. 909 Requests should be made by email to IANA, which will then forward the 910 request to the IESG, requesting approval. 912 9. References 914 9.1. Normative References 916 [RFC3986] Berners-Lee, T., Fielding, R., and 917 L. Masinter, "Uniform Resource 918 Identifier (URI): Generic Syntax", 919 STD 66, RFC 3986, January 2005. 921 [RFC2119] Bradner, S., "Key words for use in 922 RFCs to Indicate Requirement 923 Levels", BCP 14, RFC 2119, 924 March 1997. 926 [RFC4287] Nottingham, M., Ed. and R. Sayre, 927 Ed., "The Atom Syndication 928 Format", RFC 4287, December 2005. 930 [RFC3339] Klyne, G., Ed. and C. Newman, 931 "Date and Time on the Internet: 932 Timestamps", RFC 3339, July 2002. 934 [RFC2045] Freed, N. and N. Borenstein, 935 "Multipurpose Internet Mail 936 Extensions (MIME) Part One: Format 937 of Internet Message Bodies", 938 RFC 2045, November 1996. 940 9.2. Informative References 942 [RFC4627] Crockford, D., "The application/ 943 json Media Type for JavaScript 944 Object Notation (JSON)", RFC 4627, 945 July 2006. 947 [RFC2616] Fielding, R., Gettys, J., Mogul, 948 J., Frystyk, H., Masinter, L., 949 Leach, P., and T. Berners-Lee, 950 "Hypertext Transfer Protocol -- 951 HTTP/1.1", RFC 2616, June 1999. 953 [RFC5226] Narten, T. and H. Alvestrand, 954 "Guidelines for Writing an IANA 955 Considerations Section in RFCs", 956 BCP 26, RFC 5226, May 2008. 958 [I-D.hammer-discovery] Hammer-Lahav, E., "Link-based 959 Resource Descriptor Discovery", 960 draft-hammer-discovery-03 (work in 961 progress), March 2009. 963 [I-D.gregorio-uritemplate] Gregorio, J., "URI Template", 964 draft-gregorio-uritemplate-03 965 (work in progress), April 2008. 967 [I-D.nottingham-http-link-header] Nottingham, M., "Web Linking", dra 968 ft-nottingham-http-link-header-06 969 (work in progress), July 2009. 971 [W3C.REC-html401-19991224] Hors, A., Jacobs, I., and D. 972 Raggett, "HTML 4.01 973 Specification", World Wide Web 974 Consortium Recommendation REC- 975 html401-19991224, December 1999, < 976 http://www.w3.org/TR/1999/ 977 REC-html401-19991224>. 979 Appendix A. Change Log 981 Appendix B. Open Issues 983 Should we give a preference to MIME headers over Link headers (or 984 only use one)? 986 Should we use "profile" as the media type parameter instead? 988 Should "root" be a MIME parameter instead of a schema attribute? 990 Should "format" be renamed to "mediaType" or "contentType" to reflect 991 the usage MIME media types that are allowed. 993 I still do not like how dates are handled. 995 Author's Address 997 Kris Zyp (editor) 998 SitePen (USA) 999 530 Lytton Avenue 1000 Palo Alto, CA 94301 1001 USA 1003 Phone: +1 650 968 8787 1004 EMail: kris@sitepen.com