One document matched: draft-divilly-atom-hierarchy-01.txt
Differences from draft-divilly-atom-hierarchy-00.txt
Network Working Group C. Divilly
Internet-Draft N. Mehta
Intended status: Experimental Oracle Corp.
Expires: December 7, 2009 June 5, 2009
Inlining and Hierarchy Extensions for Atom
draft-divilly-atom-hierarchy-01
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 December 7, 2009.
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 mechanisms for in-lining representations
of linked resources and for hierarchical navigation among Atom feeds
and entries.
Divilly & Mehta Expires December 7, 2009 [Page 1]
Internet-Draft Atom Hierarchy Extensions June 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. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 3
1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Hierarchy Model . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Entry Classification . . . . . . . . . . . . . . . . . . . 4
2.2. Entry Parent Representation . . . . . . . . . . . . . . . 5
3. Inline Representation of Resources . . . . . . . . . . . . . . 5
3.1. Representation of Linked Resources . . . . . . . . . . . . 5
3.2. The "ae:inline" Extension Element . . . . . . . . . . . . 5
4. Child and Descendant Feeds . . . . . . . . . . . . . . . . . . 6
4.1. The "down" Link . . . . . . . . . . . . . . . . . . . . . 6
4.2. The "down-tree" Link . . . . . . . . . . . . . . . . . . . 6
4.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7
5. Parent Entries and Parent and Ascendant Feeds . . . . . . . . 7
5.1. The "up" Link . . . . . . . . . . . . . . . . . . . . . . 7
5.2. The "up-tree" Link . . . . . . . . . . . . . . . . . . . . 8
5.3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8
6. Security Considerations . . . . . . . . . . . . . . . . . . . 9
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
8. Normative References . . . . . . . . . . . . . . . . . . . . . 10
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10
Appendix B. Revision History . . . . . . . . . . . . . . . . . . 10
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11
Divilly & Mehta Expires December 7, 2009 [Page 2]
Internet-Draft Atom Hierarchy Extensions June 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 XML markup to in-line representations
of linked resources and new link relations for hierarchically related
Atom resources.
1.1. Namespace
The XML Namespaces URI for the XML data format described in this
specification is:
http://purl.org/atom/ext/
This specification uses the prefix "ae:" for the namespace name. The
prefix "atom:" is used for "http://www.w3.org/2005/Atom", the
namespace name of the Atom Syndication Format [RFC4287]. These
namespace prefixes are not semantically significant.
1.2. Notational Conventions
Some sections of this specification are illustrated with fragments of
a non-normative RELAX NG Compact schema [RELAX-NG]. In those
sections, this specification uses the atomCommonAttributes and
anyElement, defined in [RFC4287].
However, the text of this specification provides the definition of
conformance.
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.3. 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.
Divilly & Mehta Expires December 7, 2009 [Page 3]
Internet-Draft Atom Hierarchy Extensions June 2009
2. Hierarchy Model
A hierarchy exists when a resource indicates the likelihood 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. Entry Classification
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
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.
A parent entry contains one or more "down" atom:link for its child
feed. A parent entry may also contain one or more "down-tree" atom:
link for a child feed of a subset of the descendants of that parent
Entry.
atom:entry
|
o- atom:link@rel="down"
A child entry contains one or more "up" atom:link for its parent feed
or entry if the child only allows a single parent. A child entry may
also contain one or more "up-tree" atom:link for a parent feed of a
subset of the ascendants of that child Entry.
atom:entry
|
o- atom:link@rel="up"
Divilly & Mehta Expires December 7, 2009 [Page 4]
Internet-Draft Atom Hierarchy Extensions June 2009
A child feed may contain one or more "up" atom:link for its parent
Entry.
atom:feed
|
o- atom:link@rel="up"
2.2. Entry Parent Representation
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 MUST use a logical Feed to represent multiple parent
Entries. This implies use of a feed for the URI [RFC3986] identified
as the child Entry's "up" link. A child Entry MAY use an entry for
the URI identified as the child Entry's "up" link if it does not
allow multiple parents for that child Entry. Clients SHOULD be
prepared to inspect the representation received for the "up" link of
a child Entry before assuming either cardinality models.
3. Inline Representation of Resources
A resource is linked from an Atom document using the atom:link
element [RFC4287]. The representation of the linked resource MAY be
in-lined in the referring Atom document to reduce network usage.
3.1. Representation of Linked Resources
The href of atom:link element identifies a resource linked from Atom
documents. An Atom Processor can obtain the representation of a
linked resource using its identifier. This specification defines an
alternate mechanism in cases where the linked resource can be
represented directly inside the referring Atom document.
An Atom document may include the in-line representation of a linked
resource by using the ae:inline element inside the corresponding
atom:link element. The in-lined representation is only a hint and
MAY differ from the representation obtained from the URI referenced
in the link. Atom Processors SHOULD use the link URI to obtain the
complete representation of the linked resource.
3.2. The "ae:inline" Extension Element
The in-line representation of a linked resource may contain XML or
text content similar to atom:content [RFC4287].
Divilly & Mehta Expires December 7, 2009 [Page 5]
Internet-Draft Atom Hierarchy Extensions June 2009
extensionInline =
element ae:inline {
atomCommonAttributes,
inlineRepresentation
}
inlineRepresentation =
text | anyElement
In-line representation of linked resource is analogous to the in-line
representation of an entry's content. In this sense, atom:content
and atom:link behave similarly in the presence of in-line extensions.
Atom processors conforming to this specification MUST, therefore,
process the value of ae:inline per the processing model for atom:
content as specified in Section 4.1.3.3 of [RFC4287].
Additionally, even though the type attribute is optional in atom:link
elements, conforming generators that in-line linked resources MUST
specify a value for the type attribute in the corresponding atom:link
element. The value of the ae:inline element, i.e., the inline
representation MUST conform to the MIME media type specified in the
type attribute of the atom:link element that holds the ae:inline
element.
4. Child and Descendant Feeds
4.1. The "down" Link
A parent entry MUST contain an atom:link element with link relation
of "down" to indicate the child Feed URI. The type attribute of this
link element (if present), MUST be the Atom Feed content type, i.e.,
application/atom+xml;type=feed. An entry MUST NOT contain more than
one atom:link element with a rel attribute value of "down" that has
the same combination of type and hreflang attribute values.
4.2. The "down-tree" Link
A parent entry MAY contain an atom:link element with link relation of
"down-tree" to indicate the URI of a feed of descendant Entry
resources. The type attribute of this link element (if present),
MUST be the Atom Feed content type, i.e., application/
atom+xml;type=feed. This specification does not prescribe any means
of limiting the depth to which descendants are available. An entry
MUST NOT contain more than one atom:link element with a rel attribute
value of "down-tree" that has the same combination of type and
hreflang attribute values.
Divilly & Mehta Expires December 7, 2009 [Page 6]
Internet-Draft Atom Hierarchy Extensions June 2009
4.3. Examples
Example: Entry with out-of-line reference to child feed
<atom:entry>
<atom:title type="text">My Portfolio</atom:title>
<atom:link rel="down" type="application/atom+xml;type=feed"
href="/finance/feeds/default/portfolios/1/positions/"/>
<atom:link rel="down" type="text/html"
href="/finance/feeds/default/portfolios/1/positions"/>
...
</atom:entry>
Example: Parent entry representation with inline child feed
<atom:entry>
<atom:link rel="down" type="application/atom+xml;type=feed"
href="/finance/feeds/default/portfolios/1/positions">
<ae:inline>
<atom:feed>
<atom:link rel="self"
href="/finance/feeds/default/portfolios/1/positions"/>
...
</atom:feed>
</ae:inline>
</atom:link>
...
</atom:entry>
Example: Entry with out-of-line reference to descendant feed
<atom:entry>
<atom:link rel="down-tree"
href="/finance/feeds/default/portfolios/"/>
...
</atom:entry>
5. Parent Entries and Parent and Ascendant Feeds
5.1. The "up" Link
Child Entries identify the URIs of their parent Entry or multiple
parent Entry resources in their own metadata. A child entry MUST
contain an atom:link element with link relation of "up" to indicate
the parent Entry URI. If the type attribute of this link is present,
it MUST be an Atom content type. An entry MUST NOT contain more than
one atom:link element with a rel attribute value of "up" that has the
Divilly & Mehta Expires December 7, 2009 [Page 7]
Internet-Draft Atom Hierarchy Extensions June 2009
same combination of type and hreflang attribute values.
A child feed MUST identify the URI of the parent Entry represented in
the feed using the "up" link. This allows navigation back and forth
between the parent Entry and the child feed. This is in addition to
the "up" link present in individual child entries. A feed MUST NOT
contain more than one atom:link element with a rel attribute value of
"up" that has the same combination of type and hreflang attribute
values.
5.2. The "up-tree" Link
A child entry MAY contain an atom:link element with link relation of
"up-tree" to indicate the URI of a feed of ascendant Entry resources.
The type attribute of this link element (if present), MUST be the
Atom Feed content type, i.e., application/atom+xml;type=feed. This
specification does not prescribe any means of limiting the height to
which ascendants are available. An entry MUST NOT contain more than
one atom:link element with a rel attribute value of "up-tree" that
has the same combination of type and hreflang attribute values.
5.3. Examples
Example: Child Entry with inline multiple parent Entries
<atom:entry>
<atom:title type="text">Position for NASDAQ:ORCL</atom:title>
<atom:link rel="up" type="application/atom+xml;type=feed"
href="/finance/feeds/default/positions/NASDAQ:ORCL/up">
<ae:inline>
<atom:feed>
...
<atom:entry>
<atom:link rel="self"
href="/finance/feeds/default/portfolios/1"/>
...
</atom:entry>
<atom:entry>
<atom:link rel="self"
href="/finance/feeds/default/portfolios/2"/>
...
</atom:entry>
</ae:inline>
</atom:feed>
</atom:link>
...
</atom:entry>
Divilly & Mehta Expires December 7, 2009 [Page 8]
Internet-Draft Atom Hierarchy Extensions June 2009
Example: Child feed with out-of-line reference to parent Entry
<atom:feed>
<atom:title type="text">Positions</atom:title>
<atom:link rel="up"
href="/finance/feeds/default/portfolios/1"/>
...
</atom:feed>
Example: Entry with out-of-line reference to ascendant feed
<atom:entry>
<atom:link rel="up-tree"
href="/finance/feeds/default/portfolios/1/positions"/>
...
</atom:entry>
6. Security Considerations
Hierarchy Extensions for Atom is subject to the security
considerations found in Section 8 of [RFC4287].
The down-tree relation can overwhelm a server if reasonable limits
are not placed on the depth to which hierarchy can be navigated. For
this reason, applications are advised to either restrict this
relation's usage to out-of-line content or apply reasonable limits on
inline representation.
7. IANA Considerations
This specification uses the following relation that has been
previously registered in the Link Relations Registry
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
Divilly & Mehta Expires December 7, 2009 [Page 9]
Internet-Draft Atom Hierarchy Extensions June 2009
o Security considerations: See this specification
o Attribute Value: down-tree
o Description: A URI that refers to the set of descendant resources
in a hierarchy of resources.
o Expected display characteristics: none
o Security considerations: See this specification
o Attribute Value: up-tree
o Description: A URI that refers to the set of ascendant resources
in a hierarchy of resources.
o Expected display characteristics: none
o Security considerations: See this specification
8. 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.
[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, Julian Reschke, Mark
Nottingham, Pablo Castro, and Kyle Marvin 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:
Renamed the link relation "detail" to "down" and "master" to "up"
Removed Section 3, 4, 6, and 7
Divilly & Mehta Expires December 7, 2009 [Page 10]
Internet-Draft Atom Hierarchy Extensions June 2009
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
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 December 7, 2009 [Page 11]
| PAFTECH AB 2003-2026 | 2026-04-24 10:25:07 |