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,

   <entry xmlns="http://www.w3.org/2005/Atom">
     <title type="text">Hanky Panky Portfolio</title>
     <link rel="down" type="application/atom+xml;type=feed"
       href="/portfolios/1/positions/"/>
     <link rel="down" type="text/html"
       href="/portfolios/1;listing"/>
     ...
   </entry>

   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,

   <feed xmlns="http://www.w3.org/2005/Atom">
     <title type="text">Positions in Hanky Panky</title>
     <link rel="self"
       href="/portfoloios/1/positions/"/>
     <link rel="up"
       href="/portfolios/1"/>
     ...
   </feed>

   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]  <http://www.imc.org/atom-syntax/>


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]