idnits 2.17.1 draft-ietf-atompub-format-03.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 3667, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1118. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1095. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1102. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1108. ** Found boilerplate matching RFC 3978, Section 5.4, paragraph 1 (on line 1124), which is fine, but *also* found old RFC 2026, Section 10.4C, paragraph 1 text on line 37. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ** 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. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, or will be disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 24 longer pages, the longest (page 9) being 73 lines == It seems as if not all pages are separated by form feeds - found 0 form feeds but 32 pages 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 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 (October 20, 2004) is 7121 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. 'Atom-autodiscovery' -- Possible downref: Non-RFC (?) normative reference: ref. 'Atom-protocol' ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2822 (Obsoleted by RFC 5322) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 3066 (Obsoleted by RFC 4646, RFC 4647) ** Obsolete normative reference: RFC 3548 (Obsoleted by RFC 4648) -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' Summary: 11 errors (**), 0 flaws (~~), 4 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group M. Nottingham, Ed. 2 Internet-Draft 3 Expires: April 20, 2005 R. Sayre, Ed. 4 Boswijck Memex Consulting 5 October 20, 2004 7 The Atom Syndication Format 8 draft-ietf-atompub-format-03 10 Status of this Memo 12 By submitting this Internet-Draft, I certify that any applicable 13 patent or other IPR claims of which I am aware have been disclosed, 14 and any of which I become aware will be disclosed, in accordance with 15 RFC 3668. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as 20 Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on April 20, 2005. 35 Copyright Notice 37 Copyright (C) The Internet Society (2004). All Rights Reserved. 39 Abstract 41 This document specifies Atom, an XML-based Web content and metadata 42 syndication format. 44 Table of Contents 46 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 47 1.1 Editorial Notes . . . . . . . . . . . . . . . . . . . . . 4 48 1.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 49 1.3 Conformance . . . . . . . . . . . . . . . . . . . . . . . 5 50 1.4 Notational Conventions . . . . . . . . . . . . . . . . . . 5 51 2. Atom Documents . . . . . . . . . . . . . . . . . . . . . . . 7 52 3. Common Atom Constructs . . . . . . . . . . . . . . . . . . . 8 53 3.1 Text Constructs . . . . . . . . . . . . . . . . . . . . . 8 54 3.1.1 "type" Attribute . . . . . . . . . . . . . . . . . . . 8 55 3.2 Person Constructs . . . . . . . . . . . . . . . . . . . . 8 56 3.2.1 "atom:name" Element . . . . . . . . . . . . . . . . . 9 57 3.2.2 "atom:uri" Element . . . . . . . . . . . . . . . . . . 9 58 3.2.3 "atom:email" Element . . . . . . . . . . . . . . . . . 9 59 3.3 Date Constructs . . . . . . . . . . . . . . . . . . . . . 9 60 3.4 Service Constructs . . . . . . . . . . . . . . . . . . . . 9 61 3.4.1 "href" Attribute . . . . . . . . . . . . . . . . . . . 9 62 3.5 Link Constructs . . . . . . . . . . . . . . . . . . . . . 10 63 3.5.1 "rel" Attribute . . . . . . . . . . . . . . . . . . . 10 64 3.5.2 "type" Attribute . . . . . . . . . . . . . . . . . . . 10 65 3.5.3 "href" Attribute . . . . . . . . . . . . . . . . . . . 10 66 3.5.4 "hreflang" Attribute . . . . . . . . . . . . . . . . . 10 67 3.5.5 "title" Attribute . . . . . . . . . . . . . . . . . . 11 68 3.6 Identity Constructs . . . . . . . . . . . . . . . . . . . 11 69 3.6.1 Dereferencing Identity Constructs . . . . . . . . . . 11 70 3.6.2 Comparing Identity Constructs . . . . . . . . . . . . 12 71 4. The "atom:feed" Element . . . . . . . . . . . . . . . . . . 13 72 4.1 "version" Attribute . . . . . . . . . . . . . . . . . . . 13 73 4.2 The "atom:head" Element . . . . . . . . . . . . . . . . . 13 74 4.2.1 "atom:title" Element . . . . . . . . . . . . . . . . . 13 75 4.2.2 "atom:link" Element . . . . . . . . . . . . . . . . . 13 76 4.2.3 "atom:introspection" Element . . . . . . . . . . . . . 14 77 4.2.4 "atom:post" Element . . . . . . . . . . . . . . . . . 14 78 4.2.5 "atom:author" Element . . . . . . . . . . . . . . . . 14 79 4.2.6 "atom:contributor" Element . . . . . . . . . . . . . . 14 80 4.2.7 "atom:tagline" Element . . . . . . . . . . . . . . . . 14 81 4.2.8 "atom:id" Element . . . . . . . . . . . . . . . . . . 14 82 4.2.9 "atom:generator" Element . . . . . . . . . . . . . . . 15 83 4.2.10 "atom:copyright" Element . . . . . . . . . . . . . . 15 84 4.2.11 "atom:info" Element . . . . . . . . . . . . . . . . 15 85 4.2.12 "atom:updated" Element . . . . . . . . . . . . . . . 16 86 5. The "atom:entry" Element . . . . . . . . . . . . . . . . . . 17 87 5.1 "atom:title" Element . . . . . . . . . . . . . . . . . . . 17 88 5.2 "atom:link" Element . . . . . . . . . . . . . . . . . . . 17 89 5.3 "atom:edit" Element . . . . . . . . . . . . . . . . . . . 17 90 5.4 "atom:author" Element . . . . . . . . . . . . . . . . . . 18 91 5.5 "atom:contributor" Element . . . . . . . . . . . . . . . . 18 92 5.6 "atom:id" Element . . . . . . . . . . . . . . . . . . . . 18 93 5.7 "atom:updated" Element . . . . . . . . . . . . . . . . . . 18 94 5.8 "atom:published" Element . . . . . . . . . . . . . . . . . 18 95 5.9 "atom:summary" Element . . . . . . . . . . . . . . . . . . 19 96 5.10 "atom:content" Element . . . . . . . . . . . . . . . . . 19 97 5.10.1 "type" attribute . . . . . . . . . . . . . . . . . . 19 98 5.10.2 "src" attribute . . . . . . . . . . . . . . . . . . 19 99 5.10.3 Processing Model . . . . . . . . . . . . . . . . . . 20 100 5.11 "atom:copyright" Element . . . . . . . . . . . . . . . . 21 101 5.12 "atom:origin" Element . . . . . . . . . . . . . . . . . 21 102 6. Managing Feed State . . . . . . . . . . . . . . . . . . . . 22 103 7. Securing Atom Documents . . . . . . . . . . . . . . . . . . 23 104 7.1 Digital Signatures . . . . . . . . . . . . . . . . . . . . 23 105 7.2 Encryption . . . . . . . . . . . . . . . . . . . . . . . . 23 106 8. Embedding Atom in Other Formats . . . . . . . . . . . . . . 24 107 9. Extending Atom . . . . . . . . . . . . . . . . . . . . . . . 25 108 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 26 109 11. Security Considerations . . . . . . . . . . . . . . . . . . 27 110 12. Normative References . . . . . . . . . . . . . . . . . . . . 27 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 28 112 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 29 113 B. Revision History . . . . . . . . . . . . . . . . . . . . . . 30 114 Intellectual Property and Copyright Statements . . . . . . . 32 116 1. Introduction 118 Atom is an XML-based document format intended to allow lists of 119 related information, known as "feeds", to be synchronised between 120 publishers and consumers. Feeds are composed of a number of items, 121 known as "entries", each with an extensible set of attached metadata. 122 For example, each entry has a title. 124 The primary use case that Atom addresses is the syndication of Web 125 content such as Weblogs and news headlines to Web sites as well as 126 directly to user agents. However, nothing precludes it from being 127 used for other purposes and kinds of content. 129 Details of communication protocols between software agents using Atom 130 can be found in the Atom Protocol specification [Atom-protocol]. 132 [[ more motivation / design principles ]] 134 1.1 Editorial Notes 136 The Atom format is a work-in-progress, and this draft is both 137 incomplete and likely to change rapidly. As a result, THE FORMAT 138 DESCRIBED BY THIS DRAFT SHOULD NOT BE DEPLOYED, either in production 139 systems or in any non-experimental fashion on the Internet. 141 Discussion of this draft happens in two fora; 143 The mailing list [1] 144 The Atom Wiki Web site [2] 146 Active development takes place on the mailing list, while the Wiki is 147 used for issue tracking and new proposals. 149 This document is an early draft and known to be incomplete. Topics 150 marked [[like this]] indicate where additional text is likely to be 151 added. 153 1.2 Example 155 A minimal, single-entry Atom Feed Document: 157 158 160 161 Example Feed 162 163 2003-12-13T18:30:02Z 164 165 John Doe 166 167 168 169 Atom-Powered Robots Run Amok 170 171 vemmi://example.org/2003/32397 172 2003-12-13T18:30:02Z 173 174 176 1.3 Conformance 178 [[ talk about atom documents and atom consumers, and how requirements 179 are placed on them ]] 181 1.4 Notational Conventions 183 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 184 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 185 document are to be interpreted as described in BCP 14, [RFC2119]. 187 This specification uses XML Namespaces [W3C.REC-xml-names-19990114] 188 to uniquely identify XML elements and attribute names. It uses the 189 following namespace prefixes for the indicated namespace URIs; 191 "atom": http://purl.org/atom/ns#draft-ietf-atompub-format-03 193 Note that the choice of any namespace prefix is arbitrary and not 194 semantically significant. 196 Atom is specified using terms from the XML Infoset 197 [W3C.REC-xml-infoset-20011024]. However, this specification uses a 198 shorthand for two common terms; the phrase "Information Item" is 199 omitted when naming Element Information Items and Attribute 200 Information Items. 202 Therefore, when this specification uses the term "element," it is 203 referring to an Element Information Item in Infoset terms. Likewise, 204 when it uses the term "attribute," it is referring to an Attribute 205 Information Item. 207 2. Atom Documents 209 This specification describes two kinds of Atom Documents; Atom Feed 210 Documents and Atom Entry Documents. 212 An Atom Feed Document is a representation of an Atom feed, including 213 metadata about the feed, and some or all of the entries associated 214 with it. Its document element is atom:feed. 216 An Atom Entry Document represents exactly one Atom Entry, outside of 217 the context of an Atom Feed. Its document element is atom:entry. 219 Both kinds of Atom documents are specified in terms of the XML 220 Information Set, serialised as XML 1.0 [W3C.REC-xml-20040204] and 221 identified with the "application/atom+xml" media type. Atom 222 Documents MUST be well-formed XML. 224 [[ Validity? ]] 226 Atom constrains the appearance and content of elements and 227 attributes; unless otherwise stated, Atom Documents MAY contain other 228 Information Items as appropriate. In particular, Comment Information 229 Items and Processing Instruction Information Items SHOULD be ignored 230 in the normal processing of an Atom Document. 232 Any element in an Atom Document MAY have an xml:base attribute. XML 233 Base [W3C.REC-xmlbase-20010627] processing MUST be applied to any 234 relative URI reference present in an Atom document. This includes 235 such elements and attributes as specified by Atom itself, as well as 236 those specified by extensions to Atom. 238 Any element in an Atom Document MAY have an xml:lang attribute, whose 239 content indicates the default natural language of the element's 240 content. Requirements regarding the content and interpretation of 241 xml:lang are specified in XML 1.0 [W3C.REC-xml-20040204] Section 242 2.12. 244 [[ discussion of URI escaping and i18n ]] 246 [[ discussion of white space ]] 248 Atom is extensible. See the section titled 'Extending Atom' later in 249 this document for a full description of how Atom Documents can be 250 extended. 252 3. Common Atom Constructs 254 Many of Atom's elements share a few common structures. This section 255 defines a few such structures and their requirements, for convenient 256 reference by the appropriate element definitions. 258 When an element is identified as being a particular kind of 259 construct, it inherits the corresponding requirements from that 260 construct's definition in this section. 262 3.1 Text Constructs 264 A Text construct contains human readable text, usually in fairly 265 small quantities. 267 3.1.1 "type" Attribute 269 Text constructs MAY have a "type" attribute. When present, the value 270 MUST be one of "TEXT", "HTML" or "XHTML". If the "type" attribute is 271 not provided, software MUST behave as though it were present with a 272 value of "TEXT". 274 Note that MIME media types [RFC2045] are not acceptable values for 275 the "type" attribute. 277 If the value is "TEXT", the content of the Text construct MUST NOT 278 contain child elements. Such text is intended to be presented to 279 humans in a readable fashion. Thus, software MAY display it using 280 normal text rendering techniques such as proportional fonts, 281 white-space collapsing, and justification. 283 If the value of "type" is "HTML", the content of the Text construct 284 MUST NOT contain child elements, and SHOULD be suitable for handling 285 by software that knows HTML. The HTML markup must be encoded; for 286 example, "
" as "<br>". The HTML markup SHOULD be such that it 287 could validly appear directly within an HTML
element. 288 Receiving software which displays the content MAY use the markup to 289 aid in displaying it. 291 If the value of "type" is "XHTML", the content of the Text construct 292 MAY contain child elements. The content SHOULD be XHTML text and 293 markup that could validly appear directly within an xhtml:div 294 element. Receiving software which displays the content MAY use the 295 markup to aid in displaying it. 297 3.2 Person Constructs 299 A Person construct is an element that describes a person, 300 corporation, or similar entity. 302 Person constructs MAY be extended by namespace-qualified element 303 children. 305 This specification assigns no significance to the order of appearance 306 of the child elements of atom:entry. 308 3.2.1 "atom:name" Element 310 The "atom:name" element's content conveys a human-readable name for 311 the person. Person constructs MUST contain exactly one "atom:name" 312 element. 314 3.2.2 "atom:uri" Element 316 The "atom:uri" element's content conveys a URI associated with the 317 person. Person constructs MAY contain an atom:uri element, but MUST 318 NOT contain more than one. The content of atom:uri in a Person 319 construct MUST be a URI [RFC2396]. 321 xml:base [W3C.REC-xmlbase-20010627] processing MUST be applied to the 322 atom:uri element's content. 324 3.2.3 "atom:email" Element 326 The "atom:email" element's content conveys an e-mail address 327 associated with the persons. Person constructs MAY contain an 328 atom:email element, but MUST NOT contain more than one. Its content 329 MUST be an e-mail address [RFC2822]. 331 3.3 Date Constructs 333 A Date construct is an element whose content MUST conform to the 334 date-time BNF rule in [RFC3339]. 336 3.4 Service Constructs 338 A Service construct is an empty element that conveys the URI of an 339 Atom Publishing Protocol [Atom-protocol] service associated with an 340 entry or feed. 342 A Service construct has the following attribute: 344 3.4.1 "href" Attribute 346 The "href" attribute contains the a URI pointing to the endpoint of 347 the service named by the name attribute. atom:service elements MUST 348 have a "href" attribute, whose value MUST be a URI. 350 xml:base processing MUST be applied to the "href" attribute. 352 3.5 Link Constructs 354 A Link construct is an empty element that describes a connection from 355 an Atom document to another Web resource. 357 3.5.1 "rel" Attribute 359 The "rel" attribute indicates the type of relationship that the link 360 represents. Link constructs MAY have a rel attribute, whose value 361 MUST be a string, and MUST be one of the following values: 362 "alternate", "related". 364 If the "rel" attribute is not present, the link element MUST be 365 interpreted as if the value "alternate" had been supplied. 367 3.5.2 "type" Attribute 369 The "type" attribute indicates an advisory media type; it MAY be used 370 as a hint to determine the type of the representation which should be 371 returned when the URI in the href attribute is dereferenced. Note 372 that the type attribute does not override the actual media type 373 returned with the representation. 375 Link constructs MAY have a type attribute, whose value MUST be a 376 registered media type [RFC2045]. 378 3.5.3 "href" Attribute 380 The "href" attribute contains the link's URI. Link constructs MUST 381 have a href attribute, whose value MUST be a URI [RFC2396]. 383 xml:base [W3C.REC-xmlbase-20010627] processing MUST be applied to the 384 href attribute's content. 386 3.5.4 "hreflang" Attribute 388 The "hreflang" attribute's content describes the language of the 389 resource pointed to by the href attribute. When used together with 390 the rel="alternate", it implies a translated version of the entry. 391 Link constructs MAY have an hreflang attribute, whose value MUST be a 392 language tag [RFC3066]. 394 3.5.5 "title" Attribute 396 The "title" attribute conveys human-readable information about the 397 link. Link constructs MAY have a title attribute. 399 3.6 Identity Constructs 401 An Identity construct is an element whose content conveys a 402 permanent, universally unique identifier for the construct's parent. 403 Its content MUST be an absolute URI [RFC2396]. 405 When an Atom document is relocated, migrated, syndicated, 406 republished, exported or imported, the content of its Identity 407 construct MUST NOT change. Put another way, an Identity construct 408 pertains to all instantiations of a particular Atom entry or feed; 409 revisions retain the same content in their Identity constructs. 411 3.6.1 Dereferencing Identity Constructs 413 The content of an Identity construct MAY be dereferencable (e.g. an 414 HTTP URI). However, processors MUST NOT assume it to be 415 dereferencable. 417 The content of an Identity construct MUST be created in a way that 418 assures uniqueness, and it is suggested that the Identity construct 419 be stored along with the associated resource. 421 Because of the risk of confusion between URIs that would be 422 equivalent if dereferenced, the following normalization strategy is 423 strongly encouraged when generating Identity constructs: 425 o Provide the scheme in lowercase characters. 426 o Provide the host, if any, in lowercase characters. 427 o Only perform percent-encoding where it is essential. 428 o Use uppercase A-through-F characters when percent-encoding. 429 o Prevent dot-segments appearing in paths. 430 o For schemes that define a default authority, use an empty 431 authority if the default is desired. 432 o For schemes that define an empty path to be equivalent to a path 433 of "/", use "/". 434 o For schemes that define a port, use an empty port if the default 435 is desired. 436 o Preserve empty fragment identifiers and queries. 437 o Ensure that all portions of the URI are utf-8 encoded NFC form 438 Unicode strings. 440 3.6.2 Comparing Identity Constructs 442 Instances of Identity constructs can be compared to determine whether 443 an entry or feed is the same as one seen before. Processors MUST 444 compare Identity constructs on a character-by-character basis in a 445 case-sensitive fashion. 447 As a result, two URIs that resolve to the same resource but are not 448 character-for-character identical will be considered different for 449 the purposes of Identifier comparison. 451 For example, "http://www.example.org/thing", 452 "http://www.example.org/Thing", "http://www.EXAMPLE.org/thing" and 453 "HTTP://www.example.org/thing" will all be considered different 454 identifiers, despite their differences in case. 456 Likewise, "http://www.example.com/~bob", 457 "http://www.example.com/%7ebob" and "http://www.example.com/%7Ebob" 458 will all be considered different identifiers, because URI %-escaping 459 is significant for the purposes of comparison. 461 4. The "atom:feed" Element 463 The "atom:feed" element is the document (i.e., top-level) element of 464 an Atom Feed Document, acting as a container for metadata and data 465 associated with the feed. Its first element child MUST be atom:head, 466 which MAY be followed zero or more atom:entry child elements. 468 4.1 "version" Attribute 470 atom:feed elements MUST have a "version" attribute whose content 471 indicates the version of the Atom specification that the feed 472 conforms to. The content of this attribute is unstructured text. 474 The version identifier for this specification is 475 "draft-ietf-atompub-format-03: do not deploy". 477 4.2 The "atom:head" Element 479 The atom:head element acts as a container for metadata about the feed 480 itself. 482 The atom:head element MAY contain any namespace-qualified 483 [W3C.REC-xml-names-19990114] elements as children. This 484 specification assigns no significance to the order of appearance of 485 the child elements of atom:head. 487 The following child elements are defined by this specification (note 488 that the presence of some of these elements is required): 490 4.2.1 "atom:title" Element 492 The "atom:title" element is a Text construct that conveys a 493 human-readable title for the feed. atom:head elements MUST contain 494 exactly one atom:title element. 496 4.2.2 "atom:link" Element 498 The "atom:link" element is a Link construct that conveys a URI 499 associated with the feed. The nature of the relationship is 500 determined by the construct's rel attribute. 502 atom:head elements MUST contain at least one atom:link element with a 503 rel attribute value of "alternate". 505 atom:head elements MUST NOT contain more than one atom:link element 506 with a rel attribute value of "alternate" that has the same type 507 attribute value. 509 If a feed's atom:link element with type="alternate" resolves to an 510 HTML document, then that document SHOULD have a autodiscovery link 511 element [Atom-autodiscovery] that reflects back to the feed. 513 atom:head elements MAY contain additional atom:link elements beyond 514 those described above. 516 4.2.3 "atom:introspection" Element 518 The "atom:introspection" element is a Service construct that conveys 519 the URI of an introspection file associated with the feed. atom:head 520 elements MUST NOT contain more than one atom:introspection element. 522 4.2.4 "atom:post" Element 524 The "atom:post" element is a Service construct that conveys the URI 525 used to add entries to the feed. atom:head elements MUST NOT contain 526 more than one atom:post element. 528 4.2.5 "atom:author" Element 530 The "atom:author" element is a Person construct that indicates the 531 default author of the feed. atom:head elements MUST contain exactly 532 one atom:author element, UNLESS all of the atom:feed element's child 533 atom:entry elements contain an atom:author element. atom:head 534 elements MUST NOT contain more than one atom:author element. 536 [[explain inheritance]] 538 4.2.6 "atom:contributor" Element 540 The "atom:contributor" element is a Person construct that indicates a 541 person or other entity who contributes to the feed. atom:head 542 elements MAY contain one or more atom:contributor elements. 544 4.2.7 "atom:tagline" Element 546 The "atom:tagline" element is a Text construct that conveys a 547 human-readable description or tagline for the feed. atom:head 548 elements MAY contain an atom:tagline element, but MUST NOT contain 549 more than one. 551 4.2.8 "atom:id" Element 553 The "atom:id" element is an Identity construct that conveys a 554 permanent, universally unique identifier for a feed. atom:head 555 elements MAY contain an atom:id element, but MUST NOT contain more 556 than one. 558 4.2.9 "atom:generator" Element 560 The "atom:generator" element's content identifies the software agent 561 used to generate the feed, for debugging and other purposes. 562 atom:head elements MAY contain an atom:generator element, but MUST 563 NOT contain more than one. 565 The content of this element, when present, MUST be a string that is a 566 human-readable name for the generating agent. 568 The atom:generator element MAY have a "uri" attribute whose value 569 MUST be a URI. When dereferenced, that URI SHOULD produce a 570 representation that is relevant to that agent. 572 The atom:generator element MAY have a "version" attribute that 573 indicates the version of the generating agent. When present, its 574 value is unstructured text. 576 4.2.10 "atom:copyright" Element 578 The "atom:copyright" element is Text construct that conveys a 579 human-readable copyright statement for the feed. atom:head elements 580 MAY contain an atom:copyright element, but MUST NOT contain more than 581 one. 583 The atom:copyright element SHOULD NOT be used to convey 584 machine-readable licensing information. 586 [[Is the following paragraph bogus amateur lawyering? The first 587 paragraph seems sufficient.]] 589 The atom:copyright element may be assumed to apply to all entries 590 contained by the feed except those entries which contain 591 atom:copyright elements. The atom:copyright element MUST, if 592 present, be considered to apply to the feed as a collection of 593 entries. 595 4.2.11 "atom:info" Element 597 The "atom:info" element is a Text construct that conveys a 598 human-readable explanation of the feed format itself. atom:head 599 elements MAY contain an atom:info element, but MUST NOT contain more 600 than one. 602 The atom:info element SHOULD NOT considered meaningful by processors; 603 it is a convenience to publishers in certain situations. 605 4.2.12 "atom:updated" Element 607 The "atom:updated" element is a Date construct indicating the most 608 recent instant in time when a change to the feed was made that the 609 publisher wishes to bring to the attention of subscribers. For 610 example, such changes might not include minor adjustments like 611 spelling and grammatical corrections. 613 atom:head elements MUST contain exactly one atom:updated element. 615 5. The "atom:entry" Element 617 The "atom:entry" element represents an individual entry. This 618 element can appear as a child of the atom:feed element, or it can 619 appear as the document (i.e., top-level) element of a standalone Atom 620 Entry Document. 622 When appearing in an Atom Entry Document, atom:entry elements MUST 623 have a "version" attribute whose content indicates the version of the 624 Atom specification that the entry conforms to. 626 The version identifier for this specification is 627 "draft-ietf-atompub-format-03: do not deploy". 629 The atom:entry element MAY contain any namespace-qualified 630 [W3C.REC-xml-names-19990114] elements as children. This 631 specification assigns no significance to the order of appearance of 632 the child elements of atom:entry. 634 The following child elements are defined by this specification (note 635 that it requires the presence of some of these elements): 637 5.1 "atom:title" Element 639 The "atom:title" element is a Text construct that conveys a 640 human-readable title for the entry. atom:entry elements MUST have 641 exactly one "atom:title" element. 643 5.2 "atom:link" Element 645 The "atom:link" element is a Link construct that conveys a URI 646 associated with the entry. The nature of the relationship as well as 647 the link itself is determined by the element's content. 649 atom:entry elements MUST contain at least one atom:link element with 650 a rel attribute value of "alternate". 652 atom:entry elements MUST NOT contain more than one atom:link element 653 with a rel attribute value of "alternate" that has the same type 654 attribute value. 656 atom:entry elements MAY contain additional atom:link elements beyond 657 those described above. 659 5.3 "atom:edit" Element 661 The "atom:edit" element is a Service construct that conveys the URI 662 used to retrieve and edit the source representation of the entry. 664 atom:entry elements MUST NOT contain more than one atom:edit element. 666 5.4 "atom:author" Element 668 The "atom:author" element is a Person construct that indicates the 669 default author of the entry. atom:entry elements MUST contain 670 exactly one atom:author element, unless, in an Atom Feed Document, 671 the atom:head element contains an atom:author element itself. 672 atom:entry elements MUST NOT contain more than one atom:author 673 element. 675 5.5 "atom:contributor" Element 677 The "atom:contributor" element is a Person construct that indicates a 678 person or other entity who contributes to the entry. atom:entry 679 elements MAY contain one or more atom:contributor elements. 681 5.6 "atom:id" Element 683 The "atom:id" element is an Identity construct that conveys a 684 permanent, universally unique identifier for an entry. atom:entry 685 elements MUST contain exactly one atom:id element. 687 5.7 "atom:updated" Element 689 The "atom:updated" element is a Date construct indicating the most 690 recent instant in time when a change to the entry was made that the 691 publisher wishes to bring to the attention of subscribers. For 692 example, such changes might not include minor adjustments like 693 spelling and grammatical corrections. 695 atom:entry elements MUST contain exactly one atom:updated element. 697 Publishers MAY change the value of this element over time. 698 Processors MAY present entries sorted using this value. Processors 699 MAY choose not to present entries until the instant in time specified 700 in the atom:updated element has passed. 702 5.8 "atom:published" Element 704 The "atom:published" element is a Date construct indicating an 705 instant in time associated with an event early in the life cycle of 706 the entry. Typically, atom:published will be associated with the 707 initial creation or first availability of the resource. 709 atom:entry elements MAY contain an atom:published element, but MUST 710 NOT contain more than one. 712 Processors MAY present entries sorted using this value. Processors 713 MAY choose not to present entries until the instant in time specified 714 in the atom:published element has passed. 716 5.9 "atom:summary" Element 718 The "atom:summary" element is a Text construct that conveys a short 719 summary, abstract or excerpt of the entry. atom:entry elements MAY 720 contain an atom:summary element, but MUST NOT contain more than one. 722 atom:entry elements MUST contain an atom:summary element in any of 723 the following cases: 725 o the atom:entry element contains no atom:content element. 726 o the atom:entry contains an atom:content which has a "src" 727 attribute (and is thus empty). 728 o the atom:entry contains content which is encoded in Base64; i.e. 729 the "type" attribute of atom:content is a MIME media type 730 [RFC2045] and does not begin with "text/" nor end with "+xml". 732 5.10 "atom:content" Element 734 The "atom:content" element either contains or links to the content of 735 the entry. atom:entry elements MUST contain zero or one atom:content 736 elements. 738 5.10.1 "type" attribute 740 atom:content MAY have a "type" attribute, When present, the value MAY 741 be one of "TEXT", "HTML", or "XHTML". Failing that, it MUST be a 742 MIME media type [RFC2045] in which, to use the terminology of Section 743 5 of [RFC2045], the top level is a discrete type. If the type 744 attribute is not provided, software MUST behave as though it were 745 present with a value of "TEXT". 747 5.10.2 "src" attribute 749 atom:content MAY have a "src" attribute, whose value MUST be a URI. 750 If the "src" attribute is present, software MAY use the URI to 751 retrieve the content. If the "src" attribute is present, 752 atom:content MUST be empty. That is to say, the content may be 753 retrievable using "src=" URI, or it may be contained within 754 atom:content, but not both. 756 If the "src" attribute is present, the "type" attribute MUST be 757 provided and MUST be a MIME media type [RFC2045], rather than "TEXT", 758 "HTML", or "XHTML". The value is advisory; that is to say, upon 759 dereferencing the URI to retrieve the content, if the server 760 providing that content also provides a media type, the 761 server-provided media type is authoritative. 763 If the value of type begins with "text/" or ends with "+xml", the 764 content SHOULD be local; that is to say, no "src" attribute should be 765 provided. 767 5.10.3 Processing Model 769 Software MUST apply the following rules in succession in the order 770 below to ascertain the rules governing the content of "atom:content". 772 1. If the value is "TEXT", the content of atom:content MUST NOT 773 contain child elements. Such text is intended to be presented to 774 humans in a readable fashion. Thus, software MAY display it 775 using normal text rendering techniques such as proportional 776 fonts, white-space collapsing, and justification. 777 2. If the value of "type" is "HTML", the content of atom:content 778 MUST NOT contain child elements, and SHOULD be suitable for 779 handling by software that knows HTML. The HTML markup must be 780 encoded; for example, "
" as "<br>". The HTML markup 781 SHOULD be such that it could validly appear directly within an 782 HTML
element. Receiving software which displays the 783 content SHOULD use the markup to aid in displaying it. 784 3. If the value of "type" is "XHTML", the content of atom:content 785 MAY contain child elements. The content SHOULD be XHTML text and 786 markup that could validly appear directly within an xhtml:div 787 element. Receiving software which displays the content SHOULD 788 use the markup to aid in displaying it. 789 4. If the value of "type" ends with "+xml" or "/xml", the content of 790 atom:content may include child elements, and SHOULD be suitable 791 for handling by software that knows the indicated media type. If 792 the "src" attribute is not provided, this would normally mean 793 that the "atom:content" element would contain a single child 794 element which would serve as the root element of the XML document 795 of the indicated type. 796 5. If the value of "type" begins with "text/" the content of 797 atom:content MUST NOT contain child elements. 798 6. For all other values of "type", the content of atom:content MUST 799 be a valid Base64 encoding [RFC3548], which when decoded SHOULD 800 be suitable for handling by software that knows the indicated 801 media type. In this case, the characters in the Base64 encoding 802 may be preceded and followed in the atom:content element by 803 whitespace, and lines are separated by a single newline (U+000A) 804 character, as required by XML. 806 5.11 "atom:copyright" Element 808 The "atom:copyright" element is a Text construct that conveys a 809 human-readable copyright statement for the entry. atom:entry 810 elements MAY contain an atom:copyright element, but MUST NOT contain 811 more than one. 813 The atom:copyright element SHOULD NOT be used to convey 814 machine-readable licensing information. 816 If an atom:entry element does not contain an atom:copyright element, 817 then the atom:copyright element of the containing atom:feed element's 818 atom:head element, if present, should be considered to apply to the 819 entry. 821 5.12 "atom:origin" Element 823 The "atom:origin" element's content conveys the original source of 824 the entry; e.g., the feed where the entry was first published. 826 If the source is an Atom Feed Document, then the content of 827 atom:origin MUST be the same, character-for-character, as that of the 828 atom:id element in that document's atom:head section (i.e., the XPath 829 expression "/atom:feed/atom:head/atom:id"). 831 The content of this element MUST be a URI. atom:entry elements MAY 832 contain an atom:origin element, but MUST NOT contain more than one. 834 6. Managing Feed State 836 [[ talk about what it means to keep a view of a feed ]] 838 7. Securing Atom Documents 840 Because Atom is an XML-based format, existing XML security mechanisms 841 can be used to secure its content. 843 Note that while these mechanisms are available to secure Atom 844 documents, they should not be used indiscriminately. 846 7.1 Digital Signatures 848 The document element of an Atom document (i.e., atom:feed in an Atom 849 Feed Document, atom:entry in an Atom Entry Document) MAY have an 850 Enveloped Signature, as described by XML-Signature and Syntax 851 Processing [W3C.REC-xmldsig-core-20020212]. Other XML signature 852 mechanisms MUST NOT be used on the document element of an Atom 853 document. 855 Processors MUST NOT reject an Atom document containing such a 856 signature because they are not capable of verifying it; they MUST 857 continue processing and MAY inform the user of their failure to 858 validate the signature. 860 In other words, the presence of an element with the namespace URI 861 "http://www.w3.org/2000/09/xmldsig#" and a local name of "Signature" 862 as a child of the document element must not cause a processor to fail 863 merely because of its presence. 865 Other elements in an Atom document MUST NOT be signed unless their 866 definitions explicitly specify such a capability. 868 7.2 Encryption 870 The document element of an Atom document (i.e., atom:feed in an Atom 871 Feed Document, atom:entry in an Atom Entry Document) MAY be 872 encrypted, using the mechanisms described by XML Encryption Syntax 873 and Processing [W3C.REC-xmlenc-core-20021210]. Other XML encryption 874 mechanisms MUST NOT be used on the document element of an Atom 875 document. 877 8. Embedding Atom in Other Formats 879 [[ ... ]] 881 9. Extending Atom 883 [[ ... ]] 885 10. IANA Considerations 887 An Atom Document, when serialized as XML 1.0, can be identified with 888 the following media type: 890 MIME media type name: application 891 MIME subtype name: atom+xml 892 Mandatory parameters: None. 893 Optional parameters: 894 "charset": This parameter has identical semantics to the charset 895 parameter of the "application/xml" media type as specified in 896 RFC 3023 [RFC3023]. [RFC3023]. 897 Encoding considerations: Identical to those of "application/xml" as 898 described in RFC 3023 [RFC3023], section 3.2. 899 Security considerations: As defined in this specification. [[update 900 upon publication]] 901 In addition, as this media type uses the "+xml" convention, it 902 shares the same security considerations as described in RFC 3023 903 [RFC3023], section 10. 904 Interoperability considerations: There are no known interoperability 905 issues. 906 Published specification: This specification. [[update upon 907 publication]] 908 Applications which use this media type: No known applications 909 currently use this media type. 911 Additional information: 913 Magic number(s): As specified for "application/xml" in RFC 3023 914 [RFC3023], section 3.2. 915 File extension: .atom 916 Fragment identifiers: As specified for "application/xml" in RFC 3023 917 [RFC3023], section 5. 918 Base URI: As specified in RFC 3023 [RFC3023], section 6. 919 Macintosh File Type code: TEXT 920 Person and email address to contact for further information: Mark 921 Nottingham 922 Intended usage: COMMON 923 Author/Change controller: This specification's author(s). [[update 924 upon publication]] 926 11. Security Considerations 928 Atom document can be encrypted and signed using 929 [W3C.REC-xmlenc-core-20021210] and [W3C.REC-xmldsig-core-20020212], 930 respectively, and is subject to the security considerations implied 931 by their use. 933 12 Normative References 935 [Atom-autodiscovery] 936 Pilgrim, M., "Atom Feed Autodiscovery", work-in-progress, 937 August 2004. 939 [Atom-protocol] 940 Gregorio, J. and R. Sayre, "The Atom Publishing Protocol", 941 work-in-progress, July 2004. 943 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 944 Extensions (MIME) Part One: Format of Internet Message 945 Bodies", RFC 2045, November 1996. 947 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 948 Requirement Levels", BCP 14, RFC 2119, March 1997. 950 [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 951 Resource Identifiers (URI): Generic Syntax", RFC 2396, 952 August 1998. 954 [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April 955 2001. 957 [RFC3023] Murata, M., St. Laurent, S. and D. Kohn, "XML Media 958 Types", RFC 3023, January 2001. 960 [RFC3066] Alvestrand, H., "Tags for the Identification of 961 Languages", BCP 47, RFC 3066, January 2001. 963 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 964 Timestamps", RFC 3339, July 2002. 966 [RFC3548] Josefsson, S., "The Base16, Base32, and Base64 Data 967 Encodings", RFC 3548, July 2003. 969 [W3C.NOTE-datetime-19980827] 970 Wolf, M. and C. Wicksteed, "Date and Time Formats", W3C 971 NOTE NOTE-datetime-19980827, August 1998. 973 [W3C.REC-xml-20040204] 974 Yergeau, F., Paoli, J., Sperberg-McQueen, C., Bray, T. and 975 E. Maler, "Extensible Markup Language (XML) 1.0 (Third 976 Edition)", W3C REC REC-xml-20040204, February 2004. 978 [W3C.REC-xml-infoset-20011024] 979 Tobin, R. and J. Cowan, "XML Information Set", W3C 980 FirstEdition REC-xml-infoset-20011024, October 2001. 982 [W3C.REC-xml-names-19990114] 983 Hollander, D., Bray, T. and A. Layman, "Namespaces in 984 XML", W3C REC REC-xml-names-19990114, January 1999. 986 [W3C.REC-xmlbase-20010627] 987 Marsh, J., "XML Base", W3C REC REC-xmlbase-20010627, June 988 2001. 990 [W3C.REC-xmldsig-core-20020212] 991 Solo, D., Reagle, J. and D. Eastlake, "XML-Signature 992 Syntax and Processing", W3C REC REC-xmldsig-core-20020212, 993 February 2002. 995 [W3C.REC-xmlenc-core-20021210] 996 Reagle, J. and D. Eastlake, "XML Encryption Syntax and 997 Processing", W3C REC REC-xmlenc-core-20021210, December 998 2002. 1000 [1] 1002 [2] 1004 Authors' Addresses 1006 Mark Nottingham (editor) 1008 EMail: mnot@pobox.com 1009 URI: http://www.mnot.net/ 1011 Robert Sayre (editor) 1012 Boswijck Memex Consulting 1014 EMail: rfsayre@boswijck.com 1015 URI: http://boswijck.com 1017 Appendix A. Contributors 1019 The following people contributed to preliminary drafts of this 1020 document: Tim Bray, Mark Pilgrim, and Sam Ruby. The content and 1021 concepts within are a product of the Atom community and the Atom 1022 Publishing Format and Protocol Working Group. 1024 Appendix B. Revision History 1026 [[ this section should be removed before final publication. ]] 1028 -03: Move definition of Link @rel to format spec, restrict 1029 acceptable values (PaceMoveLinkElement, PaceLinkAttrDefaults). 1030 Add Service Construct, head/post, head/introspection, entry/edit 1031 (PaceServiceElement). 1032 Add Text Construct, entry/content (PaceReformedContent3). 1033 Add entry/published (PaceDatePublished). 1034 Adjust definition of Identity Construct per chairs' direction to 1035 "fix it." 1036 Add Sayre to editors. 1037 -02: Removed entry/modified, entry/issued, entry/created; added 1038 entry/updated (PaceDateUpdated). 1039 Changed date construct from W3C date-time to RFC3339 1040 (PaceDateUpdated). 1041 Feed links to HTML pages should be reflected back 1042 (PaceLinkReflection). 1043 Added Identity construct (PaceIdConstruct). 1044 Changed feed/id and entry/id to be Identity constructs 1045 (PaceIdConstruct). 1046 Changed entry/origin's content so that it's the same as the feed's 1047 id, rather than its link/@rel="alternate" (PaceIdConstruct). 1048 Added "Securing Atom Documents" (PaceDigitalSignatures). 1049 -01: Constrained omission of "Information Item" to just elements and 1050 attributes. 1051 Clarified xml:lang inheritence. 1052 Removed entry- and feed-specific langauge about xml:lang (covered 1053 by general discussion of xml:lang) 1054 Changed xml:lang to reference XML for normative requirements. 1055 Changed "... MUST be a string" to "... is unstructued text." 1056 Remomved langauge about DOCTYPEs, PIs, Comments, Entities. 1057 Changed atom:url to atom:uri, @url to @uri 1058 Introduced atom:head 1059 Introduced "Atom Feed Document" and "Atom Entry Document". 1060 Removed requirement for all elements and attributes to be 1061 namespace-qualified; now children of selective elements 1062 Added extensibility to Person constructs. 1063 Removed requirement for media types to be registered 1064 (non-registered media types are legal) 1065 Added atom:origin (PaceEntryOrigin) 1066 Added requirement for entry/id to be present and a URI 1067 (PaceEntryIdRequired). 1068 Clarified approach to Comments, PIs and well-formedness, as per 1069 RFC3470. 1071 Referenced escaping algorithm in XML. 1072 Assorted editorial nits and cleanup, refactoring 1073 -00: Initial IETF Internet-Draft submission. 1074 Added optional version attribute to entry 1075 (PaceEntryElementNeedsVersionAttribute). 1076 Added hreflang attribute (PaceHrefLang). 1077 Clarified inheritence of copyright element (PaceItemCopyright). 1078 Added xml:lang to entries (PaceItemLang). 1079 Tweaked Infoset-related language (PaceNoInfoSet). 1080 Clarified lack of structure in version attribute 1081 (PaceVersionAsText). 1082 Changed approach to XML Base (PaceXmlBaseEverywhere). 1083 Added XML Base processing to atom:id (PaceXmlBaseId). 1084 Various editorial cleanup and adjustments for IETF publication. 1086 Intellectual Property Statement 1088 The IETF takes no position regarding the validity or scope of any 1089 Intellectual Property Rights or other rights that might be claimed to 1090 pertain to the implementation or use of the technology described in 1091 this document or the extent to which any license under such rights 1092 might or might not be available; nor does it represent that it has 1093 made any independent effort to identify any such rights. Information 1094 on the procedures with respect to rights in RFC documents can be 1095 found in BCP 78 and BCP 79. 1097 Copies of IPR disclosures made to the IETF Secretariat and any 1098 assurances of licenses to be made available, or the result of an 1099 attempt made to obtain a general license or permission for the use of 1100 such proprietary rights by implementers or users of this 1101 specification can be obtained from the IETF on-line IPR repository at 1102 http://www.ietf.org/ipr. 1104 The IETF invites any interested party to bring to its attention any 1105 copyrights, patents or patent applications, or other proprietary 1106 rights that may cover technology that may be required to implement 1107 this standard. Please address the information to the IETF at 1108 ietf-ipr@ietf.org. 1110 Disclaimer of Validity 1112 This document and the information contained herein are provided on an 1113 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1114 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1115 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1116 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1117 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1118 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1120 Copyright Statement 1122 Copyright (C) The Internet Society (2004). This document is subject 1123 to the rights, licenses and restrictions contained in BCP 78, and 1124 except as set forth therein, the authors retain all their rights. 1126 Acknowledgment 1128 Funding for the RFC Editor function is currently provided by the 1129 Internet Society.