|
387 | 387 | The URI of the normative link description schema is: <eref target="http://json-schema.org/draft-04/links">http://json-schema.org/draft-04/links</eref> (draft-04 version). |
388 | 388 | </t> |
389 | 389 |
|
390 | | - <section title="Links and data"> |
| 390 | + <section title="Links, operations, and data"> |
391 | 391 | <t> |
392 | | - Data input functionality can be defined by use of the |
393 | | - <xref target="submissionSchema">"submissionSchema"</xref> and |
394 | | - <xref target="submissionEncType">"submissionEncType"</xref> keywords, |
395 | | - which supply a description of data to send to the target resource for processing. |
396 | | - Functionality equivalent to dynamic URI generation is available through |
397 | | - the <xref target="href">"href"</xref> template and |
398 | | - <xref target="hrefSchema">"hrefSchema"</xref>. |
399 | | - </t> |
400 | | - <t> |
401 | | - The simplest kind of link has an "href" with no template variables, and no "submissionSchema". This does not |
402 | | - allow for any variance in the link URI, nor does it allow for a request document. |
403 | | - </t> |
404 | | - <t> |
405 | | - An "href" with at least one template variable, but no "hrefSchema" or "submissionSchema", allows resolving |
406 | | - the template variable from the instance, but does not allow resolving it |
407 | | - from external data, nor does it allow a request document. |
408 | | - </t> |
409 | | - <t> |
410 | | - An "href" with at least one template variable and with an "hrefSchema" allows using external |
411 | | - data to resolve the template, and falls back to resolving any remaining variables from the instance. |
| 392 | + <cref> |
| 393 | + Note that while the current draft does not provide a way to explicity |
| 394 | + indicate HTTP method support, some way of providing a non-authoritative |
| 395 | + hint may be added in a future draft (see issue #73 in the GitHub repository). |
| 396 | + </cref> |
412 | 397 | </t> |
413 | 398 | <t> |
414 | | - A link with a "submissionSchema" allows submitting data for processing. |
| 399 | + Link Description Objects do not directly indicate what operations, such |
| 400 | + as HTTP methods, are supported by the target resource. Instead, operations |
| 401 | + should be inferred primarily from link <xref target="rel">relation types</xref> |
| 402 | + and URI schemes. Note, however, that a resource may always decline an operation at |
| 403 | + runtime, for instance due to application state that controls the operation's |
| 404 | + availability. |
415 | 405 | </t> |
416 | 406 | <t> |
417 | | - See the individual keyword descriptions below for details related to each of these cases. |
| 407 | + There are several ways that a client can use data can with a link: |
| 408 | + <list> |
| 409 | + <t> URI Template variables resolved from server-supplied instance data </t> |
| 410 | + <t> URI Template variables resolved from client data </t> |
| 411 | + <t> Replacing or modifying the target resource's representation </t> |
| 412 | + <t> Submitting data for processing, where the data has no |
| 413 | + inherent relation to the target resource's representation</t> |
| 414 | + </list> |
| 415 | + The three ways to use client-supplied data are each addressed by a separate |
| 416 | + schema keyword within the link description object. Link operations |
| 417 | + ignore schemas that are not relevant to their semantics. |
418 | 418 | </t> |
| 419 | + <section title="Resolving templated URIs"> |
| 420 | + <t> |
| 421 | + URI Template variables in <xref target="href">"href"</xref> resolve from |
| 422 | + server-supplied instance data by default. |
| 423 | + <xref target="hrefSchema">"hrefSchema"</xref> allows a link to specify |
| 424 | + a schema for resolving template variables from client-supplied data. |
| 425 | + Regular JSON Schema validation features can be used to require resolution |
| 426 | + from client data, forbid it, or allow client data while falling back to |
| 427 | + server-supplied instance data if no client data is provided. |
| 428 | + </t> |
| 429 | + <t> |
| 430 | + The common pattern of resolving a templated path component with |
| 431 | + server-supplied instance data while accepting client data to build |
| 432 | + a query string can be implemented by setting the "hrefSchema" subschemas |
| 433 | + for the path template variables to false, while giving the query string |
| 434 | + template variables names that do not appear in the instance. This ensures |
| 435 | + that the path variables can only be resolved from the instance, and the |
| 436 | + query string variables can only be resolved from client data. |
| 437 | + See the "hrefSchema" section for an example of this approach. |
| 438 | + </t> |
| 439 | + </section> |
| 440 | + <section title="Manipulating the target resource representation"> |
| 441 | + <t> |
| 442 | + In JSON Hyper-Schema, <xref target="targetSchema">"targetSchema"</xref> |
| 443 | + supplies a non-authoritative description of the target resource's representation. |
| 444 | + A client can use "targetSchema" to structure input for replacing or |
| 445 | + modifying the representation. Alternatively, if "targetSchema" is absent |
| 446 | + or if the client prefers to only use authoritative information, it can |
| 447 | + interact with the target resource to confirm or discover its representation |
| 448 | + structure. |
| 449 | + </t> |
| 450 | + <t> |
| 451 | + "targetSchema" is not intended to describe link operation responses, |
| 452 | + except when the response semantics indicate that it is a representation |
| 453 | + of the target resource. In all cases, the schema indicated by the response |
| 454 | + itself is authoritative. See the |
| 455 | + <xref target="targetHTTP" /> for guidance |
| 456 | + specific to each HTTP method when using "targetSchema" with HTTP URIs. |
| 457 | + </t> |
| 458 | + </section> |
| 459 | + <section title="Submitting data for processing"> |
| 460 | + <t> |
| 461 | + The <xref target="submissionSchema">"submissionSchema"</xref> and |
| 462 | + <xref target="submissionEncType">"submissionEncType"</xref> keywords |
| 463 | + describe the domain of the processing function implemented by the target resource. |
| 464 | + Otherwise, as noted above, the submission schema and encoding are ignored |
| 465 | + for operations to which they are not relevant. |
| 466 | + </t> |
| 467 | + </section> |
419 | 468 | </section> |
420 | 469 |
|
421 | | - <!-- Possibly include a short section on motivations, including triples, resources, and progressive disclosure --> |
| 470 | + <!-- Possibly include a short section on motivations, including triples, resources, and progressive disclosure --> |
422 | 471 |
|
423 | 472 | <section title="href" anchor="href"> |
424 | 473 | <t> |
|
587 | 636 | </t> |
588 | 637 | </section> |
589 | 638 |
|
590 | | - <section title="rel"> |
| 639 | + <section title="rel"anchor="rel"> |
591 | 640 | <t> |
592 | 641 | The value of the "rel" property indicates the name of the relation to the target resource. The value MUST be a registered link relation from the <xref target="RFC5988">IANA Link Relation Type Registry established in RFC 5988</xref>, or a normalized URI following the <xref target="RFC3986">URI production of RFC 3986</xref>. |
593 | 642 | </t> |
@@ -711,7 +760,7 @@ GET /foo/ |
711 | 760 | the schema may or may not describe the response to any particular |
712 | 761 | request sent to the link. This property is advisory only. |
713 | 762 | </t> |
714 | | - <section title=""targetSchema" and HTTP"> |
| 763 | + <section title=""targetSchema" and HTTP"anchor="targetHTTP"> |
715 | 764 | <t> |
716 | 765 | The relationship between a resource's representation and |
717 | 766 | HTTP requests and responses is determined by |
@@ -868,7 +917,7 @@ GET /foo/ |
868 | 917 | <section title="submissionEncType" anchor="submissionEncType"> |
869 | 918 | <t> |
870 | 919 | If present, this property indicates the media type format the |
871 | | - client should use to for the request payload described by |
| 920 | + client should use for the request payload described by |
872 | 921 | <xref target="submissionSchema">"submissionSchema"</xref>. |
873 | 922 | </t> |
874 | 923 | <t> |
|
0 commit comments