idnits 2.17.1 draft-wright-json-schema-hyperschema-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 13, 2016) is 2744 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 5988 (Obsoleted by RFC 8288) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force A. Wright, Ed. 3 Internet-Draft 4 Intended status: Informational G. Luff 5 Expires: April 16, 2017 October 13, 2016 7 JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON 8 draft-wright-json-schema-hyperschema-00 10 Abstract 12 JSON Schema is a JSON based format for defining the structure of JSON 13 data. This document specifies hyperlink- and hypermedia-related 14 keywords of JSON Schema for annotating JSON documents with hyperlinks 15 and instructions for processing and manipulating remote JSON 16 resources through hypermedia environments like HTTP. 18 Note to Readers 20 The issues list for this draft can be found at . 23 For additional information, see . 25 To provide feedback, use this issue tracker, the communication 26 methods listed on the homepage, or email the document editors. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on April 16, 2017. 45 Copyright Notice 47 Copyright (c) 2016 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 Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3 64 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 65 4. Schema keywords . . . . . . . . . . . . . . . . . . . . . . . 5 66 4.1. base . . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 4.2. links . . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 4.3. media . . . . . . . . . . . . . . . . . . . . . . . . . . 7 69 4.3.1. Properties of "media" . . . . . . . . . . . . . . . . 7 70 4.3.2. Example . . . . . . . . . . . . . . . . . . . . . . . 7 71 4.4. readOnly . . . . . . . . . . . . . . . . . . . . . . . . 8 72 5. Link Description Object . . . . . . . . . . . . . . . . . . . 8 73 5.1. href . . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 5.1.1. URI Templating . . . . . . . . . . . . . . . . . . . 9 75 5.2. rel . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 76 5.2.1. Security Considerations for "self" links . . . . . . 13 77 5.3. title . . . . . . . . . . . . . . . . . . . . . . . . . . 14 78 5.4. targetSchema . . . . . . . . . . . . . . . . . . . . . . 15 79 5.4.1. Security Considerations for "targetSchema" . . . . . 15 80 5.5. mediaType . . . . . . . . . . . . . . . . . . . . . . . . 16 81 5.5.1. Security concerns for "mediaType" . . . . . . . . . . 17 82 5.6. Submission Form Properties . . . . . . . . . . . . . . . 18 83 5.6.1. method . . . . . . . . . . . . . . . . . . . . . . . 18 84 5.6.2. encType . . . . . . . . . . . . . . . . . . . . . . . 18 85 5.6.3. schema . . . . . . . . . . . . . . . . . . . . . . . 19 86 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 87 6.1. Normative References . . . . . . . . . . . . . . . . . . 19 88 6.2. Informative References . . . . . . . . . . . . . . . . . 20 89 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 21 90 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 21 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 93 1. Introduction 95 JSON Schema is a JSON based format for defining the structure of JSON 96 data. This document specifies hyperlink- and hypermedia-related 97 keywords of JSON Schema. 99 The term JSON Hyper-Schema is used to refer to a JSON Schema that 100 uses these keywords. 102 This specification will use the terminology defined by the JSON 103 Schema core specification [json-schema]. It is advised that readers 104 have a copy of this specification. 106 2. Conventions and Terminology 108 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 109 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 110 document are to be interpreted as described in RFC 2119 [RFC2119]. 112 The terms "schema", "instance", "property" and "item" are to be 113 interpreted as defined in the JSON Schema core specification 114 [json-schema]. 116 3. Overview 118 This document describes how JSON Schema can be used to define 119 hyperlinks on instance data. It also defines how to provide 120 additional information required to interpret JSON data as rich 121 multimedia documents. 123 As with all JSON Schema keywords, all the keywords described in the 124 "Schema Keywords" section are optional. The minimal valid JSON 125 Hyper-schema is the blank object. 127 Here is an example JSON Schema defining hyperlinks, and providing a 128 multimedia interpretation for the "imgData" property: 130 { 131 "title": "Written Article", 132 "type": "object", 133 "properties": { 134 "id": { 135 "title": "Article Identifier", 136 "type": "number", 137 "readOnly": true 138 }, 139 "title": { 140 "title": "Article Title", 141 "type": "string" 142 }, 143 "authorId": { 144 "type": "integer" 145 }, 146 "imgDataPng": { 147 "title": "Article Illustration (thumbnail)", 148 "type": "string", 149 "media": { 150 "binaryEncoding": "base64", 151 "type": "image/png" 152 } 153 } 154 }, 155 "required" : ["id", "title", "authorId"], 156 "links": [ 157 { 158 "rel": "self", 159 "href": "/article{?id}" 160 }, 161 { 162 "rel": "author", 163 "href": "/user?id={authorId}" 164 } 165 ] 166 } 168 This example schema defines the properties of the instance. For the 169 "imgData" property, it specifies that that it should be 170 base64-decoded and the resulting binary data treated as a PNG image. 171 It also defines link relations for the instance, with URIs 172 incorporating values from the instance. [[CREF1: "id" probably 173 should not normally be a required keyword, since new instances will 174 have an unknown "id" property until is it assigned by the server. 175 However, this property is used in a link, and without it, multiple 176 different instances would be given the same rel=self URI!]] 177 An example of a JSON instance described by the above schema might be: 179 { 180 "id": 15, 181 "title": "Example data", 182 "authorId": 105, 183 "imgData": "iVBORw...kJggg==" 184 } 186 The base-64 data has been abbreviated for readability. 188 4. Schema keywords 190 4.1. base 192 If present, this keyword is resolved against the current URI base 193 that the entire instance is found within, and sets the new URI base 194 for URI references within the instance. It is therefore the first 195 URI Reference resolved, regardless of which order it was found in. 197 The URI is computed from the provided URI template using the same 198 process described for the "href" (Section 5.1) property of a Link 199 Description Object. 201 An example of a JSON schema using "base": 203 { 204 "base": "/object/{id}", 205 "links": [ 206 { 207 "rel": "self", 208 "href": "" 209 }, 210 { 211 "rel": "next", 212 "href": "{next_id}" 213 } 214 ] 215 } 216 An example of a JSON instance using this schema to produce rel="self" 217 and rel="next" links: 219 { 220 "id": "41", 221 "next_id": "42" 222 } 224 If the document URI is , then the new URI 225 base becomes 227 Resolving the two Link Description Objects against this URI base 228 creates two links exactly equivelant to these absolute-form HTTP Link 229 headers: 231 o Link: ;rel=self 233 o Link: ;rel=next 235 4.2. links 237 The "links" property of schemas is used to associate Link Description 238 Objects with instances. The value of this property MUST be an array, 239 and the items in the array must be Link Description Objects, as 240 defined below. 242 An example schema using the "links" keyword could be: 244 { 245 "title": "Schema defining links", 246 "links": [ 247 { 248 "rel": "self", 249 "href": "{id}" 250 }, 251 { 252 "rel": "parent", 253 "href": "{parent}" 254 } 255 ] 256 } 258 4.3. media 260 The "media" property indicates that this instance contains non-JSON 261 data encoded in a JSON string. It describes the type of content and 262 how it is encoded. 264 The value of this property MUST be an object. The value of this 265 property SHOULD be ignored if the instance described is not a string. 267 4.3.1. Properties of "media" 269 The value of the "media" keyword MAY contain any of the following 270 properties: 272 4.3.1.1. binaryEncoding 274 If the instance value is a string, this property defines that the 275 string SHOULD be interpreted as binary data and decoded using the 276 encoding named by this property. RFC 2045, Sec 6.1 [RFC2045] lists 277 the possible values for this property. 279 4.3.1.2. type 281 The value of this property must be a media type, as defined by RFC 282 2046 [RFC2046]. This property defines the media type of instances 283 which this schema defines. 285 If the "binaryEncoding" property is not set, but the instance value 286 is a string, then the value of this property SHOULD specify a text 287 document type, and the character set SHOULD be the character set into 288 which the JSON string value was decoded (for which the default is 289 Unicode). 291 4.3.2. Example 292 Here is an example schema, illustrating the use of "media": 294 { 295 "type": "string", 296 "media": { 297 "binaryEncoding": "base64", 298 "type": "image/png" 299 } 300 } 302 Instances described by this schema should be strings, and their 303 values should be interpretable as base64-encoded PNG images. 305 Another example: 307 { 308 "type": "string", 309 "media": { 310 "mediaType": "text/html" 311 } 312 } 314 Instances described by this schema should be strings containing HTML, 315 using whatever character set the JSON string was decoded into 316 (default is Unicode). 318 4.4. readOnly 320 If it has a value of boolean true, this keyword indicates that the 321 value of the instance is managed exclusively by the server or the 322 owning authority, and attempts by a user agent to modify the value of 323 this property are expected to be ignored or rejected by a server. 325 For example, this property would be used to mark a server-generated 326 serial number as read-only. 328 The value of this keyword MUST be a boolean. The default value is 329 false. 331 5. Link Description Object 333 A Link Description Object (LDO) is used to describe a single link 334 relation from the instance to another resource. A Link Description 335 Object must be an object. 337 The link description format can be used without JSON Schema, and use 338 of this format can be declared by referencing the normative link 339 description schema as the schema for the data structure that uses the 340 links. The URI of the normative link description schema is: 341 http://json-schema.org/draft-04/links (draft-04 version). 343 "Form"-like functionality can be defined by use of the "method" and 344 "schema" keywords, which supplies a schema describing the data to 345 supply to the server. 347 5.1. href 349 The value of the "href" link description property is a template used 350 to determine the target URI of the related resource. The value of 351 the instance property MUST be resolved as a URI-reference [RFC3986] 352 against the base URI of the instance. 354 This property is REQUIRED. 356 5.1.1. URI Templating 358 The value of "href" is to be used as a URI Template, as defined in 359 RFC 6570 [RFC6570]. However, some special considerations apply: 361 5.1.1.1. Pre-processing 363 [[CREF2: This pre-processing section is subject to significant change 364 in upcoming drafts.]] 366 The URI Template specification [RFC6570] restricts the set of 367 characters available for variable names. Property names in JSON, 368 however, can be any UTF-8 string. 370 To allow the use of any JSON property name in the template, before 371 using the value of "href" as a URI Template, the following pre- 372 processing rules MUST be applied, in order: 374 5.1.1.1.1. Bracket escaping 376 The purpose of this step is to allow the use of brackets to percent- 377 encode variable names inside curly brackets. Variable names to be 378 escaped are enclosed within rounded brackets, with the close-rounded- 379 bracket character ")" being escaped as a pair of close-rounded- 380 brackets "))". Since the empty string is not a valid variable name 381 in RFC 6570, an empty pair of brackets is replaced with "%65mpty". 383 The rules are as follows: 385 Find the largest possible sections of the text such that: 387 do not contain an odd number of close-rounded-bracket characters 388 ")" in sequence in that section of the text 390 are surrounded by a pair of rounded brackets: ( ), where 392 the surrounding rounded brackets are themselves contained within a 393 pair of curly brackets: { } 395 Each of these sections of the text (including the surrounding rounded 396 brackets) MUST be replaced, according to the following rules: 398 If the brackets contained no text (the empty string), then they 399 are replaced with "%65mpty" (which is "empty" with a percent- 400 encoded "e") 402 Otherwise, the enclosing brackets are removed, and the inner text 403 used after the following modifications 405 all pairs of close-brackets "))" are replaced with a single 406 close bracket 408 after that, the text is replaced with its percent-encoded 409 equivalent, such that the result is a valid RFC 6570 variable 410 name (note that this requires encoding characters such as "*" 411 and "!") 413 5.1.1.1.2. Replacing $ 415 After the above substitutions, if the character "$" (dollar sign) 416 appears within a pair of curly brackets, then it MUST be replaced 417 with the text "%73elf" (which is "self" with a percent-encoded "s"). 419 The purpose of this stage is to allow the use of the instance value 420 itself (instead of its object properties or array items) in the URI 421 Template, by the special value "%73elf". 423 5.1.1.1.3. Choice of special-case values 425 The special-case values of "%73elf" and "%65mpty" were chosen because 426 they are unlikely to be accidentally generated by either a human or 427 automated escaping. 429 5.1.1.1.4. Examples 431 For example, here are some possible values for "href", followed by 432 the results after pre-processing: 434 +-----------------------+-----------------------+ 435 | Input | Output | 436 +-----------------------+-----------------------+ 437 | "no change" | "no change" | 438 | "(no change)" | "(no change)" | 439 | "{(escape space)}" | "{escape%20space}" | 440 | "{(escape+plus)}" | "{escape%2Bplus}" | 441 | "{(escape*asterisk)}" | "{escape%2Aasterisk}" | 442 | "{(escape(bracket)}" | "{escape%28bracket}" | 443 | "{(escape))bracket)}" | "{escape%29bracket}" | 444 | "{(a))b)}" | "{a%29b} | 445 | "{(a (b)))}" | "{a%20%28b%29} | 446 | "{()}" | "{%65mpty} | 447 | "{+$*}" | "{+%73elf*} | 448 | "{+($)*}" | "{+%24*} | 449 +-----------------------+-----------------------+ 451 Note that in the final example, because the "+" was outside the 452 brackets, it remained unescaped, whereas in the fourth example the 453 "+" was escaped. 455 5.1.1.2. Values for substitution 457 After pre-processing, the URI Template is filled out using data from 458 the instance. To allow the use of any object property (including the 459 empty string), array index, or the instance value itself, the 460 following rules are defined: 462 For a given variable name in the URI Template, the value to use is 463 determined as follows: 465 If the variable name is "%73elf", then the instance value itself 466 MUST be used. 468 If the variable name is "%65mpty", then the instances's empty- 469 string ("") property MUST be used (if it exists). 471 If the instance is an array, and the variable name is a 472 representation of a non-negative integer, then the value at the 473 corresponding array index MUST be used (if it exists). 475 Otherwise, the variable name should be percent-decoded, and the 476 corresponding object property MUST be used (if it exists). 478 5.1.1.2.1. Converting to strings 480 When any value referenced by the URI template is null, a boolean or a 481 number, then it should first be converted into a string as follows: 483 null values SHOULD be replaced by the text "null" 485 boolean values SHOULD be replaced by their lower-case equivalents: 486 "true" or "false" 488 numbers SHOULD be replaced with their original JSON 489 representation. 491 In some software environments the original JSON representation of a 492 number will not be available (there is no way to tell the difference 493 between 1.0 and 1), so any reasonable representation should be used. 494 Schema and API authors should bear this in mind, and use other types 495 (such as string or boolean) if the exact representation is important. 497 5.1.1.3. Missing values 499 Sometimes, the appropriate values will not be available. For 500 example, the template might specify the use of object properties, but 501 the instance is an array or a string. 503 If any of the values required for the template are not present in the 504 JSON instance, then substitute values MAY be provided from another 505 source (such as default values). Otherwise, the link definition 506 SHOULD be considered not to apply to the instance. 508 5.2. rel 510 The value of the "rel" property indicates the name of the relation to 511 the target resource. The value MUST be a registered link relation 512 from the IANA Link Relation Type Registry established in RFC 5988 513 [RFC5988], or a normalized URI following the URI production of RFC 514 3986 [RFC3986]. 516 The relation to the target is interpreted as from the instance that 517 the schema (or sub-schema) applies to, not any larger document that 518 the instance may have been found in. 520 Relationship definitions are not normally media type dependent, and 521 users are encouraged to utilize existing accepted relation 522 definitions. 524 For example, if a schema is defined: 526 { 527 "links": [{ 528 "rel": "self", 529 "href": "{id}" 530 }, { 531 "rel": "up", 532 "href": "{upId}" 533 }] 534 } 536 And if a collection of instance resources were retrieved with JSON 537 representation: 539 GET /Resource/ 541 [{ 542 "id": "thing", 543 "upId": "parent" 544 }, { 545 "id": "thing2", 546 "upId": "parent" 547 }] 549 This would indicate that for the first item in the collection, its 550 own (self) URI would resolve to "/Resource/thing" and the first 551 item's "up" relation SHOULD be resolved to the resource at 552 "/Resource/parent". 554 Note that these relationship values are case-insensitive, consistent 555 with their use in HTML and the HTTP Link header [RFC5988]. 557 5.2.1. Security Considerations for "self" links 559 When link relation of "self" is used to denote a full representation 560 of an object, the user agent SHOULD NOT consider the representation 561 to be the authoritative representation of the resource denoted by the 562 target URI if the target URI is not equivalent to or a sub-path of 563 the the URI used to request the resource representation which 564 contains the target URI with the "self" link. 566 For example, if a hyper schema was defined: 568 { 569 "links": [{ 570 "rel": "self", 571 "href": "{id}" 572 }] 573 } 575 And a resource was requested from somesite.com: 577 GET /foo/ 579 With a response of (with newlines and whitespace added): 581 Content-Type: application/json; profile="http://example.com/alpha" 583 [{ 584 "id": "bar", 585 "name": "This representation can be safely treated 586 as authoritative " 587 }, { 588 "id": "/baz", 589 "name": "This representation should not be treated as 590 authoritative the user agent should make request the 591 resource from '/baz' to ensure it has the authoritative 592 representation" 593 }, { 594 "id": "http://othersite.com/something", 595 "name": "This representation 596 should also not be treated as authoritative and the 597 target resource representation should be retrieved 598 for the authoritative representation" 599 }] 601 5.3. title 603 This property defines a title for the link. The value must be a 604 string. 606 User agents MAY use this title when presenting the link to the user. 608 5.4. targetSchema 610 This property provides a schema that is expected to describe the link 611 target, including what a client can expect if it makes an HTTP GET 612 request, and what it should send if it replaces the resource in an 613 HTTP PUT request. This property is advisory only. 615 5.4.1. Security Considerations for "targetSchema" 617 This property has similar security concerns to that of "mediaType". 618 Clients MUST NOT use the value of this property to aid in the 619 interpretation of the data received in response to following the 620 link, as this leaves "safe" data open to re-interpretation. 622 For example, suppose two programmers are having a discussion about 623 web security using a text-only message board. Here is some data from 624 that conversation, with a URI of: 625 http://forum.example.com/topics/152/comments/13 627 { 628 "topicId": 152, 629 "commentId": 13, 630 "from": { 631 "name": "Jane", 632 "id": 5 633 }, 634 "to": { 635 "name": "Jason", 636 "id": 8 637 }, 638 "message": "It's easy, just add some HTML like 639 this: " 640 } 642 The message string was split over two lines for readability. 644 A third party might then write provide the following Link Description 645 Object at another location: 647 { 648 "rel": "evil-attack", 649 "href": "http://forum.example.com/topics/152/comments/13", 650 "targetSchema": { 651 "properties": { 652 "message": { 653 "description": "Re-interpret `message` as HTML", 654 "media": { 655 "type": "text/html" 656 } 657 } 658 } 659 } 660 } 662 If the client used this "targetSchema" value when interpreting the 663 above data, then it might display the contents of "message" as HTML. 664 At this point, the JavaScript embedded in the message might be 665 executed (in the context of the "forum.example.com" domain). 667 5.5. mediaType 669 The value of this property is advisory only, and represents the media 670 type RFC 2046 [RFC2046], that is expected to be returned when 671 fetching this resource. This property value MAY be a media range 672 instead, using the same pattern defined in RFC 7231, section 5.3.1 - 673 HTTP "Accept" header [RFC7231]. 675 This property is analogous to the "type" property of elements in 676 HTML (advisory content type), or the "type" parameter in the HTTP 677 Link header [RFC5988]. User agents MAY use this information to 678 inform the interface they present to the user before the link is 679 followed, but this information MUST NOT use this information in the 680 interpretation of the resulting data. When deciding how to interpret 681 data obtained through following this link, the behaviour of user 682 agents MUST be identical regardless of the value of the this 683 property. 685 If this property's value is specified, and the link's target is to be 686 obtained using any protocol that supports the HTTP/1.1 "Accept" 687 header RFC 7231, section 5.3.1 [RFC7231], then user agents MAY use 688 the value of this property to aid in the assembly of that header when 689 making the request to the server. 691 If this property's value is not specified, then the value should be 692 taken to be "application/json". 694 For example, if a schema is defined: 696 { 697 "links": [{ 698 "rel": "self", 699 "href": "/{id}/json" 700 }, { 701 "rel": "alternate", 702 "href": "/{id}/html", 703 "mediaType": "text/html" 704 }, { 705 "rel": "alternate", 706 "href": "/{id}/rss", 707 "mediaType": "application/rss+xml" 708 }, { 709 "rel": "icon", 710 "href": "{id}/icon", 711 "mediaType": "image/*" 712 }] 713 } 715 A suitable instance described by this schema would have four links 716 defined. The link with a "rel" value of "self" would have an 717 expected MIME type of "application/json" (the default). The two 718 links with a "rel" value of "alternate" specify the locations of HTML 719 and RSS versions of the current item. The link with a "rel" value of 720 "icon" links to an image, but does not specify the exact format. 722 A visual user agent displaying the item from the above example might 723 present a button representing an RSS feed, which when pressed passes 724 the target URI (calculated "href" value) to an view more suited to 725 displaying it, such as a news feed aggregator tab. 727 Note that presenting the link in the above manner, or passing the URI 728 to a news feed aggregator view does not constitute interpretation of 729 the data, but an interpretation of the link. The interpretation of 730 the data itself is performed by the news feed aggregator, which 731 SHOULD reject any data that would not have also been interpreted as a 732 news feed, had it been displayed in the main view. 734 5.5.1. Security concerns for "mediaType" 736 The "mediaType" property in link definitions defines the expected 737 format of the link's target. However, this is advisory only, and 738 MUST NOT be considered authoritative. 740 When choosing how to interpret data, the type information provided by 741 the server (or inferred from the filename, or any other usual method) 742 MUST be the only consideration, and the "mediaType" property of the 743 link MUST NOT be used. User agents MAY use this information to 744 determine how they represent the link or where to display it (for 745 example hover-text, opening in a new tab). If user agents decide to 746 pass the link to an external program, they SHOULD first verify that 747 the data is of a type that would normally be passed to that external 748 program. 750 This is to guard against re-interpretation of "safe" data, similar to 751 the precautions for "targetSchema". 753 5.6. Submission Form Properties 755 The following properties also apply to Link Description Objects, and 756 provide functionality analogous to HTMLforms [W3C.CR-html5-20140731], 757 by providing a means for making a request with client- or user- 758 selected information. 760 5.6.1. method 762 This property specifies that the client can construct a templated 763 query or non-idempotent request to a resource. 765 If "method" is "get", the link identifies how a user can compute the 766 URI of an arbritrary resource. For example, how compute a link to a 767 page of search results relating to the instance, for a user-selected 768 query term. Despite being named after GET, there is no constraint on 769 the method or protocol used to interact with the remote resource. 771 If "method" is "post", the link specifies how a user can construct a 772 document to submit to the link target for evaluation. 774 Values for this property SHOULD be lowercase, and SHOULD be compared 775 case-insensitive. Use of other values not defined here SHOULD be 776 ignored. 778 5.6.2. encType 780 If present, this property indicates the media type format the client 781 should use to encode a query parameter or send to the server. posting 782 to the collection of instances at the target resource. If the method 783 is "get", this will indicate how to encode the query-string that is 784 appended to the "href" link target. If the method is "post", this 785 indicates which media type to send to the server and how to encode 786 it. 788 For example, with the following schema: 790 { 791 "links": [{ 792 "encType": "application/x-www-form-urlencoded", 793 "method": "get", 794 "href": "/Product/", 795 "properties": { 796 "name": { 797 "description": "name of the product" 798 } 799 } 800 }] 801 } 803 This indicates that the client can query the server for instances 804 that have a specific name. 806 For example: 808 /Product/?name=Slinky 810 If the method is "post", "application/json" is the default media 811 type. 813 5.6.3. schema 815 This property contains a schema which defines the acceptable 816 structure of the document being encoded according to the "encType" 817 property. 819 Note that this does not provide data for any URI templates. This is 820 a separate concept from the "targetSchema" property, which is 821 describing the target information resource (including for replacing 822 the contents of the resource in a PUT request), unlike "schema" which 823 describes the user-submitted request data to be evaluated by the 824 resource. 826 6. References 828 6.1. Normative References 830 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 831 Extensions (MIME) Part One: Format of Internet Message 832 Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996, 833 . 835 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 836 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 837 RFC2119, March 1997, 838 . 840 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 841 Resource Identifier (URI): Generic Syntax", STD 66, RFC 842 3986, DOI 10.17487/RFC3986, January 2005, 843 . 845 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 846 and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/ 847 RFC6570, March 2012, 848 . 850 [json-schema] 851 Wright, A., "JSON Schema: A Media Type for Describing JSON 852 Documents", draft-wright-json-schema-00 (work in 853 progress), October 2016. 855 6.2. Informative References 857 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 858 Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 859 10.17487/RFC2046, November 1996, 860 . 862 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/ 863 RFC5988, October 2010, 864 . 866 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 867 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 868 10.17487/RFC7231, June 2014, 869 . 871 [W3C.CR-html5-20140731] 872 Berjon, R., Faulkner, S., Leithead, T., Navara, E., 873 O'Connor, E., and S. Pfeiffer, "HTML5", World Wide 874 Web Consortium CR CR-html5-20140731, July 2014, 875 . 877 Appendix A. Acknowledgments 879 Thanks to Gary Court, Francis Galiegue, Kris Zyp, and Geraint Luff 880 for their work on the initial drafts of JSON Schema. 882 Thanks to Jason Desrosiers, Daniel Perrett, Erik Wilde, Ben Hutton, 883 Evgeny Poberezkin, and Henry H. Andrews for their submissions and 884 patches to the document. 886 Appendix B. Change Log 888 [[CREF3: This section to be removed before leaving Internet-Draft 889 status.]] 891 draft-wright-json-schema-hyperschema-00 893 * "rel" is now optional 895 * rel="self" no longer changes URI base 897 * Added "base" keyword to change instance URI base 899 * Removed "root" link relation 901 * Removed "create" link relation 903 * Removed "full" link relation 905 * Removed "instances" link relation 907 * Removed special behavior for "describedBy" link relation 909 * Removed "pathStart" keyword 911 * Removed "fragmentResolution" keyword 913 * Updated references to JSON Pointer, HTML 915 * Changed behavior of "method" property to align with hypermedia 916 best current practices 918 draft-luff-json-hyper-schema-01 920 * Split from main specification. 922 Authors' Addresses 924 Austin Wright (editor) 926 EMail: aaa@bzfx.net 928 Geraint Luff 929 Cambridge 930 UK 932 EMail: luffgd@gmail.com