idnits 2.17.1 draft-nottingham-atompub-feed-history-06.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 623. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 600. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 607. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 613. ** 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 : ---------------------------------------------------------------------------- No issues found here. 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 the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (June 25, 2006) is 6515 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) No issues found here. Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft June 25, 2006 4 Expires: December 27, 2006 6 Extensions for Multi-Document Syndicated Feeds 7 draft-nottingham-atompub-feed-history-06 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 December 27, 2006. 34 Copyright Notice 36 Copyright (C) The Internet Society (2006). 38 Abstract 40 This specification defines three types of syndicated feeds that 41 enable publication of entries across one or more feed documents. 43 Table of Contents 45 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 46 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 47 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 48 4. Complete Feeds . . . . . . . . . . . . . . . . . . . . . . . . 4 49 4.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 5 50 5. Paged Feeds . . . . . . . . . . . . . . . . . . . . . . . . . 6 51 5.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 7 52 6. Archived Feeds . . . . . . . . . . . . . . . . . . . . . . . . 8 53 6.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 10 54 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 55 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 56 9. Normative References . . . . . . . . . . . . . . . . . . . . . 14 57 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 58 Appendix B. Reconstructing Archived Feeds . . . . . . . . . . . . 15 59 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 60 Intellectual Property and Copyright Statements . . . . . . . . . . 17 62 1. Introduction 64 Syndicated feeds of information (using such formats as Atom [RFC4287] 65 or RSS 2.0) are often split up into multiple documents to save 66 bandwidth, allow "sliding window" access, or for other purposes. 68 This specification defines three types of feeds that allow the 69 reconstruction of their state from one or more feed documents; 70 "complete" feeds, "paged" feeds and "archived" feeds. 72 These types are complementary; each has different properties and 73 trade-offs: 75 o Complete feeds contain the entire set of entries in one document, 76 and can be useful when it isn't desirable to "remember" 77 previously-seen entries. 78 o Paged feeds split the logical feed's entries among multiple 79 temporary documents. This can be useful when entries in the feed 80 are not long-lived or stable, and the client needs to access an 81 arbitrary portion of them, usually in close succession. 82 o Archived feeds split them among multiple permanent documents, and 83 can be useful when entries are long-lived and it is important for 84 clients to see every one. 86 See the feed type definitions below for examples of use cases for 87 each. 89 2. Notational Conventions 91 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 92 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 93 document are to be interpreted as described in BCP 14 [RFC2119], as 94 scoped to those conformance targets. 96 This specification uses XML Namespaces [W3C.REC-xml-names-19990114] 97 to uniquely identify XML element names. It uses the following 98 namespace prefix for the indicated namespace URI; 100 "fh": "http://purl.org/syndication/history/1.0" 102 This specification uses terms from the XML Infoset [W3C.REC-xml- 103 infoset-20040204]. However, this specification uses a shorthand; the 104 phrase "Information Item" is omitted when naming Element Information 105 Items. Therefore, when this specification uses the term "element," 106 it is referring to an Element Information Item in Infoset terms. 108 This specification also uses Atom link relations to identify 109 different types of links; see the Atom specification [RFC4287] for 110 information about their syntax, and the IANA link relation registry 111 for more information about specific values. 113 Although they refer to Atom normatively, the mechanisms described 114 herein can be used with similar syndication formats, such as the 115 various flavours of RSS. 117 3. Terminology 119 In this specification, "feed document" refers to an Atom Feed 120 Document, RSS document, or similar syndication instance document. It 121 may contain any number of entries (in RSS, items), and may or may not 122 be a complete representation of the logical feed. 124 "Head section" refers to the children of a feed document's document- 125 wide metadata container; e.g., the child elements of the atom:feed 126 element in an Atom Feed Document. 128 A "logical feed" is the set of entries associated with a particular 129 feed (as contrasted with a feed document, which may contain a subset 130 of them). 132 4. Complete Feeds 134 A complete feed is a feed document that contains all of the entries 135 in the logical feed; any entry not actually in the feed document 136 SHOULD NOT be presented as part of that feed. 138 It is sometimes important to distinguish a complete feed, because 139 clients may attempt to keep a history of feed entries seen over time, 140 presenting the aggregate as the feed's contents. This is 141 undesireable in some situations. 143 For example; a feed that represents a ranking that varies over time, 144 such as "Top Twenty Records" or "Most Popular Items" should not have 145 newer entries displayed alongside older ones. By marking them as 146 complete feeds, old entries are discarded when the feed is refreshed. 148 The fh:complete element, when present in a feed's head section, 149 indicates that the feed document it occurs in is a complete 150 representation of the logical feed's entries. 152 For example, 154 156 4.1. Examples 158 Atom-formatted Complete Feed 160 161 163 NetTunes Queue 164 The CDs you'll receive next. 165 166 167 169 2003-12-13T18:30:02Z 170 171 John Doe 172 173 urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 174 175 A Rush of Blood to the Head 176 177 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 178 2003-12-13T18:30:02Z 179 More jangly guitars from Coldplay... 180 181 182 RSS 2.0-formatted Complete Feed 184 185 187 188 NetTunes Queue 189 http://nettunes.example.org/ 190 The CDs you'll receive next. 191 en-us 192 Tue, 10 Jun 2003 04:00:00 GMT 193 Tue, 10 Jun 2003 09:41:01 GMT 194 http://blogs.law.harvard.edu/tech/rss 195 Weblog Editor 2.0 196 editor@nettunes.example.org 197 webmaster@nettunes.example.org 198 199 200 A Rush of Blood to the Head 201 http://nettunes.example.org/Coldplay/rush 202 More jangly guitars from Coldplay... 203 204 Tue, 03 Jun 2003 09:39:21 GMT 205 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 206 207 208 210 5. Paged Feeds 212 A paged feed is a set of linked feed documents that contain the 213 entries in the logical feed, without any guarantees about the 214 stability of the documents' contents. 216 Paged feeds are lossy; that is, it is not possible to guarantee that 217 the client will be able to reconstruct the logical feed as the server 218 has published it. Some entries may be added to the feed as the pages 219 of the feed are acccessed, without the client becoming aware of them. 221 Paged feeds can be useful when the number of entries is very large, 222 infinite, or indeterminate. Clients can "page" through the feed, 223 only accessing a subset of the feed's entries as necessary. 225 For example, a search engine might make query results available as a 226 paged feed, so that queries with very large result sets do not 227 overwhelm the server, the network, or the client. 229 The feed documents in a paged feed are tied together with the 230 following link relations: 232 o "first" - A URI that refers to the furthest preceding document in 233 a series of documents. 234 o "last" - A URI that refers to the furthest following document in a 235 series of documents. 236 o "previous" - A URI that refers to the immediately preceding 237 document in a series of documents. 238 o "next" - A URI that refers to the immediately following document 239 in a series of documents. 241 Paged feed documents MUST have at least one of these link relations 242 present, and SHOULD contain as many as practical and applicable. 244 Note that URI references in link relation values may be relative, and 245 when they are used they must be absolutised, as described in Section 246 5.1 of [RFC3986]. 248 5.1. Examples 250 Atom-formatted Paged Feed 252 253 254 Example Feed 255 256 257 258 2003-12-13T18:30:02Z 259 260 John Doe 261 262 urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 263 264 Atom-Powered Robots Run Amok 265 266 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 267 2003-12-13T18:30:02Z 268 Some text. 269 270 271 RSS 2.0-formatted Paged Feed 273 274 276 277 Liftoff News 278 http://liftoff.nasa.gov/ 279 Liftoff to Space Exploration. 280 en-us 281 Tue, 10 Jun 2003 04:00:00 GMT 282 Tue, 10 Jun 2003 09:41:01 GMT 283 http://blogs.law.harvard.edu/tech/rss 284 Weblog Editor 2.0 285 editor@example.com 286 webmaster@example.com 287 301 303 6. Archived Feeds 305 An archived feed is a set of feed documents that can be combined to 306 accurately reconstruct a logical feed. 308 Unlike paged feeds, archived feeds enable clients to do this without 309 losing any entries. This is achieved by publishing a single 310 subscription document and (potentially) many archive documents. 312 A subscription document is a feed document that always contains the 313 most recently added or changed entries available in the logical feed 314 (often, the feed document that should be subscribed to). 316 Archive documents are feed documents that contain less recent entries 317 in the feed. The set of entries contained in an archive document 318 published at a particular URI MUST NOT change over time. 320 Likewise, the URI for a particular archive document MUST NOT change 321 over time, so that clients can recognise it and associate it with the 322 entries contained therein. 324 Typically, a logical feed will make a subscription feed available, 325 and link it to a set of archive documents (also linked together) 326 which contain progressively less recent entries. 328 Clients can then "subscribe" to the feed, polling the subscription 329 document for recent changes. If a client has missed some entries, 330 the archives can be used to synchronise its state by fetching the 331 archive documents it has not yet seen. 333 Note that because archive documents are considered stable, changes to 334 entries in them may not be apparent to all users. Therefore, if a 335 publisher requires a change to be visible to all users (e.g., 336 correcting factual errors), they should consider publishing the 337 revised entry in the subscription feed, in addition to (or instead 338 of) the appropriate archive feed. Conversely, unimportant changes 339 (e.g., spelling corrections) might be only effected in archive feeds. 341 The following link relations are used to tie archived feeds together: 343 o "prev-archive" - A URI that refers to the immediately preceding 344 archive document. 345 o "next-archive" - A URI that refers to the immediately following 346 archive document. 347 o "current" - A URI that, when dereferenced, returns a feed document 348 containing the most recent entries in the feed. 350 Subscription documents and archive documents MUST have a "prev- 351 archive" link relation, unless there are no archives available. 353 Archive documents SHOULD have "next-archive" and "current" link 354 relations. 356 Note that URI references in link relation values may be relative, and 357 when they are used they must be absolutised, as described in Section 358 5.1 of [RFC3986]. 360 Archive document SHOULD also contain an fh:archive element in their 361 head sections, to indicate that they themselves are archives. 363 For example, 365 367 Publishers are not required to make all archive documents available; 368 they may refuse to serve (e.g., with HTTP status code 403 or 410), or 369 be unable to serve (e.g., with HTTP status code 404) an archive 370 document. 372 Clients SHOULD warn users when they are not able to reconstruct the 373 complete, logical feed (e.g., by alerting the user that an archive 374 document is unavailable, or displaying pseudo-entries that inform the 375 user that some entries may be missing). 377 6.1. Examples 379 Atom-formatted Subscription Document 381 382 383 Example Feed 384 385 386 388 2003-12-13T18:30:02Z 389 390 John Doe 391 392 urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 393 394 Atom-Powered Robots Run Amok 395 396 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 397 2003-12-13T18:30:02Z 398 Some text. 399 400 401 Atom-formatted Archive Document 403 404 405 Example Feed 406 407 408 410 2003-11-24T12:00:00Z 411 412 John Doe 413 414 urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 415 416 Atom-Powered Robots Scheduled To Run Amok 417 418 urn:uuid:cdef5c6d5-gff8-4ebb-assa-80dwe44efkjo 419 2003-11-24T12:00:00Z 420 Some text from an old, different entry. 421 422 423 RSS 2.0-formatted Subscription Document 425 426 427 428 Liftoff News 429 http://liftoff.nasa.gov/ 430 Liftoff to Space Exploration. 431 en-us 432 Tue, 10 Jun 2003 04:00:00 GMT 433 Tue, 10 Jun 2003 09:41:01 GMT 434 http://blogs.law.harvard.edu/tech/rss 435 Weblog Editor 2.0 436 editor@example.com 437 webmaster@example.com 438 441 442 Star City 443 http://liftoff.nasa.gov/2003/06/news-starcity 444 How do Americans get ready to work with Russians 445 aboard the International Space Station? They take a crash course 446 in culture, language and protocol at Russia's 449 Tue, 03 Jun 2003 09:39:21 GMT 450 http://liftoff.nasa.gov/2003/06/03.html#item573 451 452 453 454 RSS 2.0-formatted Archive Document 456 457 458 459 Liftoff News 460 http://liftoff.nasa.gov/ 461 Liftoff to Space Exploration. 462 en-us 463 Tue, 30 May 2003 08:00:00 GMT 464 Tue, 30 May 2003 10:31:52 GMT 465 http://blogs.law.harvard.edu/tech/rss 466 Weblog Editor 2.0 467 editor@example.com 468 webmaster@example.com 469 471 474 475 Sky watchers in Europe, Asia, and parts of 476 Alaska and Canada will experience a partial eclipse of the Sun 477 on Saturday, May 31st. 478 Fri, 30 May 2003 11:06:42 GMT 479 http://liftoff.nasa.gov/2003/05/30.html#item572 480 481 482 The Engine That Does More 483 http://liftoff.nasa.gov/2003/05/news-VASIMR.asp 484 Before man travels to Mars, NASA hopes to 485 design new engines that will let us fly through the Solar 486 System more quickly. The proposed VASIMR engine would do 487 that. 488 Tue, 27 May 2003 08:37:32 GMT 489 http://liftoff.nasa.gov/2003/05/27.html#item571 490 491 492 494 7. IANA Considerations 496 The "previous", "next" and "current" link relations have been 497 previously registered, and no IANA action regarding them is required. 499 This specification defines the following link relations: 501 o Attribute Value: prev-archive 502 o Description: A URI that refers to the immediately 503 preceding archive document. 504 o Expected display characteristics: none 505 o Security considerations: See [ this document ] 507 o Attribute Value: next-archive 508 o Description: A URI that refers to the immediately 509 following archive document. 510 o Expected display characteristics: none 511 o Security considerations: See [ this document ] 513 8. Security Considerations 515 Feeds using the mechanisms described here could be crafted in such a 516 way as to cause a client to initiate excessive (or even an unending 517 sequence of) network requests, causing denial of service (either to 518 the client, the target server, and/or intervening networks). Clients 519 can mitigate this risk by requiring user intervention after a certain 520 number of requests, or by limiting requests either according to a 521 hard limit, or with heuristics. 523 Clients should be mindful of resource limits when storing feed 524 documents. To reiterate, they are not required to always store or 525 reconstruct the feed when conforming to this specification; they only 526 need inform the user when the reconstructed feed is not complete. 528 9. Normative References 530 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 531 Requirement Levels", BCP 14, RFC 2119, March 1997. 533 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 534 Resource Identifier (URI): Generic Syntax", STD 66, 535 RFC 3986, January 2005. 537 [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication 538 Format", RFC 4287, December 2005. 540 [W3C.REC-xml-infoset-20040204] 541 Cowan, J. and R. Tobin, "XML Information Set (Second 542 Edition)", W3C REC REC-xml-infoset-20040204, 543 February 2004. 545 [W3C.REC-xml-names-19990114] 546 Bray, T., Hollander, D., and A. Layman, "Namespaces in 547 XML", W3C REC REC-xml-names-19990114, January 1999. 549 Appendix A. Acknowledgements 551 The author would like to thank the following people for their 552 contributions, comments and help: Danny Ayers, Thomas Broyer, Stefan 553 Eissing, David Hall, Bill de Hora, Aristotle Pagaltzis, John Panzer, 554 Dave Pawson, Garrett Rooney, Robert Sayre, James Snell, Henry Story. 556 Any errors herein remain the author's, not theirs. 558 Appendix B. Reconstructing Archived Feeds 560 One algorithm for reconstructing an archived feed into a complete, 561 logical feed (S), give the subscription document (D) follows. 563 1. Create an empty list L. 564 2. Consider the URI of the last archive document successfully stored 565 to local store S as A. 566 3. Consider the set of entries in document D as E. 567 4. If the document D has a "prev-archive" link relation value P in 568 its head section, and P is not A, 569 1. Append P to L. 570 2. Dereference P and use the resulting feed document as D. 571 5. Repeat the previous step until no new P is found. 572 6. Add all of document D's entries to the local store S, replacing 573 any entries with the same identity. 574 7. Pop the last "prev-archive" link relation from L, dereference its 575 value and use the resulting feed document as D. 576 8. Repeat the previous two steps until L is empty. 577 9. Add the entries E to the local store S, replacing any entries 578 with the same identity. 580 In these instructions, the concept of an entry's identity is format- 581 specific; e.g., in Atom, it is conveyed by the atom:id element; in 582 RSS 2, it is indicated by the guid element. 584 Author's Address 586 Mark Nottingham 588 Email: mnot@pobox.com 589 URI: http://www.mnot.net/ 591 Intellectual Property Statement 593 The IETF takes no position regarding the validity or scope of any 594 Intellectual Property Rights or other rights that might be claimed to 595 pertain to the implementation or use of the technology described in 596 this document or the extent to which any license under such rights 597 might or might not be available; nor does it represent that it has 598 made any independent effort to identify any such rights. Information 599 on the procedures with respect to rights in RFC documents can be 600 found in BCP 78 and BCP 79. 602 Copies of IPR disclosures made to the IETF Secretariat and any 603 assurances of licenses to be made available, or the result of an 604 attempt made to obtain a general license or permission for the use of 605 such proprietary rights by implementers or users of this 606 specification can be obtained from the IETF on-line IPR repository at 607 http://www.ietf.org/ipr. 609 The IETF invites any interested party to bring to its attention any 610 copyrights, patents or patent applications, or other proprietary 611 rights that may cover technology that may be required to implement 612 this standard. Please address the information to the IETF at 613 ietf-ipr@ietf.org. 615 Disclaimer of Validity 617 This document and the information contained herein are provided on an 618 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 619 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 620 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 621 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 622 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 623 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 625 Copyright Statement 627 Copyright (C) The Internet Society (2006). This document is subject 628 to the rights, licenses and restrictions contained in BCP 78, and 629 except as set forth therein, the authors retain all their rights. 631 Acknowledgment 633 Funding for the RFC Editor function is currently provided by the 634 Internet Society.