idnits 2.17.1 draft-divilly-atom-hierarchy-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.ii or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. 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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 1, 2009) is 5410 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Unused Reference: 'RFC3986' is defined on line 229, but no explicit reference was found in the text Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Divilly 3 Internet-Draft N. Mehta 4 Intended status: Experimental Oracle Corp. 5 Expires: January 2, 2010 July 1, 2009 7 Hierarchy Relations for Atom 8 draft-divilly-atom-hierarchy-03 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on January 2, 2010. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 This specification defines link relations for hierarchical navigation 47 among Atom feeds and entries. 49 Editorial Note 51 To provide feedback on this Internet-Draft, join the atom-syntax 52 mailing list (http://www.imc.org/atom-syntax/) [1]. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Hierarchy link relations . . . . . . . . . . . . . . . . . . . 3 60 2.1. Modeling Hierarchy In Atom . . . . . . . . . . . . . . . . 3 61 2.2. The "down" Link . . . . . . . . . . . . . . . . . . . . . . 4 62 2.3. The "up" Link . . . . . . . . . . . . . . . . . . . . . . . 5 63 3. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 64 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 65 5. Normative References . . . . . . . . . . . . . . . . . . . . . 6 66 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 6 67 Appendix B. Revision History . . . . . . . . . . . . . . . . . . . 6 68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 70 1. Introduction 72 Many applications, besides blogs, provide their data in the form of 73 syndicated Web feeds using formats such as Atom [RFC4287]. Some such 74 applications organize Atom Entries in a hierarchical fashion similar 75 to a file system. 77 This specification describes a means of communicating about Atom 78 Entries that are hierarchically related to each other since resource 79 identifiers are opaque to clients and cannot be directly manipulated 80 for the purposes of representation exchange, i.e., navigation. 82 This specification proposes new link relations for hierarchically 83 related Atom resources. 85 1.1. Notational Conventions 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 89 document are to be interpreted as described in [RFC2119]. 91 1.2. Terminology 93 This specification uses Atom link relations to identify different 94 types of links; see the Atom specification [RFC4287] for information 95 about their syntax, and the IANA link relation registry for more 96 information about specific values. 98 2. Hierarchy link relations 100 A hierarchy exists when a resource indicates the likelihood of the 101 existence of a parent and/or a child resource. The terms parent and 102 child are indicative of the need for the former to exist before the 103 latter can be created. 105 2.1. Modeling Hierarchy In Atom 107 The Atom Syndication Format [RFC4287] defines the Atom Entry 108 construct. The extensions in this specification define two 109 specialized kinds of Entry construct -- parent Entry and child Entry. 111 A parent Entry is a container for child Entries. A parent Entry 112 could itself be a child of another parent Entry. 114 Every Entry construct is represented as an Atom Entry Document 115 [RFC4287] referred to in this specification as an "entry" and its 116 plural. A logical Feed comprising entirely of child entries of a 117 given Entry is called its child feed and one comprising entirely of 118 its parent entries is called its parent feed. Both parent feed and 119 child feed are seen from the perspective of a given Entry resource. 120 The entries in the parent feed and child feed of an Entry SHOULD be 121 disjoint, i.e., not share any entries. 123 Applications MAY allow more than one parent Entry to contain a given 124 child Entry. This is similar to hard links in filesystems. On the 125 other hand, certain applications allow only a single parent Entry. 127 A child Entry MAY use a logical Feed to represent multiple parent 128 Entries. Alternatively, a child Entry MAY use multiple "up" atom: 129 link elements, each to identify one of the parent Entries. 131 Per section 4.1.1 of [RFC4287] if multiple atom:entry elements with 132 the same atom:id value appear in a logical Feed, they represent the 133 same entry. 135 2.2. The "down" Link 137 An Atom link element with a rel attribute value of "down" may be used 138 to reference a resource where child entries of an entry may be found. 139 If the type attribute of the atom:link is omitted, its value is 140 assumed to be "application/atom+xml". 142 For example, 144 145 Hanky Panky Portfolio 146 148 150 ... 151 153 Although Atom feed and entry elements MAY each contain any number of 154 atom:link elements using the "down" link relation, this specification 155 assigns no significance to the presence or order of such links. 156 Multiple down links appearing within an atom:entry may reference 157 alternative representations of the same set of children or may 158 reference entirely distinct resources containing distinct sets of 159 children. Processors MUST NOT assume that multiple down links are 160 referencing different representations of the same resource and MUST 161 process each down link independently of any others. 163 The link element MAY contain an [RFC4685] thr:count element to 164 indicate the number of entries in the down link, but as per section 6 165 of [RFC4685] this value is only an indication and may not be 166 accurate. 168 2.3. The "up" Link 170 An Atom link element with a rel attribute value of "up" may be used 171 to reference a resource where parent entries of an entry or a feed 172 may be found. If the type attribute of the atom:link is omitted, its 173 value is assumed to be "application/atom+xml". 175 For example, 177 178 Positions in Hanky Panky 179 181 183 ... 184 186 Although Atom feed and entry elements MAY each contain any number of 187 atom:link elements using the "up" link relation, this specification 188 assigns no significance to the presence or order of such links. 189 Multiple up links appearing within an atom:entry may reference 190 alternative representations of the same set of parents or may 191 reference entirely distinct resources containing distinct sets of 192 parents. Processors MUST NOT assume that multiple up links are 193 referencing different representations of the same resource and MUST 194 process each up link independently of any others. 196 The link element MAY contain an [RFC4685] thr:count element to 197 indicate the number of entries in the up link, but as per section 6 198 of [RFC4685] this value is only an indication and may not be 199 accurate. 201 3. Security Considerations 203 Hierarchy Extensions for Atom is subject to the security 204 considerations found in Section 8 of [RFC4287]. 206 4. IANA Considerations 208 This specification uses the following relation that has been 209 previously registered in the Link Relations Registry 210 o Attribute Value: up 211 o Description: A URI that refers to one or more parent resources in 212 a hierarchy of resources. 213 o Expected display characteristics: none 214 o Security considerations: See this specification 216 This specification defines the following new relations that have been 217 added to the Link Relations registry: 218 o Attribute Value: down 219 o Description: A URI that refers to one or more child resources in a 220 hierarchy of resources. 221 o Expected display characteristics: none 222 o Security considerations: See this specification 224 5. Normative References 226 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 227 Requirement Levels", BCP 14, RFC 2119, March 1997. 229 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 230 Resource Identifier (URI): Generic Syntax", STD 66, 231 RFC 3986, January 2005. 233 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 234 Syndication Format", RFC 4287, December 2005. 236 [RFC4685] Snell, J., "Atom Threading Extensions", RFC 4685, 237 September 2006. 239 [1] 241 Appendix A. Acknowledgements 243 Bill de hOra and Ashish Motivala reviewed early drafts of this I-D. 244 On the atom-syntax mailing list, Al Brown, Peter Keane, Julian 245 Reschke, Mark Nottingham, Pablo Castro, Kyle Marvin, James Snell, 246 Hadrien Gardeur, and Cornelia Davis provided very valuable feedback 247 to improve the subsequent public drafts. 249 Appendix B. Revision History 251 00 - Initial Revision. 253 00 - Based on feedback from Peter Keane, Julian Reschke, and members 254 of the CMIS TC made the following changes: 256 Renamed the link relation "detail" to "down" and "master" to "up" 257 Removed Section 3, 4, 6, and 7 258 Changed namespace prefix from h to ah 259 Added new link relations "up-tree" and "down-tree" 261 01 - Changes include: 262 In-line representations of linked resources are independent of 263 hierarchy 264 Removed Atom specific language in link relation definitions 265 Made explicit that this specification re-uses existing 'up' link 266 relation 267 Changed namespace prefix from ah to ae 268 Removed the ah:count attribute and added the ae:inline element 270 02 - Changes include: 271 In-line extensions moved to draft-mehta-atom-inline 272 Removed down-tree and up-tree relations 273 Removed cardinality restrictions on up and down links 275 03 - Changes include: 276 Illustrate use of thr:count 277 Fixed typo 278 Remove references to rel="up" for atom:source elements 279 Repeat RFC4287 rules for handling multiple entries with same 280 atom:id 282 Authors' Addresses 284 Colm Divilly 285 Oracle Corp. 287 Email: colm.divilly@oracle.com 288 URI: http://cdivilly.wordpress.com 290 Nikunj R. Mehta 291 Oracle Corp. 293 Email: nikunj.mehta@oracle.com 294 URI: http://o-micron.blogspot.com/