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]