idnits 2.17.1 draft-snell-atompub-link-extensions-01.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 599. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 576. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 583. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 589. ** 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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. 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 (December 8, 2005) is 6714 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) == Missing Reference: 'TM' is mentioned on line 546, but not defined ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Snell 3 Internet-Draft December 8, 2005 4 Expires: June 11, 2006 6 Atom Syndication Format Link Extensions 7 draft-snell-atompub-link-extensions-01.txt 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 June 11, 2006. 34 Copyright Notice 36 Copyright (C) The Internet Society (2005). 38 Abstract 40 This specification defines extensions to the Atom Syndication Format 41 link and content elements that may be used to express additional 42 metadata about linked resources. 44 Table of Contents 46 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 47 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 48 3. Entity Attributes . . . . . . . . . . . . . . . . . . . . . . 3 49 3.1. The 'md5' Attribute . . . . . . . . . . . . . . . . . . . 3 50 3.2. The 'etag' Attribute . . . . . . . . . . . . . . . . . . . 4 51 3.3. The 'last-modified' Attribute . . . . . . . . . . . . . . 4 52 3.4. The 'range' Attribute . . . . . . . . . . . . . . . . . . 5 53 4. Media Descriptors . . . . . . . . . . . . . . . . . . . . . . 6 54 4.1. The 'media' Attribute . . . . . . . . . . . . . . . . . . 6 55 5. Link Grouping and Alternates . . . . . . . . . . . . . . . . . 7 56 5.1. The 'group' Attribute . . . . . . . . . . . . . . . . . . 8 57 5.2. The 'alternate' Element . . . . . . . . . . . . . . . . . 8 58 6. Link Decoration . . . . . . . . . . . . . . . . . . . . . . . 9 59 6.1. The 'description' Element . . . . . . . . . . . . . . . . 9 60 6.2. The 'icon' Element . . . . . . . . . . . . . . . . . . . . 9 61 7. Link Relations . . . . . . . . . . . . . . . . . . . . . . . . 10 62 7.1. Hierarchy Links . . . . . . . . . . . . . . . . . . . . . 10 63 7.2. Informational Links . . . . . . . . . . . . . . . . . . . 11 64 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 65 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 66 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 67 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15 69 Intellectual Property and Copyright Statements . . . . . . . . . . 16 71 1. Introduction 73 This specification defines extensions to the Atom Syndication Format 74 [RFC4287] link and content elements that may be used to express 75 additional metadata about linked resources. 77 2. Notational Conventions 79 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 80 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 81 document are to be interpreted as described in BCP 14, [RFC2119] 83 This specification uses XML Namespaces [W3C.REC-xml-names-19990114] 84 to uniquely identify XML element names. It uses the following 85 namespace prefix for the indicated namespace URI; 87 {Ed. Note: this namespace MUST be changed to a proper IETF namespace 88 scheme prior to publication} 90 "le": "http://purl.org/atompub/link-extensions/1.0" 92 3. Entity Attributes 94 The following link Entity Attributes may be used to specify metadata 95 about the resource referenced by an atom:link element or atom:content 96 element using the 'src' attribute. The attributes are designed to 97 closely correlate with existing HTTP [RFC2616] mechanisms used to 98 perform conditional operations, detecting resource modifications and 99 requesting ranges. 101 3.1. The 'md5' Attribute 103 The 'md5' Attribute specifies a Base64-encoded MD5 digest [RFC1864] 104 of the resource identified by the atom:link/@href or atom:content/@ 105 src attributes. The value of the digest is calculated as specified 106 in [RFC2616] and [RFC1864]. The 'md5' attribute MAY appear as a 107 child of the atom:link and atom:content (using the 'src' attribute) 108 elements. 110 md5 = attribute le:md5 { md5-digest } 112 md5-digest = 114 While MD5 digests are not a guarantee against malicious modifications 115 of a resource, the digest specified may be used as a simple integrity 116 check to verify whether or not the referenced resource may have been 117 modified. 119 An example MD5 digest of an enclosed MP3 file 121 125 3.2. The 'etag' Attribute 127 The 'etag' Attribute specifies an Entity Tag [RFC2616] for the 128 resource identified by the atom:link or atom:content element. The 129 'etag' attribute MAY appear as a child of the atom:link and atom: 130 content (using the 'src' attribute) elements. 132 etag = attribute le:etag { entity-tag } 134 entity-tag = [ weak ] opaque-tag 135 weak = "W/" 136 opaque-tag = quoted-string 138 As specified by [RFC2616], Entity Tags are usable for the purpose of 139 comparing multiple entities served from the same resource URI and are 140 typically used in the context of conditional-retrievals of resource 141 representations. 143 An example Entity Tag for an enclosed MP3 file 145 149 3.3. The 'last-modified' Attribute 151 The 'last-modified' Attribute specifies the date and time when the 152 resource identified by the atom:link or atom:content element was last 153 modified as specified by [RFC2616]. The value of the attribute must 154 conform to the HTTP-date construct from [RFC2616]. The 'last- 155 modified' attribute MAY appear as a child of the atom:link and atom: 156 content (using the 'src' attribute) elements. 158 last-modified = attribute le:last-modified { HTTP-date } 160 HTTP-date = rfc1123-date | rfc850-date | asctime-date 161 rfc1123-date = wkday "," SP date1 SP time SP "GMT" 162 rfc850-date = weekday "," SP date2 SP time SP "GMT" 163 asctime-date = wkday SP date3 SP time SP 4DIGIT 164 date1 = 2DIGIT SP month SP 4DIGIT 165 ; day month year (e.g., 02 Jun 1982) 166 date2 = 2DIGIT "-" month "-" 2DIGIT 167 ; day-month-year (e.g., 02-Jun-82) 168 date3 = month SP ( 2DIGIT | ( SP 1DIGIT )) 169 ; month day (e.g., Jun 2) 170 time = 2DIGIT ":" 2DIGIT ":" 2DIGIT 171 ; 00:00:00 - 23:59:59 172 wkday = "Mon" | "Tue" | "Wed" 173 | "Thu" | "Fri" | "Sat" | "Sun" 174 weekday = "Monday" | "Tuesday" | "Wednesday" 175 | "Thursday" | "Friday" | "Saturday" | "Sunday" 176 month = "Jan" | "Feb" | "Mar" | "Apr" 177 | "May" | "Jun" | "Jul" | "Aug" 178 | "Sep" | "Oct" | "Nov" | "Dec" 180 An example last-modified attribute for an enclosed MP3 file 182 186 3.4. The 'range' Attribute 188 The 'range' Attribute specifies a subset of the resource identified 189 by the atom:link or atom:content element as specified by the standard 190 HTTP Range header defined by [RFC2616]. The 'range' attribute MAY 191 appear as a child of the atom:link and atom:content (using the 'src' 192 attribute) elements. 194 range = attribute le:range { ranges-specifier } 196 ranges-specifier = byte-ranges-specifier 197 byte-ranges-specifier = bytes-unit "=" byte-range-set 198 byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec ) 199 byte-range-spec = first-byte-pos "-" [last-byte-pos] 200 first-byte-pos = 1*DIGIT 201 last-byte-pos = 1*DIGIT 203 The only Range Specifier defined by [RFC2616] is the "bytes" range 204 specifier used to request a specific sequence of bytes from a 205 resource. Other range specifiers MAY be used. Unknown range 206 specifiers SHOULD be ignored. 208 An example range attribute specifying the first 500 bytes of an 209 enclosed MP3 file 211 215 4. Media Descriptors 217 Resources referenced by atom:link and atom:content elements may be 218 optimized for rendering on specific types of devices. 220 4.1. The 'media' Attribute 222 The 'media' attribute MAY be used to identify the types of devices 223 for which a resource referenced by an atom:link or atom:content 224 (using the src attribute) has been targeted. The definition of the 225 media attribute is the same as the 'media' attribute on HTML 226 [W3C.REC-html401-19991224] and XHTML [W3C.REC-xhtml1-20020801] link 227 elements. The 'media' attribute MAY appear as a child of the atom: 228 link and atom:content elements. 230 media = attribute le:media { media-descriptors } 232 The value of the 'media' attribute is a comma separated list of 233 media-descriptor tokens. If not specified, the value of attribute is 234 assumed to be "all". The following lists the standard media- 235 descriptor definitions as specified by [W3C.REC-html401-19991224]. 237 screen 238 intended for non-paged computer screens 240 tty 241 intended for media using a fixed-pitch character 242 grid, such as teletypes, terminals, or portable 243 devices with limited display capabilities. 245 tv 246 intended for television-type devices (low-resolution, 247 color, limited scrollability). 249 projection 250 intended for projectors 252 handheld 253 intended for handheld devices (small screen, 254 monochrome, bitmapped graphics, limited bandwidth). 256 print 257 intended for paged, opaque material and for documents 258 viewed on screen in print preview mode 260 braille 261 intended for braille tactile feedback devices. 263 aural 264 intended for speech synthesizers 266 all 267 suitable for all devices 269 Two alternate atom:link elements respectively targeted at screen and 270 handheld devices 272 275 279 5. Link Grouping and Alternates 281 The Link Grouping and Alternate mechanisms defined below make it 282 possible to group related atom:link elements into logical sets or to 283 identify alternate IRI's (e.g. mirrors) for linked resources. 285 5.1. The 'group' Attribute 287 The 'group' Attribute MAY appear as a child of atom:link elements and 288 MAY be used to group associated links together into a logical set of 289 mutually-exclusive options. The value of the attribute is a case- 290 insensitive, opaque text string. Link elements with 'group' 291 attributes specifying the same value are considered to belong to the 292 same logical set. 294 group = attribute le:group { text } 296 The following illustrates an example of how the 'group' attribute may 297 be used to identify alternate encodings of the same enclosed audio 298 content. 300 303 307 Comparison operations on the 'group' attribute are performed using a 308 case-insensitive character-by-character examination. Entity 309 encodings MUST be interpreted as the character they represent. For 310 instance, The value "group" is equivalent to "group", "Group", 311 "GROUP", etc. The value " " is equivalent to the character 312 string " " (that is, an ampersand followed by the characters "nbsp;") 313 and MUST NOT be interpreted as markup. 315 5.2. The 'alternate' Element 317 The 'alternate' Element is used to specify one or more alternative 318 IRI's for the resource identified by an atom:link element. For 319 instance, an enclosure referenced by a link may be downloadable from 320 multiple mirror locations. The 'alternate' Element consists of an 321 IRI and optional language-sensitive text label. Zero or more 322 'alternate' elements MAY appear as children of the atom:link element. 323 The parent link element's 'type', 'length' and 'hreflang' attributes 324 are considered to apply equally to each of the contained 'alternate' 325 elements. 327 alternate = element le:alternate { 328 atomCommonAttributes, 329 attribute href, 330 attribute title?, 331 (undefinedContent) 332 } 334 An example atom:link that specifies two alternate download locations 335 for the enclosed MP3 file 337 340 342 344 346 6. Link Decoration 348 6.1. The 'description' Element 350 The 'description' element is an Atom Text Construct that is used to 351 associate a short, human-readable textual summary with an atom:link 352 element. 354 description = element le:description { atomTextConstruct } 356 An example atom:link element with an associated description. 358 360 361 My first podcast. Isn't it great! 362 363 365 6.2. The 'icon' Element 367 The 'icon' element identifies an image that provides an iconic visual 368 identification for an atom:link. Like the standard atom:icon 369 element, which is used to associate an icon image with Atom Feed 370 Documents, images referenced by the 'icon' element SHOULD have a 371 1-to-1 aspect ratio and be suitable for presentation at a small size. 372 The element MAY contain an optional 'type' attribute whose value 373 specifies the media-type of the referenced icon. 375 icon = element le:icon { 376 atomCommonAttributes, 377 attribute type { media-type }?, 378 (atomURI) 379 } 381 An example atom:link element with an associated PNG icon 383 385 http://example.org/icons/podcast.png 386 388 7. Link Relations 390 This specification adds the following values to the IANA Registry of 391 Link Relations as specified by [RFC4287]. 393 7.1. Hierarchy Links 395 The Hierarchy Link Relations may be used to organize Atom Feed and 396 Entry documents into a hierarchical tree. 398 o link[@rel='origin'] : The 'origin' link refers to the logical root 399 of a hierarchical tree of entities. 400 o link[@rel='parent'] : The 'parent' link refers to the logical 401 parent of the current entity in a hierarchical tree of entities. 402 o link[@rel='child'] : The 'child' link refers to a logical 403 subordinate of the current document in a hierarchical tree of 404 entities. 405 o link[@rel='sibling'] : The 'sibling' link refers to a logical 406 sibling of the current document in a hierarchical tree of 407 entities. 409 An example of an Atom document hierarchy 411 412 413 414 ... 415 417 419 421 422 423 424 426 428 430 432 434 435 436 437 439 441 443 7.2. Informational Links 445 The following link relations may be used to reference informational 446 resources about the containing Atom Feed or Entry. 448 o link[@rel='help'] : The 'help' link may be used to reference 449 resources offering help information for the containing Feed or 450 Entry. 451 o link[@rel='about'] : The 'about' link may be used to reference 452 resources offering additional information about the containing 453 Feed or Entry. 455 An Atom Feed with help and about links 457 458 ... 459 461 463 ... 464 466 8. Security Considerations 468 While the mechanisms defined herein may be used to detect potentially 469 malicious modifications of referenced resources, the mechanisms MUST 470 NOT be considered to provide a guarantee against inappropriate 471 modification. Other mechanisms, such as XML Digital Signatures and 472 XML Encryption should be used to properly secure Atom documents. 474 9. IANA Considerations 476 This specification adds the following registrations to the IANA 477 Registry of link relations: 479 Attribute Value: origin 480 Description: The 'origin' link refers to the logical root 481 of a hierarchical tree of entities. 482 Expected display characteristics: none 483 Security considerations: As defined in [RFC4287] 485 Attribute Value: parent 486 Description: The 'parent' link refers to the logical parent 487 of the current entity in a hierarchical tree of 488 entities. 489 Expected display characteristics: none 490 Security considerations: As defined in [RFC4287] 492 Attribute Value: child 493 Description: The 'child' link refers to a logical subordinate 494 of the current document in a hierarchical tree 495 of entities. 496 Expected display characteristics: none 497 Security considerations: As defined in [RFC4287] 498 Attribute Value: sibling 499 Description: The 'sibling' link refers to a logical sibling of 500 the current document in a hierarchical tree of 501 entities. 502 Expected display characteristics: none 503 Security considerations: As defined in [RFC4287] 505 Attribute Value: help 506 Description: The 'help' link may be used to reference resources 507 offering help information for the containing Feed 508 or Entry. 509 Expected display characteristics: none 510 Security considerations: As defined in [RFC4287] 512 Attribute Value: about 513 Description: The 'about' link may be used to reference 514 resources offering additional information 515 about the containing Feed or Entry. 516 Expected display characteristics: none 517 Security considerations: As defined in [RFC4287] 519 10. Acknowledgements 521 The author gratefully acknowledges the feedback from the members of 522 the Atom Publishing Format and Protocol working group during the 523 development of this specification. 525 11. References 527 [RFC1864] Myers, J. and M. Rose, "The Content-MD5 Header Field", 528 RFC 1864, October 1995. 530 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 531 Requirement Levels", BCP 14, RFC 2119, March 1997. 533 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 534 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 535 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 537 [RFC4287] Nottingham, M. and R. Sayre, "The Atom Syndication 538 Format", RFC 4287, December 2005. 540 [W3C.REC-html401-19991224] 541 Hors, A., Jacobs, I., and D. Raggett, "HTML 4.01 542 Specification", W3C REC REC-html401-19991224, 543 December 1999. 545 [W3C.REC-xhtml1-20020801] 546 Pemberton, S., "XHTML[TM] 1.0 The Extensible HyperText 547 Markup Language (Second Edition)", W3C REC REC-xhtml1- 548 20020801, August 2002. 550 [W3C.REC-xml-infoset-20040204] 551 Tobin, R. and J. Cowan, "XML Information Set (Second 552 Edition)", W3C REC REC-xml-infoset-20040204, 553 February 2004. 555 [W3C.REC-xml-names-19990114] 556 Hollander, D., Bray, T., and A. Layman, "Namespaces in 557 XML", W3C REC REC-xml-names-19990114, January 1999. 559 Author's Address 561 James M Snell 563 Phone: 564 Email: jasnell@gmail.com 565 URI: http://snellspace.com 567 Intellectual Property Statement 569 The IETF takes no position regarding the validity or scope of any 570 Intellectual Property Rights or other rights that might be claimed to 571 pertain to the implementation or use of the technology described in 572 this document or the extent to which any license under such rights 573 might or might not be available; nor does it represent that it has 574 made any independent effort to identify any such rights. Information 575 on the procedures with respect to rights in RFC documents can be 576 found in BCP 78 and BCP 79. 578 Copies of IPR disclosures made to the IETF Secretariat and any 579 assurances of licenses to be made available, or the result of an 580 attempt made to obtain a general license or permission for the use of 581 such proprietary rights by implementers or users of this 582 specification can be obtained from the IETF on-line IPR repository at 583 http://www.ietf.org/ipr. 585 The IETF invites any interested party to bring to its attention any 586 copyrights, patents or patent applications, or other proprietary 587 rights that may cover technology that may be required to implement 588 this standard. Please address the information to the IETF at 589 ietf-ipr@ietf.org. 591 Disclaimer of Validity 593 This document and the information contained herein are provided on an 594 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 595 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 596 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 597 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 598 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 599 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 601 Copyright Statement 603 Copyright (C) The Internet Society (2005). This document is subject 604 to the rights, licenses and restrictions contained in BCP 78, and 605 except as set forth therein, the authors retain all their rights. 607 Acknowledgment 609 Funding for the RFC Editor function is currently provided by the 610 Internet Society.