One document matched: draft-divilly-atom-hierarchy-01.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'>
]>
<!--<?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-01">
	<front>
		<title abbrev="Atom Hierarchy Extensions">Inlining and 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="5" month="June" year="2009"/>
		<abstract>
			<t>
			This specification defines mechanisms for in-lining representations of
      linked resources and 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 in-line representations of
      linked resources and new link relations for 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/ext/</artwork>
				</figure>
				<t> 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 <xref target="RFC4287" pageno="false" format="default"/>.
       These namespace prefixes are not semantically significant.
       </t>
			</section>
			<section title="Notational Conventions">
        <t>
        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].
        </t>
        <t>
        However, the text of this specification provides the definition of conformance.  
        </t>
				<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 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.
					</preamble>
					<artwork name="Parent entry contents"><![CDATA[
   atom:entry
        |
        o- atom:link@rel="down"
]]></artwork>
				</figure>
				<figure>
					<preamble>
					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. 
					</preamble>
					<artwork name="Child entry"><![CDATA[
   atom:entry
        |
        o- atom:link@rel="up"
]]></artwork>
				</figure>
				<figure>
					<preamble>
					A child feed may contain one or more "up" atom:link for its parent Entry.
					</preamble>
					<artwork name="Child entry"><![CDATA[
   atom:feed
        |
        o- atom:link@rel="up"
]]></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 Resources" anchor="inline-representation">
			<t>
			A resource is linked from an Atom document using the atom:link element <xref target="RFC4287"/>. The 
      representation of the linked resource MAY be in-lined in the referring Atom document to
      reduce network usage. 
			</t>
			<section title="Representation of Linked Resources" anchor="hierarchy-representation">
				<t>
				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. 
        </t>
				<t>
        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.
				</t>
      </section>
				
      <section title="The "ae:inline" Extension Element" anchor="inline-element">
        <t>
        The in-line representation of a linked resource may contain XML or text content 
        similar to atom:content <xref target="RFC4287"/>. 
        </t>
				<figure>
					<preamble/>
					<artwork name="inline-definition" type="definition"><![CDATA[
extensionInline = 
   element ae:inline {
     atomCommonAttributes,
     inlineRepresentation
   }
   
inlineRepresentation =
   text | anyElement
 ]]></artwork>
        </figure>
        <t>
        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 <xref target="RFC4287" pageno="false" format="default"/>. 
        </t>
        <t>
        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. 
        </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. 
        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.
				</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. 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.
				</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/"/>
  <atom:link rel="down" type="text/html"
    href="/finance/feeds/default/portfolios/1/positions"/>
  ...
</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" 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>
	 ]]></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. An entry 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.
				</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. 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.
        </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. 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.
				</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" 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>
	 ]]></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"/>
  ...
</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 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 uses the following relation that has been previously 
		    registered in the Link Relations Registry
				<list style="symbols">
					<t>Attribute Value: up</t>
					<t>Description: A URI that refers to one or more parent resources
          in a hierarchy of resources.</t>
					<t>Expected display characteristics: none</t>
					<t>Security considerations: See this specification</t>
				</list>		    
		    </t>
			<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 one or more child resources in a hierarchy 
          of resources.</t>
					<t>Expected display characteristics: none</t>
					<t>Security considerations: See this specification</t>
				</list>
				<list style="symbols">
					<t>Attribute Value: down-tree</t>
					<t>Description: A URI that refers to the set of descendant resources in a 
          hierarchy of resources.</t>
					<t>Expected display characteristics: none</t>
					<t>Security considerations: See this specification</t>
				</list>
				<list style="symbols">
					<t>Attribute Value: up-tree</t>
					<t>Description: A URI that refers to the set of ascendant resources 
          in a hierarchy of resources.</t>
					<t>Expected display characteristics: none</t>
					<t>Security considerations: See this specification</t>
				</list>
			</t>
		</section>
	</middle>
	<back>
		<references title="Normative References">
		   &rfc2119;
		   &rfc3986;
		   &rfc4287;
    </references>
    <section title="Acknowledgements">
			<t>
			Bill de hÓra 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. 
			</t>
		</section>
		<section title="Revision History">
			<t>
			00 - Initial Revision.
      </t>
			<t>
			00 - 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>
 			<t>
			01 - Changes include:
        <list style="hanging">
          <t>In-line representations of linked resources are independent of hierarchy</t>
          <t>Removed Atom specific language in link relation definitions</t>
          <t>Made explicit that this specification re-uses existing 'up' link relation</t>
          <t>Changed namespace prefix from ah to ae</t>
          <t>Removed the ah:count attribute and added the ae:inline element</t>
        </list>
      </t>
		</section>
	</back>
</rfc>