idnits 2.17.1 draft-johnston-http-category-header-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 29, 2011) is 4593 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2068 (Obsoleted by RFC 2616) -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force S. Johnston 3 Internet-Draft Open Cloud Initiative 4 Intended status: Experimental September 29, 2011 5 Expires: April 1, 2012 7 Web Categories 8 draft-johnston-http-category-header-02 10 Abstract 12 This document specifies the Category header-field for HyperText 13 Transfer Protocol (HTTP), which enables the sending of taxonomy 14 information in HTTP headers in a similar fashion to that employed by 15 Atom. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on April 1, 2012. 34 Copyright Notice 36 Copyright (c) 2011 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.1. Requirements Language . . . . . . . . . . . . . . . . . . . 3 53 2. Categories . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3. The Category Header Field . . . . . . . . . . . . . . . . . . . 4 55 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 57 4.1. Category Header Registration . . . . . . . . . . . . . . . 5 58 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 59 6. Internationalisation Considerations . . . . . . . . . . . . . . 5 60 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 7.1. Normative References . . . . . . . . . . . . . . . . . . . 6 62 7.2. Informative References . . . . . . . . . . . . . . . . . . 6 63 Appendix A. Notes on use with HTML . . . . . . . . . . . . . . . . 7 64 Appendix B. Notes on use with Atom . . . . . . . . . . . . . . . . 7 65 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . . 8 66 Appendix D. Change Log (to be removed by RFC Editor before 67 publication) . . . . . . . . . . . . . . . . . . . . . 8 68 D.1. draft-johnston-http-category-header-00 . . . . . . . . . . 8 69 D.2. draft-johnston-http-category-header-01 . . . . . . . . . . 8 70 D.3. draft-johnston-http-category-header-02 . . . . . . . . . . 8 71 Appendix E. Outstanding Issues . . . . . . . . . . . . . . . . . . 8 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 1. Introduction 76 A means of indicating categories for resources on the web has been 77 defined by Atom [RFC4287]. This document defines a framework for 78 exposing category information in the same format via HTTP headers. 80 The atom:category element conveys information about a category 81 associated with an entry or feed. A given atom:feed or atom:entry 82 element MAY have zero or more categories which MUST have a "term" 83 attribute (a string that identifies the category to which the entry 84 or feed belongs) and MAY also have a scheme attribute (an IRI that 85 identifies a categorization scheme) and/or a label attribute (a 86 human-readable label for display in end-user applications). 88 Similarly a web resource may be associated with zero or more 89 categories as indicated in the Category header-field(s). These 90 categories may be divided into separate vocabularies or "schemes" 91 and/or accompanied with human-friendly labels. 93 [[ Feedback is welcome on the ietf-http-wg@w3.org mailing list, 94 although this is NOT a work item of the HTTPBIS WG. ]] 96 1.1. Requirements Language 98 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 99 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 100 document are to be interpreted as described in BCP 14, [RFC2119], as 101 scoped to those conformance targets. 103 This document uses the Augmented Backus-Naur Form (ABNF) notation of 104 [RFC2616], and explicitly includes the following rules from it: 105 quoted-string, token. Additionally, the following rules are included 106 from [RFC3986]: URI. 108 2. Categories 110 In this specification, a category is a grouping of resources by 111 'term', from a vocabulary ('scheme') identified by an IRI [RFC3987]. 112 It is comprised of: 114 o A "term" which is a string that identifies the category to which 115 the resource belongs. 117 o A "scheme" which is an IRI that identifies a categorization scheme 118 (optional). 120 o An "label" which is a human-readable label for display in end-user 121 applications (optional). 123 A category can be viewed as a statement of the form "resource is from 124 the {term} category of {scheme}, to be displayed as {label}", for 125 example "'Loewchen' is from the 'dog' category of 'animals', to be 126 displayed as 'Canine'". 128 3. The Category Header Field 130 The Category entity-header provides a means for serialising one or 131 more categories in HTTP headers. It is semantically equivalent to 132 the atom:category element in Atom [RFC4287]. 134 Category = "Category" ":" #category-value 135 category-value = term *( ";" category-param ) 136 category-param = ( ( "scheme" "=" <"> scheme <"> ) 137 | ( "label" "=" quoted-string ) 138 | ( "label*" "=" enc2231-string ) 139 | ( category-extension ) ) 140 category-extension = token [ "=" ( token | quoted-string ) ] 141 enc2231-string = 142 term = token 143 scheme = URI 145 Each category-value conveys exactly one category but there may be 146 multiple category-values for each header-field and/or multiple 147 header-fields per [RFC2616]. 149 Note that schemes are REQUIRED to be absolute URLs in Category 150 headers, and MUST be quoted if they contain a semicolon (";") or 151 comma (",") as these characters are used to separate category-params 152 and category-values respectively. 154 The "label" parameter is used to label the category such that it can 155 be used as a human-readable identifier (e.g. a menu entry). 156 Alternately, the "label*" parameter MAY be used encode this label in 157 a different character set, and/or contain language information as per 158 [RFC2231]. When using the enc2231-string syntax, producers MUST NOT 159 use a charset value other than 'ISO-8859-1' or 'UTF-8'. 161 3.1. Examples 163 NOTE: Non-ASCII characters used in prose for examples are encoded 164 using the format "Backslash-U with Delimiters", defined in Section 165 5.1 of [RFC5137]. 167 For example: 168 Category: dog 170 indicates that the resource is in the "dog" category. 171 Category: dog; label="Canine"; scheme="http://purl.org/net/animals" 173 indicates that the resource is in the "dog" category, from the 174 "http://purl.org/net/animals" scheme, and should be displayed as 175 "Canine". 177 The example below shows an instance of the Category header encoding 178 multiple categories, and also the use of [RFC2231] encoding to 179 represent both non-ASCII characters and language information. 180 Category: dog; label="Canine"; scheme="http://purl.org/net/animals", 181 lowchen; label*=UTF-8'de'L%c3%b6wchen"; 182 scheme="http://purl.org/net/animals/dogs" 184 Here, the second category has a label encoded in UTF-8, uses the 185 German language ("de"), and contains the Unicode code point \u'00F6' 186 ("LATIN SMALL LETTER O WITH DIAERESIS"). 188 4. IANA Considerations 190 4.1. Category Header Registration 192 This specification adds an entry for "Category" in HTTP to the 193 Message Header Registry [RFC3864] referring to this document: 194 Header Field Name: Category 195 Protocol: http 196 Status: standard 197 Author/change controller: 198 IETF (iesg@ietf.org) 199 Internet Engineering Task Force 200 Specification document(s): 201 [ this document ] 203 5. Security Considerations 205 The content of the Category header-field is not secure, private or 206 integrity-guaranteed, and due caution should be exercised when using 207 it. 209 6. Internationalisation Considerations 211 Category header-fields may be localised depending on the Accept- 212 Language header-field, as defined in section 14.4 of [RFC2616]. 214 Scheme IRIs in atom:category elements may need to be converted to 215 URIs in order to express them in serialisations that do not support 216 IRIs, as defined in section 3.1 of [RFC3987]. This includes the 217 Category header-field. 219 7. References 221 7.1. Normative References 223 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 224 Requirement Levels", BCP 14, RFC 2119, March 1997. 226 [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded 227 Word Extensions: 228 Character Sets, Languages, and Continuations", RFC 2231, 229 November 1997. 231 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 232 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 233 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 235 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 236 Procedures for Message Header Fields", BCP 90, RFC 3864, 237 September 2004. 239 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 240 Resource Identifier (URI): Generic Syntax", STD 66, 241 RFC 3986, January 2005. 243 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 244 Identifiers (IRIs)", RFC 3987, January 2005. 246 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 247 Syndication Format", RFC 4287, December 2005. 249 [RFC5137] Klensin, J., "ASCII Escaping of Unicode Characters", 250 BCP 137, RFC 5137, February 2008. 252 7.2. Informative References 254 [RFC2068] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., and T. 255 Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", 256 RFC 2068, January 1997. 258 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 260 [W3C.REC-html401-19991224] 261 Raggett, D., Jacobs, I., and A. Hors, "HTML 4.01 262 Specification", World Wide Web Consortium 263 Recommendation REC-html401-19991224, December 1999, 264 . 266 [W3C.WD-html5-20110525] 267 Hickson, I., "HTML5", World Wide Web Consortium 268 LastCall WD-html5-20110525, May 2011, 269 . 271 [rel-tag-microformat] 272 Celik, T., Marks, K., and D. Powazek, "rel="tag" 273 Microformat", . 275 Appendix A. Notes on use with HTML 277 In the absence of a dedicated category element in HTML 4 278 [W3C.REC-html401-19991224] and HTML 5 [W3C.WD-html5-20110525], 279 category information (including user supllied folksonomy 280 classifications) MAY be exposed using HTML A and/or LINK elements by 281 concatenating the scheme and term: 282 category-link = scheme term 283 scheme = URI 284 term = token 286 These category-links MAY form a resolveable "tag space" in which case 287 they SHOULD use the "tag" relation-type per [rel-tag-microformat]. 289 Alternatively META elements MAY be used: 291 o where the "name" attribute is "keywords" and the "content" 292 attribute is a comma-separated list of term(s) 294 o where the "http-equiv" attribute is "Category" and the "content" 295 attribute is a comma-separated list of category-value(s) 297 Appendix B. Notes on use with Atom 299 Where the cardinality is known to be one (for example, when 300 retrieving an individual resource) it MAY be preferable to render the 301 resource natively over HTTP without Atom structures. In this case 302 the contents of the atom:content element SHOULD be returned as the 303 HTTP entity-body and metadata including the type attribute and atom: 304 category element(s) via HTTP header-field(s). 306 This approach SHOULD NOT be used where the cardinality is guaranteed 307 to be one (for example, search results which MAY return one result). 309 Appendix C. Acknowledgements 311 The author would like to thank Mark Nottingham for his work on Web 312 Linking [RFC5988] (on which this document was based), the authors of 313 [RFC2068] for specification of the Link: header-field on which this 314 is based and all those who commented upon, encouraged and gave 315 feedback to this draft. 317 Appendix D. Change Log (to be removed by RFC Editor before publication) 319 D.1. draft-johnston-http-category-header-00 321 Initial draft based on draft-nottingham-http-link-header-05 323 D.2. draft-johnston-http-category-header-01 325 Updated references, affiliation and tickled for IETF-78. 327 D.3. draft-johnston-http-category-header-02 329 Revived draft for further work due to renewed interest, resolved two 330 of the issues, updated affiliation. 332 Appendix E. Outstanding Issues 334 [[ to be removed by the RFC editor should document proceed to 335 publication as an RFC. ]] 337 The following issues are oustanding and should be addressed: 339 1. Is supporting multi-lingual representations of the same 340 category(s) necessary? If so, what are the risks of doing so? 342 2. Is a mechanism for maintaining Category header-fields required? 343 If so, should it use the headers themselves or some other 344 mechanism? 346 Author's Address 348 Sam Johnston 349 Open Cloud Initiative 351 Email: samj@samj.net