idnits 2.17.1 draft-nottingham-atompub-feed-history-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 449. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 426. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 433. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 439. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 1, 2005) is 6805 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'AtomSyntax' Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft September 1, 2005 4 Expires: March 5, 2006 6 Feed History: Enabling Incremental Syndication 7 draft-nottingham-atompub-feed-history-04 9 Status of this Memo 11 By submitting this Internet-Draft, each author represents that any 12 applicable patent or other IPR claims of which he or she is aware 13 have been or will be disclosed, and any of which he or she becomes 14 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on March 5, 2006. 34 Copyright Notice 36 Copyright (C) The Internet Society (2005). 38 Abstract 40 This document specifies a mechanism for feed publishers to give hints 41 about the completeness of a feed, and a means of retrieving "missed" 42 entries from a incremental feed. 44 Table of Contents 46 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 47 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 3 48 3. The 'fh:incremental' Element . . . . . . . . . . . . . . . . 4 49 4. The 'fh:archive' Element . . . . . . . . . . . . . . . . . . 5 50 5. The 'fh:prev' Element . . . . . . . . . . . . . . . . . . . 5 51 6. Feed Reconstruction . . . . . . . . . . . . . . . . . . . . 6 52 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7 53 8. Security Considerations . . . . . . . . . . . . . . . . . . 10 54 9. Normative References . . . . . . . . . . . . . . . . . . . . 11 55 Author's Address . . . . . . . . . . . . . . . . . . . . . . 11 56 A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 57 Intellectual Property and Copyright Statements . . . . . . . 12 59 1. Introduction 61 Syndication documents (e.g., those in formats such as Atom 62 [AtomSyntax] and RSS 63 ) usually only contain the last several entries in a larger 65 channel (or "feed") of information. Often, consuming software keeps 66 copies of all entries that have been previously seen, effectively 67 keeping a history of the feed's contents. 69 However, not all feeds benefit from this practice; in some, previous 70 entries are not relevant to the current contents of the feed. For 71 example, it's not desireable to keep history in this manner with a 72 "top ten" feed; showing old entries would imply that the previous 73 number one is now number eleven, and so forth. 75 Feeds that encourage this practice have a different problem. If 76 consuming software does not poll often enough, some entries may be 77 missed, causing them to be silently omitted. For some applications, 78 this is a serious error on its own. Even in non-critical 79 applications, this phenomenon can cause publishers to make Feed 80 Documents contain more entries than reasonably necessary, just to 81 assure that consumers have an amply large window in which to 82 reconstruct the feed. 84 This document specifies a mechanism that allows feed publishers to 85 give hints as to the completeness of a feed, and a means of 86 retrieving "missed" entries from a partial, or incremental, feed. 87 Although it refers to Atom normatively, the mechanism described 88 herein can be used with similar syndication formats, such as the 89 various flavours of RSS. 91 2. Notational Conventions 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 95 document are to be interpreted as described in BCP 14, [RFC2119], as 96 scoped to those conformance targets. 98 In this specification, "feed document" refers to an Atom Feed 99 Document, RSS document or similar syndication format instance. It 100 may contain any number of entries (in RSS, items), and may or may not 101 be a complete representation of the logical feed. 103 Similarly, "subscription document" refers to a feed document that is 104 intended to be subscribed to; i.e., it contains the most recent 105 entries available in the feed. 107 "Archive document" refers to a feed document that is archived; i.e., 108 the set of entries inside it does not change over time. Entries 109 within an archive MAY change themselves. Note that some entries in 110 the archive document may also be present in the subscription 111 document; in other words, some (but not necessarily all) "live" 112 entries might already be archived. 114 Finally, "head section" refers to the children of a feed document's 115 document-wide metadata container; e.g., the child elements of the 116 atom:feed element in an Atom Feed Document. 118 This specification uses XML Namespaces [W3C.REC-xml-names-19990114] 119 to uniquely identify XML element names. It uses the following 120 namespace prefix for the indicated namespace URI; 122 "fh": "http://purl.org/syndication/history/1.0" 124 This specification uses terms from the XML Infoset [W3C.REC-xml- 125 infoset-20040204]. However, this specification uses a shorthand; the 126 phrase "Information Item" is omitted when naming Element Information 127 Items. Therefore, when this specification uses the term "element," 128 it is referring to an Element Information Item in Infoset terms. 130 3. The 'fh:incremental' Element 132 The fh:incremental element indicates whether the subscription 133 document is a complete representation of the logical feed's entries, 134 and SHOULD occur in a subscription document's head section. It MUST 135 NOT occur there more than once, or elsewhere in a feed document. Its 136 content MUST be either "true" or "false". Whitespace in its content 137 MUST be ignored by consumers. 139 For example, 141 true 143 Subscription feeds MAY omit the fh:incremental element if the fh:prev 144 element is present; a consumer encountering a subscription document 145 that contains a fh:prev element but does not contain a fh:incremental 146 element MAY behave as if the fh:incremental is present and contains 147 "true". 149 If the content of the fh:incremental element is "false", it indicates 150 that the subscription document is a complete representation of the 151 entire feed; previous entries SHOULD NOT be considered part of the 152 feed by consumers. 154 For example, a feed that represents a ranking that varies over time, 155 such as "Top Twenty Records" or "Most Popular Items" should be marked 156 with a fh:incremental element containing "false". 158 If the content of the fh:incremental element is "true", it indicates 159 that the subscription document is a potentially partial 160 representation of the entire feed; previous entries MUST be 161 considered part of the feed by consumers. 163 For example, a feed that represents a chronological list, such as 164 "ExampleCo Press Releases" or "Widget Project Updates" should be 165 marked with a fh:incremental element containing "true". 167 A subscription document whose fh:incremental element contains "true" 168 MUST contain a fh:prev element, unless there are no previous entries 169 in the feed. A subscription document whose fh:incremental element 170 contains "false" MUST NOT contain a fh:prev element. 172 4. The 'fh:archive' Element 174 The fh:archive element is an empty element that indicates that the 175 feed document is an archive document and SHOULD occur in an archive 176 document's head section. It MUST NOT occur there more than once, or 177 elsewhere in a feed document. 179 For example, 181 183 Consumers can use this element to distinguish between subscription 184 documents and archive documents; e.g., to assure that an archive 185 document isn't subscribed to by mistake. 187 5. The 'fh:prev' Element 189 The fh:prev element conveys the location of an archive of previous 190 entries from the feed which sequentially precede those in the current 191 document, and MAY occur in a subscription document's head section. 192 It MUST occur in an archive document's head section, unless there are 193 no previous entries in the feed. It MUST NOT occur there more than 194 once, or elsewhere in a feed document. 196 Its content MUST be a URI reference [RFC3986] indicating the previous 197 archive document's location. Whitespace surrounding its content MUST 198 be ignored by consumers. 200 For example, 202 http://www.example.com/feed/archive/2005/05 204 Note that URI references may be relative, and when they are used they 205 must be absolutised, as described in Section 5.1 of [RFC3986]. 207 Also, note that the fh:prev element, on its own, does not bestow any 208 semantics on the ordering of entries in a feed; the only purpose of 209 introducing ordering here is to allow the feed to be reconstructed. 211 6. Feed Reconstruction 213 When presented with an incremental subscription document, a consumer 214 MAY reconstruct the entire feed in a local store by following these 215 steps, starting with the subscription document as the current 216 document: 218 1. Add all of the entries in the current document to the store. 219 2. Dereference the fh:prev URI, if present. If it is not present, 220 stop processing. 221 3. Using the dereferenced archive document as the current document, 222 start at step one (i.e., apply these steps recursively). 224 A consumer MAY stop when it encounters an fh:prev URI whose entries 225 have been successfully stored beforehand when following this process. 227 Note that consumers MAY cache archive documents and/or use a 228 different method of reconstructing the feed, as long as the result is 229 the same as that achieved by following these steps. 231 Consumers SHOULD warn users when they do not have the complete feed 232 (e.g., by alerting the user that an archive document is unavailable, 233 or inserting pseudo-entries that inform the user that some entries 234 may be missing). 236 Note that publishers are not required to make all archive documents 237 available. 239 7. Examples 241 Atom Subscription Document 243 244 246 Example Feed 247 248 2003-12-13T18:30:02Z 249 250 John Doe 251 252 urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 253 true 254 http://example.org/2003/11/index.atom 256 257 Atom-Powered Robots Run Amok 258 259 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 260 2003-12-13T18:30:02Z 261 Some text in a new, fresh entry. 262 264 265 Atom Archive Document 267 268 270 Example Feed 271 272 2003-11-24T12:00:00Z 273 274 John Doe 275 276 urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 277 278 http://example.org/2003/10/index.atom 280 281 Atom-Powered Robots Scheduled To Run Amok 282 283 urn:uuid:cd3272ef-b09c-42fd-806b-e25580e59b39 284 2003-11-24T12:00:00Z 285 Some text from an old, different entry. 286 288 289 RSS 2.0 Subscription Document 291 292 294 295 Liftoff News 296 http://liftoff.nasa.gov/ 297 Liftoff to Space Exploration. 298 en-us 299 Tue, 10 Jun 2003 04:00:00 GMT 300 Tue, 10 Jun 2003 09:41:01 GMT 301 http://blogs.law.harvard.edu/tech/rss 302 Weblog Editor 2.0 303 editor@example.com 304 webmaster@example.com 305 http://liftoff.nasa.gov/2003/05/feed 307 308 Star City 309 http://liftoff.nasa.gov/2003/06/news-starcity 310 How do Americans get ready to work with Russians 311 aboard the International Space Station? They take a crash course 312 in culture, language and protocol at Russia's Star 314 City. 315 Tue, 03 Jun 2003 09:39:21 GMT 316 http://liftoff.nasa.gov/2003/06/03.html#item573 317 318 319 321 (note that the incremental element has been omitted in this instance, 322 because the presense of the prev element indicates that the feed is 323 incremental.) 324 RSS 2.0 Archive Document 326 327 329 330 Liftoff News 331 http://liftoff.nasa.gov/ 332 Liftoff to Space Exploration. 333 en-us 334 Tue, 30 May 2003 08:00:00 GMT 335 Tue, 30 May 2003 10:31:52 GMT 336 http://blogs.law.harvard.edu/tech/rss 337 Weblog Editor 2.0 338 editor@example.com 339 webmaster@example.com 340 341 http://liftoff.nasa.gov/2003/04/feed 343 344 Sky watchers in Europe, Asia, and parts of 345 Alaska and Canada will experience a partial eclipse of the Sun 346 on Saturday, May 31st. 347 Fri, 30 May 2003 11:06:42 GMT 348 http://liftoff.nasa.gov/2003/05/30.html#item572 349 350 351 The Engine That Does More 352 http://liftoff.nasa.gov/2003/05/news-VASIMR.asp 353 Before man travels to Mars, NASA hopes to 354 design new engines that will let us fly through the Solar 355 System more quickly. The proposed VASIMR engine would do 356 that. 357 Tue, 27 May 2003 08:37:32 GMT 358 http://liftoff.nasa.gov/2003/05/27.html#item571 359 360 361 363 8. Security Considerations 365 Feeds using the mechanisms described here could be crafted in such a 366 way as to cause a consumer to initiate excessive (or even an unending 367 sequence of) network requests, causing denial of service (either to 368 the consumer, the target server, and/or intervening networks). 369 Consumers can mitigate this risk by requiring user intervention after 370 a certain number of requests, or by limiting requests either 371 according to a hard limit, or with heuristics. 373 Consumers should be mindful of resource limits when storing feed 374 documents; to reiterate, they are not required to always store or 375 reconstruct the feed when conforming to this specification; they only 376 need inform the user when the reconstructed feed is not complete. 378 9. Normative References 380 [AtomSyntax] 381 Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 382 Syndication Format", June 2005. 384 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 385 Requirement Levels", BCP 14, RFC 2119, March 1997. 387 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 388 Resource Identifier (URI): Generic Syntax", STD 66, 389 RFC 3986, January 2005. 391 [W3C.REC-xml-infoset-20040204] 392 Cowan, J. and R. Tobin, "XML Information Set (Second 393 Edition)", W3C REC REC-xml-infoset-20040204, 394 February 2004. 396 [W3C.REC-xml-names-19990114] 397 Bray, T., Hollander, D., and A. Layman, "Namespaces in 398 XML", W3C REC REC-xml-names-19990114, January 1999. 400 Author's Address 402 Mark Nottingham 404 Email: mnot@pobox.com 405 URI: http://www.mnot.net/ 407 Appendix A. Acknowledgements 409 The author would like to thanks the following people for their 410 contributions, comments and help: Danny Ayers, Thomas Broyer, Stefan 411 Eissing, David Hall, Aristotle Pagaltzis, Dave Pawson, Garrett 412 Rooney, Robert Sayre, James Snell, Henry Story. [[This is who showed 413 up in the e-mail archive; contact me if I missed you.]] 415 Any errors herein remain the author's, not theirs. 417 Intellectual Property Statement 419 The IETF takes no position regarding the validity or scope of any 420 Intellectual Property Rights or other rights that might be claimed to 421 pertain to the implementation or use of the technology described in 422 this document or the extent to which any license under such rights 423 might or might not be available; nor does it represent that it has 424 made any independent effort to identify any such rights. Information 425 on the procedures with respect to rights in RFC documents can be 426 found in BCP 78 and BCP 79. 428 Copies of IPR disclosures made to the IETF Secretariat and any 429 assurances of licenses to be made available, or the result of an 430 attempt made to obtain a general license or permission for the use of 431 such proprietary rights by implementers or users of this 432 specification can be obtained from the IETF on-line IPR repository at 433 http://www.ietf.org/ipr. 435 The IETF invites any interested party to bring to its attention any 436 copyrights, patents or patent applications, or other proprietary 437 rights that may cover technology that may be required to implement 438 this standard. Please address the information to the IETF at 439 ietf-ipr@ietf.org. 441 Disclaimer of Validity 443 This document and the information contained herein are provided on an 444 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 445 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 446 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 447 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 448 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 449 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 451 Copyright Statement 453 Copyright (C) The Internet Society (2005). This document is subject 454 to the rights, licenses and restrictions contained in BCP 78, and 455 except as set forth therein, the authors retain all their rights. 457 Acknowledgment 459 Funding for the RFC Editor function is currently provided by the 460 Internet Society.