|
9 | 9 | <!ENTITY rfc5789 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5789.xml"> |
10 | 10 | <!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml"> |
11 | 11 | <!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml"> |
| 12 | +<!ENTITY rfc6573 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6573.xml"> |
12 | 13 | <!ENTITY rfc6901 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6901.xml"> |
13 | 14 | <!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml"> |
14 | 15 | <!ENTITY rfc7240 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7240.xml"> |
|
879 | 880 | Note that these relationship values are case-insensitive, consistent with their |
880 | 881 | use in HTML and the <xref target="RFC5988">HTTP Link header</xref>. |
881 | 882 | </t> |
| 883 | + <section title=""collection" and "item" links"> |
| 884 | + <t> |
| 885 | + <xref target="RFC6573">RFC 6573</xref> defines and registers |
| 886 | + the "item" and "collection" link relations. A well-known design pattern |
| 887 | + in hypermedia is to use a collection resource to create a member of the |
| 888 | + collection and give it a server-assigned URI. When using HTTP, or a protocol |
| 889 | + such as CoAP that is explicitly analogous to HTTP, this is done by POST-ing |
| 890 | + a representation of the individual resource to be created to the collection |
| 891 | + resource. |
| 892 | + </t> |
| 893 | + <t> |
| 894 | + Resources that are the target of a "collection" link using HTTP or an analogous |
| 895 | + protocol in JSON Hyper-Schema MUST NOT assign semantics other than resource |
| 896 | + creation to POST (or the analogous method in non-HTTP protocols). |
| 897 | + </t> |
| 898 | + <t> |
| 899 | + The <xref target="submissionSchema">"submissionSchema"</xref> field for the |
| 900 | + link SHOULD be identical to the schema of the representations of the |
| 901 | + collection's items, as indicated by the "item" link. RFC 6573 identifies |
| 902 | + the "collection" and "item" link relation types as reciprocal, so the |
| 903 | + context resource of an "item" link MAY be treated as a collection, even if |
| 904 | + no explicit "collection" link is defined. |
| 905 | + </t> |
| 906 | + <figure> |
| 907 | + <preamble> |
| 908 | + The first of these hyper-schemas describes an individual "thing", |
| 909 | + while the second describes a collection of "things". Note that the |
| 910 | + "targetSchema" of the individual thing's "self" link is the same |
| 911 | + as the "submissionSchema" of its "collection" link. |
| 912 | + </preamble> |
| 913 | + <artwork> |
| 914 | +<![CDATA[{ |
| 915 | + "$id": "http://example.com/schemas/thing", |
| 916 | + "type": "object", |
| 917 | + "properties": { |
| 918 | + "id": { |
| 919 | + "type": "integer", |
| 920 | + "readOnly": true |
| 921 | + } |
| 922 | + }, |
| 923 | + "links": [{ |
| 924 | + "rel": "self", |
| 925 | + "href": "/things/{id}", |
| 926 | + "targetSchema": {"$ref": "#"} |
| 927 | + }, { |
| 928 | + "rel": "collection", |
| 929 | + "href": "/things" |
| 930 | + "targetSchema": {"$ref": "thing-collection"} |
| 931 | + "submissionSchema": {"$ref": "#"} |
| 932 | + }] |
| 933 | +}]]> |
| 934 | + |
| 935 | +<![CDATA[{ |
| 936 | + "$id": "http://example.com/schemas/thing-collection", |
| 937 | + "type": "array", |
| 938 | + "items": { |
| 939 | + "allOf": [{"$ref": "thing"}] |
| 940 | + "links": [{ |
| 941 | + "anchorPointer": "", |
| 942 | + "rel": "item", |
| 943 | + "href": "/things/{id}", |
| 944 | + "targetSchema": {"$ref": "thing"} |
| 945 | + }] |
| 946 | + }, |
| 947 | + "links": [{ |
| 948 | + "rel": "self", |
| 949 | + "href": "/things", |
| 950 | + "targetSchema": {"$ref": "#"}, |
| 951 | + "submissionSchema": {"$ref": "thing"} |
| 952 | + }] |
| 953 | +}]]> |
| 954 | + </artwork> |
| 955 | + <postamble> |
| 956 | + In the hyper-schema for the collection, the "item" link also demonstrates |
| 957 | + the usage of "anchorPointer", as the context of that link must be the |
| 958 | + entire collection, rather than the individual array element to which the |
| 959 | + link is attached. The collection's self link also supports a |
| 960 | + "submissionSchema" matching that of its "item" link's "targetSchema". |
| 961 | + </postamble> |
| 962 | + </figure> |
| 963 | + </section> |
882 | 964 |
|
883 | 965 | <section title="Security Considerations for "self" links"> |
884 | 966 | <t> |
@@ -1584,6 +1666,7 @@ GET /foo/ |
1584 | 1666 | &rfc4151; |
1585 | 1667 | &rfc5789; |
1586 | 1668 | &rfc5988; |
| 1669 | + &rfc6573; |
1587 | 1670 | &rfc7231; |
1588 | 1671 | &rfc7240; |
1589 | 1672 | </references> |
|
0 commit comments