idnits 2.17.1 draft-amundsen-item-and-collection-link-relations-05.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 5, 2012) is 4463 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Amundsen 3 Internet-Draft February 5, 2012 4 Intended status: Informational 5 Expires: August 8, 2012 7 The Item and Collection Link Relations 8 draft-amundsen-item-and-collection-link-relations-05 10 Abstract 12 RFC 5988 standardized a means of indicating the relationships between 13 resources on the Web. This specification defines a pair of reciprocal 14 link relation types that may be used to express the relationship 15 between a collection and its members. 17 Editorial Note (To be removed by RFC Editor) 19 Distribution of this document is unlimited. Comments should be sent 20 to the IETF Apps-Discuss mailing list (see 21 ). 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on August 8, 2012. 40 Copyright Notice 42 Copyright (c) 2012 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 1. Introduction 57 RFC 5988 standardized a means of indicating the relationships between 58 resources on the Web. This specification defines a pair of reciprocal 59 link relation types that may be used to express the relationship 60 between a collection and its members. 62 These link relation types can be applied to a wide range of use cases 63 across multiple media types. For example, the 'collection' and 64 'item' link relation types are used in these media types: 66 1. OpenSearch 1.1: see Section 4.5.4.1 of [OpenSearch] 68 2. Maze+XML: see Section 3 of [Maze] 70 3. Collection+JSON: see Section 5 of [CollectionJSON] 72 2. Link Relations 74 The following link relations are defined. 76 2.1. 'item' 78 When included in a resource which represents a collection, the 'item' 79 link relation identifies a target resource that represents a member 80 of that collection. 82 For example, if a resource represents a catalog of products, that 83 same representation may include one or more links to resources which 84 represent members of that catalog. 86 87 ... 88

Product Group X Listing

89 ... 90 View Product X001 91 View Product X002 92 ... 93 95 or, in the case of a Link Header field 96 Link: <...>; rel="item"; title="View Product X001" 97 Link: <...>; rel="item"; title="View Product X002" 99 2.2. 'collection' 101 When included in a resource which represents a member of a 102 collection, the 'collection' link relation identifies a target 103 resource that represents a collection of which the context resource 104 is a member. 106 For example, if a resource represents a single product in a catalog, 107 that same representation may include a link to a resource which 108 represents a product group to which this single product belongs: 110 Return to Product Group X 112 or, in the case of a Link Header field 114 Link: <...>; rel="collection"; title="Return to Product Group X" 116 Since it is possible that a resource could be a member of multiple 117 collections, multiple 'collection' link relations may appear within 118 the same representation: 120 View other widgets 121 View all discontinued items 123 The target resource representation need not be restricted to 124 representing a list. It may simply be a document that provides 125 details on the collection of which the context resource is a member: 127 Link: <...>; rel="collection"; 128 title="Shakespeare's Collected Works - A History" 130 It should also be noted that that same link might represent an 'item' 131 in one collection as well as a 'collection' itself. In this case 132 both Link Relation values can be applied to the same link: 134 Link: <...>; rel="collection item"; 135 title="A Review of Issac Asimov's Collected Works - Vol. I" 137 3. IANA Considerations 139 IANA is asked to register the 'collection' and 'item' Link Relations 140 below as per [RFC5988]. 142 3.1. 'item' Link Relation Registration 144 Relation Name: 146 item 148 Description: 150 The target IRI points to a resource that is a member of the 151 collection represented by the context IRI. 153 Reference: 155 See Section 2 157 3.2. 'collection' Link Relation Registration 159 Relation Name: 161 collection 163 Description: 165 The target IRI points to a resource which represents a collection 166 of which the context IRI is a member. 168 Reference: 170 See Section 2 172 4. Security Considerations 174 The two link relation types defined in this document do not introduce 175 any new security issues to those which are discussed in Section 7 of 176 RFC5988 [RFC5988]. 178 5. Internationalisation Considerations 180 The 'item' and 'collection' link relation types do not have any 181 internationalization considerations other than those which are 182 discussed in Section 8 of RFC5988 [RFC5988]. 184 6. References 186 6.1. Normative References 188 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 189 October 2010. 191 6.2. Informative References 193 [OpenSearch] Clinton, D., "Open Search 1.1", Work in Progress , 194 March 2011, . 197 [Maze] Amundsen, M., "Maze+XML - Format", Web Page , 198 December 2010, 199 . 201 [CollectionJSON] Amundsen, M., "Collection+JSON - Document Format", 202 Web Page , July 2011, . 205 Appendix A. Acknowledgements 207 The author gratefully acknowledges the contributions of Julian 208 Reschke and Mykyta Yevstifeyev. 210 Author's Address 212 Mike Amundsen 214 EMail: mca@amundsen.com 215 URI: http://amundsen.com