idnits 2.17.1 draft-zyp-json-schema-01.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 789 has weird spacing: '...ntifier res...' == Line 796 has weird spacing: '...rop.baz the s...' -- 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: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC2119' is defined on line 920, but no explicit reference was found in the text == Unused Reference: 'RFC4287' is defined on line 925, but no explicit reference was found in the text == Unused Reference: 'RFC3339' is defined on line 929, but no explicit reference was found in the text == Unused Reference: 'RFC2045' is defined on line 933, but no explicit reference was found in the text == Unused Reference: 'RFC4627' is defined on line 941, but no explicit reference was found in the text == Unused Reference: 'RFC2616' is defined on line 946, but no explicit reference was found in the text == Unused Reference: 'I-D.hammer-discovery' is defined on line 957, but no explicit reference was found in the text == Unused Reference: 'I-D.gregorio-uritemplate' is defined on line 962, but no explicit reference was found in the text == Unused Reference: 'I-D.nottingham-http-link-header' is defined on line 966, 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 (==), 5 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 Intended status: Informational December 5, 2009 5 Expires: June 8, 2010 7 A JSON Media Type for Describing the Structure and Meaning of JSON 8 Documents 9 draft-zyp-json-schema-01 11 Abstract 13 JSON (JavaScript Object Notation) Schema defines the media type 14 application/schema+json, a JSON based format for defining the 15 structure of JSON data. JSON Schema provides a contract for what 16 JSON data is required for a given application and how to interact 17 with it. JSON Schema is intended to define validation, 18 documentation, hyperlink navigation, and interaction control of JSON 19 data. 21 Status of This Memo 23 This Internet-Draft is submitted to IETF 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), its areas, and its working groups. Note that 28 other groups may also distribute working documents as Internet- 29 Drafts. 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 The list of current Internet-Drafts can be accessed at 37 http://www.ietf.org/ietf/1id-abstracts.txt. 39 The list of Internet-Draft Shadow Directories can be accessed at 40 http://www.ietf.org/shadow.html. 42 This Internet-Draft will expire on June 8, 2010. 44 Copyright Notice 46 Copyright (c) 2009 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 62 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 65 3.2. Design Considerations . . . . . . . . . . . . . . . . . . 6 66 4. Schema/Instance Association . . . . . . . . . . . . . . . . . 6 67 4.1. Self-Descriptive Schema . . . . . . . . . . . . . . . . . 7 68 5. Core Schema Definition . . . . . . . . . . . . . . . . . . . . 7 69 5.1. type . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 5.2. properties . . . . . . . . . . . . . . . . . . . . . . . . 8 71 5.3. items . . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 5.4. optional . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 5.5. additionalProperties . . . . . . . . . . . . . . . . . . . 9 74 5.6. requires . . . . . . . . . . . . . . . . . . . . . . . . . 9 75 5.7. minimum . . . . . . . . . . . . . . . . . . . . . . . . . 10 76 5.8. maximum . . . . . . . . . . . . . . . . . . . . . . . . . 10 77 5.9. minimumCanEqual . . . . . . . . . . . . . . . . . . . . . 10 78 5.10. maximumCanEqual . . . . . . . . . . . . . . . . . . . . . 10 79 5.11. minItems . . . . . . . . . . . . . . . . . . . . . . . . . 10 80 5.12. maxItems . . . . . . . . . . . . . . . . . . . . . . . . . 10 81 5.13. pattern . . . . . . . . . . . . . . . . . . . . . . . . . 10 82 5.14. maxLength . . . . . . . . . . . . . . . . . . . . . . . . 10 83 5.15. minLength . . . . . . . . . . . . . . . . . . . . . . . . 10 84 5.16. enum . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 85 5.17. title . . . . . . . . . . . . . . . . . . . . . . . . . . 11 86 5.18. description . . . . . . . . . . . . . . . . . . . . . . . 11 87 5.19. format . . . . . . . . . . . . . . . . . . . . . . . . . . 11 88 5.20. contentEncoding . . . . . . . . . . . . . . . . . . . . . 12 89 5.21. default . . . . . . . . . . . . . . . . . . . . . . . . . 12 90 5.22. maxDecimal . . . . . . . . . . . . . . . . . . . . . . . . 12 91 5.23. disallow . . . . . . . . . . . . . . . . . . . . . . . . . 13 92 5.24. extends . . . . . . . . . . . . . . . . . . . . . . . . . 13 93 6. Hyper Schema . . . . . . . . . . . . . . . . . . . . . . . . . 13 94 6.1. links . . . . . . . . . . . . . . . . . . . . . . . . . . 13 95 6.1.1. Link Description Object . . . . . . . . . . . . . . . 13 96 6.2. fragmentResolution . . . . . . . . . . . . . . . . . . . . 17 97 6.2.1. dot-delimited fragment resolution . . . . . . . . . . 18 98 6.3. root . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 99 6.4. readonly . . . . . . . . . . . . . . . . . . . . . . . . . 19 100 6.5. pathStart . . . . . . . . . . . . . . . . . . . . . . . . 19 101 6.6. mediaType . . . . . . . . . . . . . . . . . . . . . . . . 19 102 6.7. alternate . . . . . . . . . . . . . . . . . . . . . . . . 20 103 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 104 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 105 8.1. Registry of Link Relations . . . . . . . . . . . . . . . . 21 106 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 107 9.1. Normative References . . . . . . . . . . . . . . . . . . . 21 108 9.2. Informative References . . . . . . . . . . . . . . . . . . 22 109 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 23 110 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 23 112 1. Introduction 114 JSON (JavaScript Object Notation) Schema is a JSON media type for 115 defining the structure of JSON data. JSON Schema provides a contract 116 for what JSON data is required for a given application and how to 117 interact with it. JSON Schema is intended to define validation, 118 documentation, hyperlink navigation, and interaction control of JSON 119 data. 121 2. Conventions 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 125 document are to be interpreted as described in RFC 2119. 127 3. Overview 129 JSON Schema defines the media type application/schema+json for 130 describing the structure of other JSON documents. JSON Schema is 131 JSON-based and includes facilities for describing the structure of 132 JSON documents in terms of allowable values, descriptions, and 133 interpreting relations with other resources. 135 JSON Schema format is organized into several separate definitions. 136 The first definition is the core schema specification. This 137 definition is primary concerned with describing a JSON structure and 138 specifying valid elements in the structure. The second definition is 139 the Hyper Schema specification which is intended define elements in a 140 structure that can be interpreted as hyperlinks. Hyper Schema builds 141 on JSON Schema to describe the hyperlink structure of other JSON 142 documents. This allows user agents to be able to successfully 143 navigate JSON documents based on their schemas. 145 Cumulatively JSON Schema acts as a meta-document that can be used to 146 define the required type and constraints on property values, as well 147 as define the meaning of the property values for the purpose of 148 describing a resource and determining hyperlinks within the 149 representation. 151 An example JSON Schema that describes products might look like: 153 { 154 "name":"Product", 155 "properties":{ 156 "id":{ 157 "type":"number", 158 "description":"Product identifier" 159 }, 160 "name":{ 161 "description":"Name of the product", 162 "type":"string" 163 }, 164 "price":{ 165 "type": "number", 166 "minimum":0 167 }, 168 "tags":{ 169 "optional":true, 170 "type":"array", 171 "items":{ 172 "type":"string" 173 } 174 } 175 }, 176 "links":[ 177 { 178 "rel":"full", 179 "href":"{id}" 180 }, 181 { 182 "rel":"comments", 183 "href":"comments/?id={id}" 184 } 185 ] 186 } 188 This schema defines the properties of the instance JSON documents and 189 their required properties (id, name, and price) as well as an 190 optional property (tags). This also defines the link relations of 191 the instance JSON documents. 193 3.1. Terminology 195 For this specification, a schema will be used to denote a JSON Schema 196 definition, and an instance refers to the JSON object or array that 197 the schema will be describing and validating 199 3.2. Design Considerations 201 The JSON Schema media type does not attempt to dictate the structure 202 of JSON representations that contain data, but rather provides a 203 separate format for flexibly communicating how a JSON representation 204 should be interpreted and validated, such that user agents can 205 properly understand acceptable structures and extrapolate hyperlink 206 information with the JSON document. This specification does not 207 define a protocol. The underlying protocol (such as HTTP) should 208 sufficiently define the semantics of the client-server interface, the 209 retrieval of resource representations linked to by JSON 210 representations, and modification of those resources. The goal of 211 this format is to sufficiently describe JSON structures such that one 212 can utilize existing information available in existing JSON 213 representations from a large variety of services that leverage a REST 214 architecture using existing protocols. 216 4. Schema/Instance Association 218 JSON Schema instances are correlated to their schema by the 219 "describedby" relation, where the schema is defined to be the target 220 of the relation. Instance representations may be of the application/ 221 json media type or any other subtype. Consequently, dictating how an 222 instance representation should specify the relation to the schema is 223 beyond the normative scope of this document (since this document 224 specifically defines the JSON Schema media type, and no other), but 225 it is recommended that instances specify their schema so that user 226 agents can interpret the instance representation and messages may 227 retain the self-descriptive characteristic, avoiding the need for 228 out-of-band information about instance data. Two approaches are 229 recommended for declaring the relation to the schema that describes 230 the meaning of a JSON instance's (or collection of instances) 231 structure. A MIME type parameter named "describedby" or a Link 232 header with a relation of "describedby" SHOULD be used: 234 Content-Type: application/json; 235 describedby=http://json.com/my-hyper-schema 237 or if the content is being transferred by a protocol (such as HTTP) 238 that provides headers, a Link header can be used: 240 Link: ; rel="describedby" 242 Instances MAY specify multiple schemas, to indicate all the schemas 243 that are applicable to the data. The instance data may have multiple 244 schemas that it is defined by (the instance data should be valid for 245 those schemas). Or if the document is a collection of instances, the 246 collection may contain instances from different schemas. When 247 collections contain heterogeneous instances, the pathStart attribute 248 MAY be specified in the schema to disambiguate which schema should be 249 applied for each item in the collection. 251 4.1. Self-Descriptive Schema 253 JSON Schemas are themselves instances for the schema schemas. A 254 self-describing JSON Schema for the core JSON Schema can be found at 255 http://json-schema.org/schema and the hyper schema self-description 256 can be found at: http://json-schema.org/hyper-schema. All schemas 257 used within a protocol with media type definitions SHOULD include a 258 MIME parameter that refers to the self-descriptive hyper schema or 259 another schema that extends this hyper schema: 261 Content-Type: application/json; 262 describedby=http://www.json-schema.org/hyper-schema 264 5. Core Schema Definition 266 A JSON Schema is a JSON Object that defines various attributes of the 267 instance and defines it's usage and valid values. A JSON Schema is a 268 JSON Object with schema attribute properties. The following is the 269 grammar of a JSON Schema: 271 And an example JSON Schema definition could look like: 273 {"description":"A person", 274 "type":"object", 276 "properties": 277 {"name": {"type":"string"}, 278 "age" : {"type":"integer", 279 "maximum":125}} 280 } 282 A JSON Schema object may have any of the following properties, called 283 schema attributes (all attributes are optional): 285 5.1. type 287 Union type definition - An array with two or more items which 288 indicates a union of type definitions. Each item in the array may 289 be a simple type definition or a schema. The instance value is 290 valid if it is of the same type as one the type definitions in the 291 array or if it is valid by one of the schemas in the array. For 292 example to indicate that a string or number is a valid: {"type": 293 ["string","number"]} 295 Simple type definition - A string indicating a primitive or simple 296 type. The following are acceptable strings: 298 string - Value must be a string. 300 number - Value must be a number, floating point numbers are 301 allowed. 303 integer - Value must be an integer, no floating point numbers 304 are allowed. This is a subset of the number type. 306 boolean - Value must be a boolean. 308 object - Value must be an object. 310 array - Value must be an array. 312 null - Value must be null. Note this is mainly for purpose of 313 being able use union types to define nullability. 315 any - Value may be of any type including null. If the property 316 is not defined or is not in this list, than any type of value 317 is acceptable. Other type values may be used for custom 318 purposes, but minimal validators of the specification 319 implementation can allow any instance value on unknown type 320 values. 322 5.2. properties 324 This should be an object type definition, which is an object with 325 property definitions that correspond to instance object properties. 326 When the instance value is an object, the property values of the 327 instance object must conform to the property definitions in this 328 object. In this object, each property definition's value should be a 329 schema, and the property's name should be the name of the instance 330 property that it defines. 332 5.3. items 334 This should be a schema or an array of schemas. When this is an 335 object/schema and the instance value is an array, all the items in 336 the array must conform to this schema. When this is an array of 337 schemas and the instance value is an array, each position in the 338 instance array must conform to the schema in the corresponding 339 position for this array. This called tuple typing. When tuple 340 typing is used, additional items are allowed, disallowed, or 341 constrained by the additionalProperties attribute using the same 342 rules as extra properties for objects.. 344 5.4. optional 346 This indicates that the instance property in the instance object is 347 optional. This is false by default. 349 5.5. additionalProperties 351 This provides a default property definition for all properties that 352 are not explicitly defined in an object type definition. The value 353 must be a schema. If false is provided, no additional properties are 354 allowed, and the schema can not be extended. The default value is an 355 empty schema which allows any value for additional properties. 357 5.6. requires 359 This indicates that if this property is present in the containing 360 instance object, the property given by requires attribute must also 361 be present in the containing instance object. The value of this 362 property may be a string, indicating the require property name. Or 363 the value may be a schema, in which case the containing instance must 364 be valid by the schema if the property is present. For example if a 365 object type definition is defined: 367 { 368 "state": 369 { 370 "optional":true 371 }, 372 "town": 373 { 374 "requires":"state", 375 "optional":true 376 } 377 } 379 An instance must include a state property if a town property is 380 included. If a town property is not included, the state property is 381 optional. 383 5.7. minimum 385 This indicates the minimum value for the instance property when the 386 type of the instance value is a number. 388 5.8. maximum 390 This indicates the minimum value for the instance property when the 391 type of the instance value is a number. 393 5.9. minimumCanEqual 395 If the minimum is defined, this indicates whether or not the instance 396 property value can equal the minimum. 398 5.10. maximumCanEqual 400 If the maximum is defined, this indicates whether or not the instance 401 property value can equal the maximum. 403 5.11. minItems 405 This indicates the minimum number of values in an array when an array 406 is the instance value. 408 5.12. maxItems 410 This indicates the maximum number of values in an array when an array 411 is the instance value. 413 5.13. pattern 415 When the instance value is a string, this provides a regular 416 expression that a instance string value should match in order to be 417 valid. Regular expressions should follow the regular expression 418 specification from ECMA 262/Perl 5 420 5.14. maxLength 422 When the instance value is a string, this indicates maximum length of 423 the string. 425 5.15. minLength 427 When the instance value is a string, this indicates minimum length of 428 the string. 430 5.16. enum 432 This provides an enumeration of possible values that are valid for 433 the instance property. This should be an array, and each item in the 434 array represents a possible value for the instance value. If "enum" 435 is included, the instance value must be one of the values in enum 436 array in order for the schema to be valid. 438 5.17. title 440 This provides a short description of the instance property. The 441 value must be a string. 443 5.18. description 445 This provides a full description of the of purpose the instance 446 property. The value must be a string. 448 5.19. format 450 This property indicates the type of data, content type, or 451 microformat to be expected in the instance property values. A format 452 attribute may be one of the values listed below, and if so, should 453 adhere to the semantics describing for the format. A format should 454 only be used give meaning to primitive types (string, integer, 455 number, or boolean). Validators are not required to validate that 456 the instance values conform to a format. The following formats are 457 defined: 459 Any valid MIME media type may be used as a format value, in which 460 case the instance property value must be a string, representing 461 the contents of the MIME file. 463 date-time - This should be a date in ISO 8601 format of YYYY-MM- 464 DDThh:mm:ssZ in UTC time. This is the recommended form of date/ 465 timestamp. 467 date - This should be a date in the format of YYYY-MM-DD. It is 468 recommended that you use the "date-time" format instead of "date" 469 unless you need to transfer only the date part. 471 time - This should be a time in the format of hh:mm:ss. It is 472 recommended that you use the "date-time" format instead of "time" 473 unless you need to transfer only the time part. 475 utc-millisec - This should be the difference, measured in 476 milliseconds, between the specified time and midnight, January 1, 477 1970 UTC. The value should be a number (integer or float). 479 regex - A regular expression. 481 color - This is a CSS color (like "#FF0000" or "red"). 483 style - This is a CSS style definition (like "color: red; 484 background-color:#FFF"). 486 phone - This should be a phone number (format may follow E.123). 488 uri - This value should be a URI.. 490 email - This should be an email address. 492 ip-address - This should be an ip version 4 address. 494 ipv6 - This should be an ip version 6 address. 496 street-address - This should be a street address. 498 locality - This should be a city or town. 500 region - This should be a region (a state in the US, province in 501 Canada, etc.) 503 postal-code - This should be a postal code (AKA zip code). 505 country - This should be the name of a country. 507 Additional custom formats may be defined with a URL to a 508 definition of the format. 510 5.20. contentEncoding 512 If the instance property value is a string, this indicates that the 513 string should be interpreted as binary data and decoded using the 514 encoding named by this schema property. RFC 2045, Sec 6.1 lists 515 possible values. 517 5.21. default 519 This indicates the default for the instance property. 521 5.22. maxDecimal 523 This indicates the maximum number of decimal places in a floating 524 point number. By default there is no maximum. 526 5.23. disallow 528 This attribute may take the same values as the "type" attribute, 529 however if the instance matches the type or if this value is an array 530 and the instance matches any type or schema in the array, than this 531 instance is not valid. 533 5.24. extends 535 The value of this property should be another schema which will 536 provide a base schema which the current schema will inherit from. 537 The inheritance rules are such that any instance that is valid 538 according to the current schema must be valid according to the 539 referenced schema. This may also be an array, in which case, the 540 instance must be valid for all the schemas in the array. 542 6. Hyper Schema 544 This section defines hypermedia definitions of JSON schema. The 545 following attributes are specified in addition to those attributes 546 that already provided by JSON schema with the specific purpose of 547 informing user agents of relations between resources based on JSON 548 data. Just as with JSON schema attributes, all the attributes in 549 hyper-schema are optional. Therefore an empty object is a valid 550 (non-informative) schema, and essentially describes plain JSON (no 551 constraints on the structures). Addition of attributes provides 552 additive information for user agents. 554 6.1. links 556 The value of the links property should be an array, where each item 557 in the array is a link description object which describes the link 558 relations of the instances. 560 6.1.1. Link Description Object 562 A link description object is used to describe the link relations of 563 instances of a schema. 565 6.1.1.1. href 567 The value of the "href" link description property indicates the 568 target URI of the related resource. The value of the instance 569 property should be resolved as a URI-Reference per [RFC3986] and may 570 be a relative URI. The base URI to be used for relative resolution 571 should be the URI used to retrieve the instance object (not the 572 schema). Also, the URI may be parametrized by the property values of 573 the instance object. 575 Instance property values should be substituted into the URIs where 576 matching braces ('{', '}') are found surrounding zero or more 577 characters, creating an expanded URI. Instance property value 578 substitutions are resolved by using the text between the braces to 579 denote the property name from the instance to get the value to 580 substitute. For example, if an href value is defined: 582 http://somesite.com/{id} 584 Then it would be resolved by replace the value of the "id" property 585 value from the instance object. If the value of the "id" property 586 was "45", the expanded URI would be: 588 http://somesite.com/45 590 If matching braces are found with the string "-this" (no quotes) 591 between the braces, than the actual instance value should be used to 592 replace the braces, rather than a property value. This should only 593 be used in situations where the instance is a scalar (string, 594 boolean, or number), and not for objects or arrays. 596 6.1.1.2. rel 598 The value of the "rel" property indicates the name of the relation to 599 the target resource. The relation to the target should be 600 interpreted as specifically from the instance object that the schema 601 (or sub-schema) applies to, not just the top level resource that 602 contains the object within its hierarchy. If a resource JSON 603 representation contains a sub object with a property interpreted as a 604 link, that sub-object holds the relation with the target. A relation 605 to target from the top level resource must be indicated with the 606 schema describing the top level JSON representation. 608 Relationship definitions SHOULD NOT be media type dependent, and 609 users are encouraged to utilize existing accepted relation 610 definitions, including those in existing relation registries (see 611 &rfc4287). However, we define these relation here for clarity of 612 normative interpretation within the context of JSON hyper schema 613 defined relations: 615 self - If the relation value is "self", when this property is 616 encountered in the instance object, the object represents a 617 resource and the instance object is treated as a full 618 representation of the target resource identified by the specified 619 URI. 621 full - This indicates that the target of the link is the full 622 representation for the instance object. The object that contains 623 this link may not be the full representation. 625 describedby - This indicates the target of the link is the schema 626 for the instance object. This may be used to specifically denote 627 the schemas of objects within a JSON object hierarchy, 628 facilitating polymorphic type data structures. 630 The following relations are applicable for schemas (the schema as 631 the "from" resource in the relation). 633 instances - This indicates the target resource that represents 634 collection of instances of a schema. 636 create - This indicates a target to use for creating new instances 637 of a schema. This link definition SHOULD be a submission link 638 with a non-safe method (like POST). 640 For example, if a schema is defined: 642 { 643 "links": [ 644 { 645 "rel": "self" 646 "href": "{id}" 647 }, 648 { 649 "rel": "up" 650 "href": "{upId}" 651 }, 652 { 653 "rel": "children" 654 "href": "?upId={id}" 655 } 656 ] 657 } 659 And if a collection of instance resource's JSON representation was 660 retrieved: 662 GET /Resource/ 664 [ 665 { 666 "id": "thing", 667 "upId": "parent" 668 }, 669 { 670 "id": "thing2", 671 "upId": "parent" 672 } 673 ] 675 This would indicate that for the first item in the collection, it's 676 own (self) URI would resolve to "/Resource/thing" and the first 677 item's "up" relation should be resolved to the resource at 678 "/Resource/parent". The "children" collection would be located at 679 "/Resource/?upId=thing". 681 6.1.1.3. Submission Link Properties 683 The following properties also apply to link definition objects, and 684 provide functionality analogous to HTML forms, in providing a means 685 for submitting extra (often user supplied) information to send to a 686 server. 688 6.1.1.3.1. method 690 This indicates which method should be used to access the target 691 resource. In an HTTP environment, this would be "GET" or "POST" 692 (other HTTP methods such as "PUT" and "DELETE" have semantics that 693 are clearly implied by accessed resources, and do not need to be 694 defined here). This defaults to "GET". 696 6.1.1.3.2. enctype 698 If present, this property indicates a query media type format that 699 the server supports for querying or posting to the collection of 700 instances at the target resource. The query can be suffixed to the 701 target URI to query the collection with property-based constraints on 702 the resources that SHOULD be returned from the server or used to post 703 data to the resource (depending on the method). For example, with 704 the following schema: 706 { 707 "links":[ 708 { 709 "enctype": "application/x-www-form-urlencoded", 710 "method": "GET", 711 "href": "/Product/", 712 "properties":{ 713 "name":{"description":"name of the product"} 714 } 715 } 716 ] 717 } 719 This indicates that the client can query the server for instances 720 that have a specific name: 722 /Product/?name=Slinky 724 If no enctype or method is specified, only the single URI specified 725 by the href property is defined. If the method is POST, application/ 726 json is the default media type. 728 6.1.1.3.3. properties 730 This is inherited from the base JSON schema definition, and can 731 follow the same structure, but its meaning should be used to define 732 the acceptable property names and values for the action (whether it 733 be for the GET query or POST body). If properties are omitted, and 734 this form is the child of a schema, the properties from the parent 735 schema should be used as the basis for the form action. 737 6.2. fragmentResolution 739 This property indicates the fragment resolution protocol to use for 740 resolving fragment identifiers in URIs within the instance 741 representations. This applies to the instance object URIs and all 742 children of the instance object's URIs. The default fragment 743 resolution protocol is "dot-delimited", which is defined below. 744 Other fragment resolution protocols may be used, but are not defined 745 in this document. 747 The fragment identifier is based on RFC 2396 Sec 5, and defines the 748 mechanism for resolving references to entities within a document. 750 6.2.1. dot-delimited fragment resolution 752 With the dot-delimited fragment resolution protocol, the fragment 753 identifier is interpreted as a series of property reference tokens 754 that are delimited by the "." character (\x2E). Each property 755 reference token is a series of any legal URI component characters 756 except the "." character. Each property reference token should be 757 interpreted, starting from the beginning of the fragment identifier, 758 as a path reference in the target JSON structure. The final target 759 value of the fragment can be determined by starting with the root of 760 the JSON structure from the representation of the resource identified 761 by the pre-fragment URI. If the target is a JSON object, than the 762 new target is the value of the property with the name identified by 763 the next property reference token in the fragment. If the target is 764 a JSON array, than the target is determined by finding the item in 765 array the array with the index defined by the next property reference 766 token (which MUST be a number). The target is successively updated 767 for each property reference token, until the entire fragment has been 768 traversed. 770 Property names SHOULD be URI-encoded. In particular, any "." in a 771 property name MUST be encoded to avoid being interpreted as a 772 property delimiter. 774 For example, for the following JSON representation: 776 { 777 "foo":{ 778 "anArray":[ 779 {"prop":44} 780 ], 781 "another prop":{ 782 "baz":"A string" 783 } 784 } 785 } 787 The following fragment identifiers would be resolved: 789 fragment identifier resolution 790 ------------------- ---------- 791 # self, the root of the resource itself 792 #foo the object referred to by the foo property 793 #foo.another prop the object referred to by the "another prop" 794 property of the object referred to by the 795 "foo" property 796 #foo.another prop.baz the string referred to by the value of "baz" 797 property of the "another prop" property of 798 the object referred to by the "foo" property 799 #foo.anArray.0 the first object in the "anArray" array 801 6.3. root 803 This attribute indicates that the value of the instance property 804 value SHOULD be treated as the root or the body of the representation 805 for the purposes of user agent interaction and fragment resolution 806 (all other properties of the instance objects are can be regarded as 807 meta-data descriptions for the data). 809 6.4. readonly 811 This indicates that the instance property should not be changed. 812 Attempts by a user agent to modify the value of this property are 813 expected to be rejected by a server. 815 6.5. pathStart 817 This property value is a URI-Reference that indicates the URI that 818 all the URIs for the instances of the schema should start with. When 819 multiple schemas have been referenced for an instance, the user agent 820 can determine if this schema is applicable for a particular instance 821 by determining if URI of the instance begins with the pathStart's 822 referenced URI. pathStart MUST be resolved as per [RFC3986] section 823 5. If the URI of the instance does not start with URI indicated by 824 pathStart, or if another schema specifies a starting URI that is 825 longer and also matches the instance, this schema should not be 826 applied to the instance. Any schema that does not have a pathStart 827 attribute should be considered applicable to all the instances for 828 which it is referenced. 830 6.6. mediaType 832 This indicates the media type of the instance representations that 833 this schema is defining. 835 6.7. alternate 837 This is an array of JSON schema definitions that define any other 838 schemas for alternate JSON-based representations of the instance 839 resources. 841 7. Security Considerations 843 This specification is a sub-type of the JSON format, and consequently 844 the security considerations are generally the same as RFC 4627. 845 However, an additional issue is that when link relation of "self" is 846 used to denote a full representation of an object, the user agent 847 SHOULD NOT consider the representation to be the authoritative 848 representation of the resource denoted by the target URI if the 849 target URI is not equivalent to or a sub-path of the the URI used to 850 request the resource representation which contains the target URI 851 with the "self" link. For example, if a hyper schema was defined: 853 { 854 "links":[ 855 { 856 "rel":"self", 857 "href":"{id}" 858 } 859 ] 860 } 862 And a resource was requested from somesite.com: 864 GET /foo/ 866 With a response of: 868 Content-Type: application/json; describedby=/schema-for-this-data 869 [ 870 {"id":"bar", "name":"This representation can be safely treated \ 871 as authoritative "}, 872 {"id":"/baz", "name":"This representation should not be treated as \ 873 authoritative the user agent should make request the resource\ 874 from "/baz" to ensure it has the authoritative representation"}, 875 {"id":"http://othersite.com/something", "name":"This representation\ 876 should also not be treated as authoritative and the target\ 877 resource representation should be retrieved for the\ 878 authoritative representation"} 879 ] 880 8. IANA Considerations 882 The proposed MIME media type for JSON Schema is application/ 883 schema+json 885 Type name: application 887 Subtype name: schema+json 889 Required parameters: describedby 891 The value of the describedby parameter should be a URI (relative or 892 absolute) that refers to the schema used to define the structure of 893 this structure (the meta-schema). Normally the value would be 894 http://json-schema.org/hyper-schema, but it is allowable to use other 895 schemas that extend the hyper schema's meta- schema. 897 Optional parameters: pretty 899 The value of the pretty parameter may be true or false to indicate if 900 additional whitespace has been included to make the JSON 901 representation easier to read. 903 8.1. Registry of Link Relations 905 This registry is maintained by IANA per RFC 4287 and this 906 specification adds three values: "full", "create", "instances". New 907 assignments are subject to IESG Approval, as outlined in [RFC5226]. 908 Requests should be made by email to IANA, which will then forward the 909 request to the IESG, requesting approval. 911 9. References 913 9.1. Normative References 915 [RFC3986] Berners-Lee, T., Fielding, R., and 916 L. Masinter, "Uniform Resource 917 Identifier (URI): Generic Syntax", 918 STD 66, RFC 3986, January 2005. 920 [RFC2119] Bradner, S., "Key words for use in 921 RFCs to Indicate Requirement 922 Levels", BCP 14, RFC 2119, 923 March 1997. 925 [RFC4287] Nottingham, M., Ed. and R. Sayre, 926 Ed., "The Atom Syndication 927 Format", RFC 4287, December 2005. 929 [RFC3339] Klyne, G., Ed. and C. Newman, 930 "Date and Time on the Internet: 931 Timestamps", RFC 3339, July 2002. 933 [RFC2045] Freed, N. and N. Borenstein, 934 "Multipurpose Internet Mail 935 Extensions (MIME) Part One: Format 936 of Internet Message Bodies", 937 RFC 2045, November 1996. 939 9.2. Informative References 941 [RFC4627] Crockford, D., "The application/ 942 json Media Type for JavaScript 943 Object Notation (JSON)", RFC 4627, 944 July 2006. 946 [RFC2616] Fielding, R., Gettys, J., Mogul, 947 J., Frystyk, H., Masinter, L., 948 Leach, P., and T. Berners-Lee, 949 "Hypertext Transfer Protocol -- 950 HTTP/1.1", RFC 2616, June 1999. 952 [RFC5226] Narten, T. and H. Alvestrand, 953 "Guidelines for Writing an IANA 954 Considerations Section in RFCs", 955 BCP 26, RFC 5226, May 2008. 957 [I-D.hammer-discovery] Hammer-Lahav, E., "Link-based 958 Resource Descriptor Discovery", 959 draft-hammer-discovery-03 (work in 960 progress), March 2009. 962 [I-D.gregorio-uritemplate] Gregorio, J., "URI Template", 963 draft-gregorio-uritemplate-03 964 (work in progress), April 2008. 966 [I-D.nottingham-http-link-header] Nottingham, M., "Web Linking", dra 967 ft-nottingham-http-link-header-06 968 (work in progress), July 2009. 970 [W3C.REC-html401-19991224] Hors, A., Jacobs, I., and D. 971 Raggett, "HTML 4.01 972 Specification", World Wide Web 973 Consortium Recommendation REC- 974 html401-19991224, December 1999, < 975 http://www.w3.org/TR/1999/ 976 REC-html401-19991224>. 978 Appendix A. Change Log 980 -01 982 o Fixed category and updates from template 984 -00 986 o Initial draft 988 Appendix B. Open Issues 990 Should we give a preference to MIME headers over Link headers (or 991 only use one)? 993 Should we use "profile" as the media type parameter instead? 995 Should "root" be a MIME parameter instead of a schema attribute? 997 Should "format" be renamed to "mediaType" or "contentType" to reflect 998 the usage MIME media types that are allowed. 1000 I still do not like how dates are handled. 1002 Author's Address 1004 Kris Zyp (editor) 1005 SitePen (USA) 1006 530 Lytton Avenue 1007 Palo Alto, CA 94301 1008 USA 1010 Phone: +1 650 968 8787 1011 EMail: kris@sitepen.com