idnits 2.17.1
draft-divilly-atom-hierarchy-03.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
** The document seems to lack a License Notice according IETF Trust
Provisions of 28 Dec 2009, Section 6.b.ii or Provisions of 12 Sep 2009
Section 6.b -- however, there's a paragraph with a matching beginning.
Boilerplate error?
(You're using the IETF Trust Provisions' Section 6.b License Notice from
12 Feb 2009 rather than one of the newer Notices. See
https://trustee.ietf.org/license-info/.)
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The abstract seems to contain references ([1]), which it shouldn't.
Please replace those with straight textual mentions of the documents in
question.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (July 1, 2009) is 5410 days in the past. Is this
intentional?
Checking references for intended status: Experimental
----------------------------------------------------------------------------
== Unused Reference: 'RFC3986' is defined on line 229, but no explicit
reference was found in the text
Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group C. Divilly
3 Internet-Draft N. Mehta
4 Intended status: Experimental Oracle Corp.
5 Expires: January 2, 2010 July 1, 2009
7 Hierarchy Relations for Atom
8 draft-divilly-atom-hierarchy-03
10 Status of this Memo
12 This Internet-Draft is submitted to IETF in full conformance with the
13 provisions of BCP 78 and BCP 79.
15 Internet-Drafts are working documents of the Internet Engineering
16 Task Force (IETF), its areas, and its working groups. Note that
17 other groups may also distribute working documents as Internet-
18 Drafts.
20 Internet-Drafts are draft documents valid for a maximum of six months
21 and may be updated, replaced, or obsoleted by other documents at any
22 time. It is inappropriate to use Internet-Drafts as reference
23 material or to cite them other than as "work in progress."
25 The list of current Internet-Drafts can be accessed at
26 http://www.ietf.org/ietf/1id-abstracts.txt.
28 The list of Internet-Draft Shadow Directories can be accessed at
29 http://www.ietf.org/shadow.html.
31 This Internet-Draft will expire on January 2, 2010.
33 Copyright Notice
35 Copyright (c) 2009 IETF Trust and the persons identified as the
36 document authors. All rights reserved.
38 This document is subject to BCP 78 and the IETF Trust's Legal
39 Provisions Relating to IETF Documents in effect on the date of
40 publication of this document (http://trustee.ietf.org/license-info).
41 Please review these documents carefully, as they describe your rights
42 and restrictions with respect to this document.
44 Abstract
46 This specification defines link relations for hierarchical navigation
47 among Atom feeds and entries.
49 Editorial Note
51 To provide feedback on this Internet-Draft, join the atom-syntax
52 mailing list (http://www.imc.org/atom-syntax/) [1].
54 Table of Contents
56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3
58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3
59 2. Hierarchy link relations . . . . . . . . . . . . . . . . . . . 3
60 2.1. Modeling Hierarchy In Atom . . . . . . . . . . . . . . . . 3
61 2.2. The "down" Link . . . . . . . . . . . . . . . . . . . . . . 4
62 2.3. The "up" Link . . . . . . . . . . . . . . . . . . . . . . . 5
63 3. Security Considerations . . . . . . . . . . . . . . . . . . . . 5
64 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5
65 5. Normative References . . . . . . . . . . . . . . . . . . . . . 6
66 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 6
67 Appendix B. Revision History . . . . . . . . . . . . . . . . . . . 6
68 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7
70 1. Introduction
72 Many applications, besides blogs, provide their data in the form of
73 syndicated Web feeds using formats such as Atom [RFC4287]. Some such
74 applications organize Atom Entries in a hierarchical fashion similar
75 to a file system.
77 This specification describes a means of communicating about Atom
78 Entries that are hierarchically related to each other since resource
79 identifiers are opaque to clients and cannot be directly manipulated
80 for the purposes of representation exchange, i.e., navigation.
82 This specification proposes new link relations for hierarchically
83 related Atom resources.
85 1.1. Notational Conventions
87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
89 document are to be interpreted as described in [RFC2119].
91 1.2. Terminology
93 This specification uses Atom link relations to identify different
94 types of links; see the Atom specification [RFC4287] for information
95 about their syntax, and the IANA link relation registry for more
96 information about specific values.
98 2. Hierarchy link relations
100 A hierarchy exists when a resource indicates the likelihood of the
101 existence of a parent and/or a child resource. The terms parent and
102 child are indicative of the need for the former to exist before the
103 latter can be created.
105 2.1. Modeling Hierarchy In Atom
107 The Atom Syndication Format [RFC4287] defines the Atom Entry
108 construct. The extensions in this specification define two
109 specialized kinds of Entry construct -- parent Entry and child Entry.
111 A parent Entry is a container for child Entries. A parent Entry
112 could itself be a child of another parent Entry.
114 Every Entry construct is represented as an Atom Entry Document
115 [RFC4287] referred to in this specification as an "entry" and its
116 plural. A logical Feed comprising entirely of child entries of a
117 given Entry is called its child feed and one comprising entirely of
118 its parent entries is called its parent feed. Both parent feed and
119 child feed are seen from the perspective of a given Entry resource.
120 The entries in the parent feed and child feed of an Entry SHOULD be
121 disjoint, i.e., not share any entries.
123 Applications MAY allow more than one parent Entry to contain a given
124 child Entry. This is similar to hard links in filesystems. On the
125 other hand, certain applications allow only a single parent Entry.
127 A child Entry MAY use a logical Feed to represent multiple parent
128 Entries. Alternatively, a child Entry MAY use multiple "up" atom:
129 link elements, each to identify one of the parent Entries.
131 Per section 4.1.1 of [RFC4287] if multiple atom:entry elements with
132 the same atom:id value appear in a logical Feed, they represent the
133 same entry.
135 2.2. The "down" Link
137 An Atom link element with a rel attribute value of "down" may be used
138 to reference a resource where child entries of an entry may be found.
139 If the type attribute of the atom:link is omitted, its value is
140 assumed to be "application/atom+xml".
142 For example,
144
145 Hanky Panky Portfolio
146
148
150 ...
151
153 Although Atom feed and entry elements MAY each contain any number of
154 atom:link elements using the "down" link relation, this specification
155 assigns no significance to the presence or order of such links.
156 Multiple down links appearing within an atom:entry may reference
157 alternative representations of the same set of children or may
158 reference entirely distinct resources containing distinct sets of
159 children. Processors MUST NOT assume that multiple down links are
160 referencing different representations of the same resource and MUST
161 process each down link independently of any others.
163 The link element MAY contain an [RFC4685] thr:count element to
164 indicate the number of entries in the down link, but as per section 6
165 of [RFC4685] this value is only an indication and may not be
166 accurate.
168 2.3. The "up" Link
170 An Atom link element with a rel attribute value of "up" may be used
171 to reference a resource where parent entries of an entry or a feed
172 may be found. If the type attribute of the atom:link is omitted, its
173 value is assumed to be "application/atom+xml".
175 For example,
177
178 Positions in Hanky Panky
179
181
183 ...
184
186 Although Atom feed and entry elements MAY each contain any number of
187 atom:link elements using the "up" link relation, this specification
188 assigns no significance to the presence or order of such links.
189 Multiple up links appearing within an atom:entry may reference
190 alternative representations of the same set of parents or may
191 reference entirely distinct resources containing distinct sets of
192 parents. Processors MUST NOT assume that multiple up links are
193 referencing different representations of the same resource and MUST
194 process each up link independently of any others.
196 The link element MAY contain an [RFC4685] thr:count element to
197 indicate the number of entries in the up link, but as per section 6
198 of [RFC4685] this value is only an indication and may not be
199 accurate.
201 3. Security Considerations
203 Hierarchy Extensions for Atom is subject to the security
204 considerations found in Section 8 of [RFC4287].
206 4. IANA Considerations
208 This specification uses the following relation that has been
209 previously registered in the Link Relations Registry
210 o Attribute Value: up
211 o Description: A URI that refers to one or more parent resources in
212 a hierarchy of resources.
213 o Expected display characteristics: none
214 o Security considerations: See this specification
216 This specification defines the following new relations that have been
217 added to the Link Relations registry:
218 o Attribute Value: down
219 o Description: A URI that refers to one or more child resources in a
220 hierarchy of resources.
221 o Expected display characteristics: none
222 o Security considerations: See this specification
224 5. Normative References
226 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
227 Requirement Levels", BCP 14, RFC 2119, March 1997.
229 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
230 Resource Identifier (URI): Generic Syntax", STD 66,
231 RFC 3986, January 2005.
233 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
234 Syndication Format", RFC 4287, December 2005.
236 [RFC4685] Snell, J., "Atom Threading Extensions", RFC 4685,
237 September 2006.
239 [1]
241 Appendix A. Acknowledgements
243 Bill de hOra and Ashish Motivala reviewed early drafts of this I-D.
244 On the atom-syntax mailing list, Al Brown, Peter Keane, Julian
245 Reschke, Mark Nottingham, Pablo Castro, Kyle Marvin, James Snell,
246 Hadrien Gardeur, and Cornelia Davis provided very valuable feedback
247 to improve the subsequent public drafts.
249 Appendix B. Revision History
251 00 - Initial Revision.
253 00 - Based on feedback from Peter Keane, Julian Reschke, and members
254 of the CMIS TC made the following changes:
256 Renamed the link relation "detail" to "down" and "master" to "up"
257 Removed Section 3, 4, 6, and 7
258 Changed namespace prefix from h to ah
259 Added new link relations "up-tree" and "down-tree"
261 01 - Changes include:
262 In-line representations of linked resources are independent of
263 hierarchy
264 Removed Atom specific language in link relation definitions
265 Made explicit that this specification re-uses existing 'up' link
266 relation
267 Changed namespace prefix from ah to ae
268 Removed the ah:count attribute and added the ae:inline element
270 02 - Changes include:
271 In-line extensions moved to draft-mehta-atom-inline
272 Removed down-tree and up-tree relations
273 Removed cardinality restrictions on up and down links
275 03 - Changes include:
276 Illustrate use of thr:count
277 Fixed typo
278 Remove references to rel="up" for atom:source elements
279 Repeat RFC4287 rules for handling multiple entries with same
280 atom:id
282 Authors' Addresses
284 Colm Divilly
285 Oracle Corp.
287 Email: colm.divilly@oracle.com
288 URI: http://cdivilly.wordpress.com
290 Nikunj R. Mehta
291 Oracle Corp.
293 Email: nikunj.mehta@oracle.com
294 URI: http://o-micron.blogspot.com/