One document matched: draft-divilly-atom-hierarchy-00.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
	<!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
	<!ENTITY rfc3986 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>
	<!ENTITY rfc4287 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4287.xml'>
	<!ENTITY W3C.REC-xmlbase-20010627 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xmlbase-20010627.xml'>
]>
<!--<?xml-stylesheet type='text/xsl' href='rfc2629.xslt'/ ?>-->
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="yes" ?>
<?rfc strict="yes" ?>
<?rfc compact="yes" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes" ?>
<?rfc tocdepth="3" ?>
<rfc category="exp" ipr="trust200811" docName="draft-divilly-atom-hierarchy-00">
	<front>
		<title abbrev="Atom Hierarchy Extensions">Hierarchy Extensions for Atom</title>
		<author initials="C." surname="Divilly" fullname="Colm Divilly">
			<organization>Oracle Corp.</organization>
			<address>
				<email>colm.divilly@oracle.com</email>
				<uri>http://cdivilly.wordpress.com</uri>
			</address>
		</author>
		<author initials="N. R." surname="Mehta" fullname="Nikunj R. Mehta">
			<organization>Oracle Corp.</organization>
			<address>
				<email>nikunj.mehta@oracle.com</email>
				<uri>http://o-micron.blogspot.com/</uri>
			</address>
		</author>
		<date day="20" month="May" year="2009"/>
		<abstract>
			<t>
			This specification defines mechanisms for hierarchical navigation
      among Atom feeds and entries.
 			</t>
		</abstract>
		<note title="Editorial Note">
			<t>
			To provide feedback on this Internet-Draft, join the
			<eref target="http://www.imc.org/atom-syntax/">atom-syntax mailing
			list (http://www.imc.org/atom-syntax/)</eref>.
			</t>
		</note>
	</front>
	<middle>
		<section anchor="intro" title="Introduction">
			<t>
			Many applications, besides blogs, provide their data in the form of 
      syndicated Web feeds using formats such as Atom <xref target="RFC4287"/>. 
      Some such applications organize Atom Entries in a hierarchical fashion
      similar to a file system. 
      </t>
      <t>
      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.  
 	    </t>
			<t>
			This specification proposes new XML markup to extend the Atom Syndication Format and new
      link relations to obtain representations of hierarchically related Atom resources.
			</t>
			<section title="Namespace">
				<t> The XML Namespaces URI for the XML data format described in this specification is: </t>
				<figure width="" align="left" height="" alt="" title="">
					<artwork name="" align="left" height="" width="" alt="" type="" xml:space="preserve">
    http://purl.org/atom/hierarchy/</artwork>
				</figure>
				<t> This specification uses the prefix "ah:" for the namespace name.  The
       prefix "atom:" is used for "http://www.w3.org/2005/Atom", the namespace name of
       the Atom Syndication Format <xref target="RFC4287" pageno="false" format="default"/>.
       These namespace prefixes are not semantically significant.
       </t>
			</section>
			<section title="Notational Conventions">
				<t>
				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 <xref target="RFC2119"/>.
				</t>
			</section>
      <section title="Terminology" anchor="terminology">
        <t>
          This specification uses Atom link relations to identify different
          types of links; see the Atom specification <xref target="RFC4287"/> for
          information about their syntax, and the IANA link relation registry
          for more information about specific values.
         </t>
       </section>
		</section>
		<section title="Hierarchy Model" anchor="hierarchy-model">
			<t>
			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.
			</t>
			<section title="Entry Classification" anchor="entry-classification">
				<t>
				The Atom Syndication Format <xref target="RFC4287"/> defines the Atom Entry construct. 
				The extensions in this specification define two specialized kinds of Entry construct --
				parent Entry and child Entry. 
        </t>
				<t>
				A parent Entry is a container for child Entries. A parent Entry 
        could itself be a child of another parent Entry.
				</t>
        <t>Every Entry construct is represented as an Atom Entry Document <xref target="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.
				</t>
				<figure>
					<preamble>
					A parent entry contains a "down" atom:link for its child feed. A parent 
          entry may also contain a "down-tree" atom:link for a child feed of a subset 
          of the descendants of that parent Entry.
					</preamble>
					<artwork name="Parent entry contents"><![CDATA[
   atom:entry
        |
        o- atom:link@rel="down" (1..1)
        o- atom:link@rel="down-tree" (0..1)
]]></artwork>
				</figure>
				<figure>
					<preamble>
					A child entry contains an "up" atom:link for its parent feed or
          entry if the child only allows a single parent. A child entry may also 
          contain an "up-tree" atom:link for a parent feed of a subset of the 
          ascendants of that child Entry.
					</preamble>
					<artwork name="Child entry"><![CDATA[
   atom:feed
        |
        o- atom:link@rel="up" (1..1)
        o- atom:link@rel="up-tree" (0..1)
]]></artwork>
				</figure>
			</section>
      <section title="Entry parent representation" anchor="parent-representation">
        <t>
        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.
        </t>
        <t>
        A child Entry MUST use a logical Feed to represent multiple parent
        Entries. This implies use of a feed for the URI <xref target="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.
        </t>
      </section>
    </section>
		<section title="Inline Representation of Hierarchical Resources" anchor="inline-representation">
			<t>
			A parent or child feed or a parent entry MAY be inlined in an entry. 
      Clients SHOULD NOT assume that the inline representations are identical 
      to the one available from the linked URI. Clients SHOULD use URI identified 
      by the relevant link relation to obtain its complete representation.
			</t>
			<section title="Representation of Linked Resources" anchor="hierarchy-representation">
				<t>
				An entry references parent and child Entries via various links. 
        The representation of a hierarchically linked resource can be provided
        in the following ways:
					<list style="numbers">
						<t>
						Out-of-line reference: The Atom Processor can retrieve the representation by 
						following the URI specified in the link element.
						</t>
						<t>
						Inline content with out-of-line reference: The Atom Processor can use
						the content specified inside the link element as an approximation of 
            the server representation as detailed below. The embedded
            representation is only a hint and MAY differ from the representation
            obtained from the URI referenced in the link. 
						</t>
					</list>
				</t>
				
          <section title="The "ah:count" Extension Attribute" anchor="count-attribute">
            <t>
            On the atom:link element, the value of the "ah:count" attribute MAY 
            be a non-negative integral value identifying an approximate count 
            of the number of entries in the inlined feed document. If the 
            inlined representation or the type identified in the atom:link is 
            the Atom Entry content type, i.e., application/atom+xml;type=entry, 
            then this attribute MUST NOT be used.
            </t>
          </section>
      </section>
			<section title="Child and descendant feeds" anchor="child-feeds">
				<section title="The "down" Link" anchor="down-link">
					<t>
					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.
					</t>
				</section>
				<section title="The "down-tree" Link" anchor="down-tree-link">
					<t>
					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.
					</t>
				</section>
				<section title="Examples" anchor="down-examples">
					<figure>
						<preamble>
						Example: Entry with out-of-line reference to child feed
						</preamble>
						<artwork name="Out-of-line child feed" type="example"><![CDATA[
<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" ah:count="0"/>
  ...
</atom:entry>
 ]]></artwork>
					</figure>
					<figure>
						<preamble>
						Example: Parent entry representation with inline child feed 
						</preamble>
						<artwork name="Inline child feed" type="example"><![CDATA[
<atom:entry>
  <atom:link rel="down"
    href="/finance/feeds/default/portfolios/1/positions">
    <atom:feed>
      <atom:link rel="self" 
       href="/finance/feeds/default/portfolios/1/positions"/>
       ...
    </atom:feed>
  </atom:link>
  ...
</atom:entry>
	 ]]></artwork>
					</figure>
					<figure>
						<preamble>
						Example: Entry with out-of-line reference to descendant feed
						</preamble>
						<artwork name="Out-of-line descendant feed" type="example"><![CDATA[
<atom:entry>
  <atom:link rel="down-tree"
    href="/finance/feeds/default/portfolios/"/>
  ...
</atom:entry>
	 ]]></artwork>
					</figure>
				</section>
			</section>
			<section title="Parent Entries and Parent and Ascendant Feeds" anchor="parent-entries">
				<section title="The "up" Link" anchor="up-link">
					<t>
					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.
					</t>
          <t>
          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.
          </t>
				</section>
				<section title="The "up-tree" Link" anchor="up-tree-link">
					<t>
					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.
					</t>
				</section>
				<section title="Examples" anchor="parent-examples">
					<figure>
						<preamble>
						Example: Child Entry with inline multiple parent Entries
						</preamble>
						<artwork name="Inline parents feed" type="example"><![CDATA[
<atom:entry>
  <atom:title type="text">Position for NASDAQ:ORCL</atom:title>
  <atom:link rel="up"
    href="/finance/feeds/default/positions/NASDAQ:ORCL/up">
    <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>
    </atom:feed>
  </atom:link>
  ...
</atom:entry>
	 ]]></artwork>
					</figure>
					<figure>
						<preamble>
						Example: Child feed with out-of-line reference to parent Entry
						</preamble>
						<artwork name="Out-of-line parent entry" type="example"><![CDATA[
<atom:feed>
  <atom:title type="text">Positions</atom:title>
  <atom:link rel="up"
    href="/finance/feeds/default/portfolios/1" ah:count="2"/>
  ...
</atom:feed>
 ]]></artwork>
					</figure>
					<figure>
						<preamble>
						Example: Entry with out-of-line reference to ascendant feed
						</preamble>
						<artwork name="Out-of-line ascendant feed" type="example"><![CDATA[
<atom:entry>
  <atom:link rel="up-tree"
    href="/finance/feeds/default/portfolios/1/positions"/>
  ...
</atom:entry>
	 ]]></artwork>
					</figure>
				</section>
			</section>
			</section>
		<section title="Security Considerations">
			<t>
			Hierarchy Extensions for Atom is subject to the 
			security considerations found in Section 8 of <xref target="RFC4287"/>.
			</t>
      <t>
      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.
      </t>
		</section>
		<section title="IANA Considerations" anchor="iana">
			<t>
		    This specification defines the following new relations that have been
		    added to the Link Relations registry:
				<list style="symbols">
					<t>Attribute Value: down</t>
					<t>Description: A URI that refers to a feed of child entries in a hierarchy 
          of Atom Entry resources.</t>
					<t>Expected display characteristics: none</t>
					<t>Security considerations: See this draft</t>
				</list>
				<list style="symbols">
					<t>Attribute Value: down-tree</t>
					<t>Description: A URI that refers to the feed of descendant entries in a 
          hierarchy of Atom Entry resources.</t>
					<t>Expected display characteristics: none</t>
					<t>Security considerations: See this draft</t>
				</list>
				<list style="symbols">
					<t>Attribute Value: up</t>
					<t>Description: A URI that refers to one or more parent entry resources
          in a hierarchy of Atom Entry resources.</t>
					<t>Expected display characteristics: none</t>
					<t>Security considerations: See this draft</t>
				</list>
				<list style="symbols">
					<t>Attribute Value: up-tree</t>
					<t>Description: A URI that refers to the feed of ascendant entries 
          in a hierarchy of Atom Entry resources.</t>
					<t>Expected display characteristics: none</t>
					<t>Security considerations: See this draft</t>
				</list>
			</t>
		</section>
	</middle>
	<back>
		<references title="Normative References">
		   &rfc2119;
		   &rfc3986;
		   &rfc4287;
		   &W3C.REC-xmlbase-20010627;
    </references>
    <section title="Acknowledgements">
			<t>
			Bill de hÓra and Ashish Motivala reviewed early drafts of this I-D.
			</t>
		</section>
		<section title="Revision History">
			<t>
			00 - Initial Revision.
      </t>
			<t>
			01 - Based on feedback from Peter Keane, Julian Reschke, and members of the CMIS TC made the following changes:
        <list style="hanging">
          <t>Renamed the link relation "detail" to "down" and "master" to "up"</t>
          <t>Removed Section 3, 4, 6, and 7</t>
          <t>Changed namespace prefix from h to ah</t>
          <t>Added new link relations "up-tree" and "down-tree"</t>
        </list>
      </t>
		</section>
	</back>
</rfc>