Network Working Group C. Divilly Internet-Draft N. Mehta Intended status: Experimental Oracle Corp. Expires: January 2, 2010 July 1, 2009 Hierarchy Relations for Atom draft-divilly-atom-hierarchy-03 Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on January 2, 2010. Copyright Notice Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Abstract This specification defines link relations for hierarchical navigation among Atom feeds and entries. Divilly & Mehta Expires January 2, 2010 [Page 1] Internet-Draft Atom Hierarchy Relations July 2009 Editorial Note To provide feedback on this Internet-Draft, join the atom-syntax mailing list (http://www.imc.org/atom-syntax/) [1]. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Hierarchy link relations . . . . . . . . . . . . . . . . . . . 3 2.1. Modeling Hierarchy In Atom . . . . . . . . . . . . . . . . 3 2.2. The "down" Link . . . . . . . . . . . . . . . . . . . . . . 4 2.3. The "up" Link . . . . . . . . . . . . . . . . . . . . . . . 5 3. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 5. Normative References . . . . . . . . . . . . . . . . . . . . . 6 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 6 Appendix B. Revision History . . . . . . . . . . . . . . . . . . . 6 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 Divilly & Mehta Expires January 2, 2010 [Page 2] Internet-Draft Atom Hierarchy Relations July 2009 1. Introduction Many applications, besides blogs, provide their data in the form of syndicated Web feeds using formats such as Atom [RFC4287]. Some such applications organize Atom Entries in a hierarchical fashion similar to a file system. This specification describes a means of communicating about Atom Entries that are hierarchically related to each other since resource identifiers are opaque to clients and cannot be directly manipulated for the purposes of representation exchange, i.e., navigation. This specification proposes new link relations for hierarchically related Atom resources. 1.1. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 1.2. Terminology This specification uses Atom link relations to identify different types of links; see the Atom specification [RFC4287] for information about their syntax, and the IANA link relation registry for more information about specific values. 2. Hierarchy link relations A hierarchy exists when a resource indicates the likelihood of the existence of a parent and/or a child resource. The terms parent and child are indicative of the need for the former to exist before the latter can be created. 2.1. Modeling Hierarchy In Atom The Atom Syndication Format [RFC4287] defines the Atom Entry construct. The extensions in this specification define two specialized kinds of Entry construct -- parent Entry and child Entry. A parent Entry is a container for child Entries. A parent Entry could itself be a child of another parent Entry. Every Entry construct is represented as an Atom Entry Document [RFC4287] referred to in this specification as an "entry" and its plural. A logical Feed comprising entirely of child entries of a Divilly & Mehta Expires January 2, 2010 [Page 3] Internet-Draft Atom Hierarchy Relations July 2009 given Entry is called its child feed and one comprising entirely of its parent entries is called its parent feed. Both parent feed and child feed are seen from the perspective of a given Entry resource. The entries in the parent feed and child feed of an Entry SHOULD be disjoint, i.e., not share any entries. Applications MAY allow more than one parent Entry to contain a given child Entry. This is similar to hard links in filesystems. On the other hand, certain applications allow only a single parent Entry. A child Entry MAY use a logical Feed to represent multiple parent Entries. Alternatively, a child Entry MAY use multiple "up" atom: link elements, each to identify one of the parent Entries. Per section 4.1.1 of [RFC4287] if multiple atom:entry elements with the same atom:id value appear in a logical Feed, they represent the same entry. 2.2. The "down" Link An Atom link element with a rel attribute value of "down" may be used to reference a resource where child entries of an entry may be found. If the type attribute of the atom:link is omitted, its value is assumed to be "application/atom+xml". For example, Hanky Panky Portfolio ... Although Atom feed and entry elements MAY each contain any number of atom:link elements using the "down" link relation, this specification assigns no significance to the presence or order of such links. Multiple down links appearing within an atom:entry may reference alternative representations of the same set of children or may reference entirely distinct resources containing distinct sets of children. Processors MUST NOT assume that multiple down links are referencing different representations of the same resource and MUST process each down link independently of any others. The link element MAY contain an [RFC4685] thr:count element to indicate the number of entries in the down link, but as per section 6 Divilly & Mehta Expires January 2, 2010 [Page 4] Internet-Draft Atom Hierarchy Relations July 2009 of [RFC4685] this value is only an indication and may not be accurate. 2.3. The "up" Link An Atom link element with a rel attribute value of "up" may be used to reference a resource where parent entries of an entry or a feed may be found. If the type attribute of the atom:link is omitted, its value is assumed to be "application/atom+xml". For example, Positions in Hanky Panky ... Although Atom feed and entry elements MAY each contain any number of atom:link elements using the "up" link relation, this specification assigns no significance to the presence or order of such links. Multiple up links appearing within an atom:entry may reference alternative representations of the same set of parents or may reference entirely distinct resources containing distinct sets of parents. Processors MUST NOT assume that multiple up links are referencing different representations of the same resource and MUST process each up link independently of any others. The link element MAY contain an [RFC4685] thr:count element to indicate the number of entries in the up link, but as per section 6 of [RFC4685] this value is only an indication and may not be accurate. 3. Security Considerations Hierarchy Extensions for Atom is subject to the security considerations found in Section 8 of [RFC4287]. 4. IANA Considerations This specification uses the following relation that has been previously registered in the Link Relations Registry Divilly & Mehta Expires January 2, 2010 [Page 5] Internet-Draft Atom Hierarchy Relations July 2009 o Attribute Value: up o Description: A URI that refers to one or more parent resources in a hierarchy of resources. o Expected display characteristics: none o Security considerations: See this specification This specification defines the following new relations that have been added to the Link Relations registry: o Attribute Value: down o Description: A URI that refers to one or more child resources in a hierarchy of resources. o Expected display characteristics: none o Security considerations: See this specification 5. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom Syndication Format", RFC 4287, December 2005. [RFC4685] Snell, J., "Atom Threading Extensions", RFC 4685, September 2006. [1] Appendix A. Acknowledgements Bill de hOra and Ashish Motivala reviewed early drafts of this I-D. On the atom-syntax mailing list, Al Brown, Peter Keane, Julian Reschke, Mark Nottingham, Pablo Castro, Kyle Marvin, James Snell, Hadrien Gardeur, and Cornelia Davis provided very valuable feedback to improve the subsequent public drafts. Appendix B. Revision History 00 - Initial Revision. 00 - Based on feedback from Peter Keane, Julian Reschke, and members of the CMIS TC made the following changes: Divilly & Mehta Expires January 2, 2010 [Page 6] Internet-Draft Atom Hierarchy Relations July 2009 Renamed the link relation "detail" to "down" and "master" to "up" Removed Section 3, 4, 6, and 7 Changed namespace prefix from h to ah Added new link relations "up-tree" and "down-tree" 01 - Changes include: In-line representations of linked resources are independent of hierarchy Removed Atom specific language in link relation definitions Made explicit that this specification re-uses existing 'up' link relation Changed namespace prefix from ah to ae Removed the ah:count attribute and added the ae:inline element 02 - Changes include: In-line extensions moved to draft-mehta-atom-inline Removed down-tree and up-tree relations Removed cardinality restrictions on up and down links 03 - Changes include: Illustrate use of thr:count Fixed typo Remove references to rel="up" for atom:source elements Repeat RFC4287 rules for handling multiple entries with same atom:id Authors' Addresses Colm Divilly Oracle Corp. Email: colm.divilly@oracle.com URI: http://cdivilly.wordpress.com Nikunj R. Mehta Oracle Corp. Email: nikunj.mehta@oracle.com URI: http://o-micron.blogspot.com/ Divilly & Mehta Expires January 2, 2010 [Page 7]