idnits 2.17.1 draft-reschke-http-jfv-00.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([2], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 2, 2014) is 3584 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) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Obsolete informational reference (is this intentional?): RFC 5987 (Obsoleted by RFC 8187) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Reschke 3 Internet-Draft greenbytes 4 Intended status: Standards Track July 2, 2014 5 Expires: January 3, 2015 7 A JSON Encoding for HTTP Header Field Values 8 draft-reschke-http-jfv-00 10 Abstract 12 This document establishes a convention for use of JSON-encoded field 13 values in HTTP header fields. 15 Editorial Note (To be removed by RFC Editor before publication) 17 Distribution of this document is unlimited. Although this is not a 18 work item of the HTTPbis Working Group, comments should be sent to 19 the Hypertext Transfer Protocol (HTTP) mailing list at 20 ietf-http-wg@w3.org [1], which may be joined by sending a message 21 with subject "subscribe" to ietf-http-wg-request@w3.org [2]. 23 Discussions of the HTTPbis Working Group are archived at 24 . 26 XML versions and latest edits for this document are available from 27 . 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on January 3, 2015. 46 Copyright Notice 48 Copyright (c) 2014 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Data Model and Format . . . . . . . . . . . . . . . . . . . . . 3 65 3. Sender Requirements . . . . . . . . . . . . . . . . . . . . . . 4 66 4. Recipient Requirements . . . . . . . . . . . . . . . . . . . . 5 67 5. Using this Format in Header Field Definitions . . . . . . . . . 5 68 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 69 6.1. Content-Length . . . . . . . . . . . . . . . . . . . . . . 5 70 6.2. Content-Disposition . . . . . . . . . . . . . . . . . . . . 6 71 6.3. WWW-Authenticate . . . . . . . . . . . . . . . . . . . . . 7 72 7. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 8. Deployment Considerations . . . . . . . . . . . . . . . . . . . 8 74 9. Internationalization Considerations . . . . . . . . . . . . . . 8 75 10. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 76 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 77 11.1. Normative References . . . . . . . . . . . . . . . . . . . 8 78 11.2. Informative References . . . . . . . . . . . . . . . . . . 9 79 Appendix A. Sample Code and Test Cases . . . . . . . . . . . . . . 9 81 1. Introduction 83 Defining syntax for new HTTP header fields ([RFC7230], Section 3.2) 84 is non-trivial. Among the commonly encountered problems are: 86 o There is no common syntax for complex field values. Several well- 87 known header fields do use a similarly looking syntax, but it is 88 hard to write generic parsing code that will both correctly handle 89 valid field values but also fail on invalid ones. 91 o The HTTP message format allows header fields to repeat, so field 92 syntax needs to be designed in a way that these cases are either 93 meaningful, or can be unambiguously detected and rejected. 95 o HTTP/1.1 does not define a character encoding scheme ([RFC6365], 96 Section 2), so header fields are either stuck with US-ASCII 97 ([USASCII]), or need out-of-band information to decide what 98 encoding scheme is used. Furthermore, APIs usually assume a 99 default encoding scheme in order to map from octet sequences to 100 strings (for instance, [XMLHttpRequest] uses the IDL type 101 "ByteString", effectively resulting in the ISO-8859-1 character 102 encoding scheme [ISO-8859-1] being used). 104 (See Section 8.3.1 of [RFC7231] for a summary of considerations for 105 new header fields.) 107 This specification addresses the issues listed above by defining both 108 a generic JSON-based ([RFC7159]) data model and a concrete wire 109 format that can be used in definitions of new header fields. 111 2. Data Model and Format 113 In HTTP, header fields with the same field name can occur multiple 114 times within a single message (Section 3.2.2 of [RFC7230]). When 115 this happens, recipients are allowed to combine the field values 116 using commas as delimiter. This rule matches nicely JSON's array 117 format (Section 5 of [RFC7159]). Thus, the basic data model used 118 here is the JSON array. 120 Header field definitions that need only a single value can restrict 121 themselves to arrays of lenght 1, and are encouraged to define error 122 handling in case more values are received (such as "first wins", 123 "last wins", or "abort with fatal error message"). 125 JSON arrays are mapped to field values by creating a sequence of 126 serialized member elements, separated by commas and optionally 127 whitespace. This is equivalent to using the full JSON array format, 128 while leaving out the "begin-array" ('[') and "end-array" (']') 129 delimiters. 131 The ABNF character names and classes below are used (copied from 132 [RFC5234], Appendix B.1): 134 CR = %x0D ; carriage return 135 HTAB = %x09 ; horizontal tab 136 LF = %x0A ; line feed 137 SP = %x20 ; space 138 VCHAR = %x21-7E ; visible (printing) characters 140 Characters in JSON strings that are not allowed or discouraged in 141 HTTP header field values -- that is, not in the "VCHAR" definition -- 142 need to be represented using JSON's "backslash" escaping mechanism 143 ([RFC7159], Section 7). 145 The control characters CR, LF, and HTAB do not appear inside JSON 146 strings, but can be used outside (line breaks, indentation etc). 147 These characters can be either stripped or replaced by space 148 characters (ABNF "SP"). 150 Formally, using the HTTP specification's ABNF extensions defined in 151 Section 7 of [RFC7230]: 153 json-field-value = #json-field-item 154 json-field-item = JSON-Text 155 ; see [RFC7159], Section 2, 156 ; post-processed so that only VCHAR characters 157 ; are used 159 3. Sender Requirements 161 [[anchor3: The text below assumes we're starting with a JSON- 162 formatted sequence of characters, not octets; need to clarify.]] To 163 map a JSON array to an HTTP header field value, process each array 164 element separately by: 166 1. generating the JSON representation, 168 2. stripping all JSON control characters (CR, HTAB, LF), or 169 replacing them by space ("SP") characters, 171 3. replacing all remaining non-VSPACE characters by the equivalent 172 backslash-escape sequence ([RFC7159], Section 7). 174 The resulting list of strings is transformed into an HTTP field value 175 by combining them using comma (%x2C) plus optional SP as delimiter, 176 and encoding the resulting string into an octet sequence using the 177 US-ASCII character encoding scheme. 179 4. Recipient Requirements 181 To map a set of HTTP header field instances to a JSON array: 183 1. remove all header field instances that only contain whitespace 184 (SP / HTAB) and "comma" characters [[anchor5: either drop this or 185 make it more precise]], 187 2. combine all header field instances into a single field as per 188 Section 3.2.2 of [RFC7230], 190 3. add a leading begin-array ("[") octet and a trailing end-array 191 ("]") octet, then 193 4. run the resulting octet sequence through a JSON parser. 195 The result of the parsing operation is either an error (in which case 196 the header field values needs to be considered invalid), or a JSON 197 array. 199 5. Using this Format in Header Field Definitions 201 [[anchor7: Explain what a definition of a new header field needs to 202 do precisely to use this format]] 204 6. Examples 206 This section shows how some of the existing HTTP header fields would 207 look like if they would use the format defined by this specification. 209 6.1. Content-Length 211 "Content-Length" is defined in Section 3.3.2 of [RFC7230], with the 212 field value's ABNF being: 214 Content-Length = 1*DIGIT 216 So the field value is similar to a JSON number ([RFC7230], Section 217 6). 219 Content-Length is restricted to a single field instance, as it 220 doesn't use the list production (as per Section 3.2.2 of [RFC7230]). 221 However, in practice multiple instances do occur, and the definition 222 of the header field does indeed discuss how to handle these cases. 224 If Content-Length was defined using the JSON format discussed here, 225 the ABNF would be something like: 227 Content-Length = #number 228 ; number: [RFC7159], Section 6 230 ...and the prose definition would: 232 o restrict all numbers to be non-negative integers without 233 fractions, and 235 o require that the array of values is of length 1 (but allow the 236 case where the array is longer, but all members represent the same 237 value) 239 6.2. Content-Disposition 241 Content-Disposition field values, defined in [RFC6266], consist of a 242 "disposition type" (a string), plus multiple parameters, of which at 243 least one ("filename") sometime needs to carry non-ASCII characters. 245 For instance, the first example in Section 5 of [RFC6266]: 247 Attachment; filename=example.html 249 has a disposition type of "Attachment", with filename parameter value 250 "example.html". A JSON representation of this information might be: 252 { 253 "Attachment": { 254 "filename" : "example.html" 255 } 256 } 258 which would translate to a header field value of: 260 { "Attachment": { "filename" : "example.html" } } 262 The third example in Section 5 of [RFC6266] uses a filename parameter 263 containing non-US-ASCII characters: 265 attachment; filename*=UTF-8''%e2%82%ac%20rates 267 Note that in this case, the "filename*" parameter uses the encoding 268 defined in [RFC5987], representing a filename starting with the 269 Unicode character U+20AC (EURO SIGN), followed by " rates". If the 270 definition of Content-Disposition would have used the format proposed 271 here, the workaround involving the "parameter*" syntax would not have 272 been needed at all. 274 The JSON representation of this value could then be: 276 { "attachment": { "filename" : "\u20AC rates" } } 278 6.3. WWW-Authenticate 280 The WWW-Authenticate is defined in Section 4.1 of [RFC7235] as a list 281 of "challenges": 283 WWW-Authenticate = 1#challenge 285 ...where a challenge consists of a scheme with optional parameters: 287 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 289 An example for a complex header field value given in the definition 290 of the header field is: 292 Newauth realm="apps", type=1, title="Login to \"apps\"", 293 Basic realm="simple" 295 (line break added for readability) 297 A possible JSON representation of this field value would be the array 298 below: 300 [ 301 { 302 "Newauth" : { 303 "realm": "apps", 304 "type" : 1, 305 "title" : "Login to \"apps\"" 306 } 307 }, 308 { 309 "Basic" : { 310 "realm": "simple" 311 } 312 } 313 ] 315 ...which would translate to a header field value of: 317 { "Newauth" : { "realm": "apps", "type" : 1, 318 "title": "Login to \"apps\"" }}, 319 { "Basic" : { "realm": "simple"}} 321 7. Discussion 323 This approach uses a default of "JSON array", using implicit array 324 markers. An alternative would be a default of "JSON object". This 325 would simplify the syntax for non-list-typed haeders, but all the 326 benefits of having the same data model for both types of header 327 fields would be gone. A hybrid approach might make sense, as long as 328 it doesn't require any heuristics on the recipient's side. 330 [[anchor9: Use of generic libs vs compactness of field values..]] 332 8. Deployment Considerations 334 [[anchor11: Mention that some code might be refused by double quotes 335 not being used for quoted-string.]] 337 9. Internationalization Considerations 339 [[anchor13: TBD, mention migration path to message format that is 340 robust wrt UTF-8, or other binary encodings of JSON]] 342 10. Security Considerations 344 [[anchor15: TBD]] 346 11. References 348 11.1. Normative References 350 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for 351 Syntax Specifications: ABNF", STD 68, RFC 5234, 352 January 2008. 354 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) 355 Data Interchange Format", RFC 7159, March 2014. 357 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 358 Transfer Protocol (HTTP/1.1): Message Syntax and 359 Routing", RFC 7230, June 2014. 361 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 362 Transfer Protocol (HTTP/1.1): Semantics and 363 Content", RFC 7231, June 2014. 365 [USASCII] American National Standards Institute, "Coded 366 Character Set -- 7-bit American Standard Code for 367 Information Interchange", ANSI X3.4, 1986. 369 11.2. Informative References 371 [ISO-8859-1] International Organization for Standardization, 372 "Information technology -- 8-bit single-byte coded 373 graphic character sets -- Part 1: Latin alphabet 374 No. 1", ISO/IEC 8859-1:1998, 1998. 376 [RFC5987] Reschke, J., "Character Set and Language Encoding 377 for Hypertext Transfer Protocol (HTTP) Header Field 378 Parameters", RFC 5987, August 2010. 380 [RFC6266] Reschke, J., "Use of the Content-Disposition Header 381 Field in the Hypertext Transfer Protocol (HTTP)", 382 RFC 6266, June 2011. 384 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 385 Internationalization in the IETF", BCP 166, 386 RFC 6365, September 2011. 388 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 389 Transfer Protocol (HTTP/1.1): Authentication", 390 RFC 7235, June 2014. 392 [XMLHttpRequest] van Kesteren, A., Aubourg, J., Song, J., and H. 393 Steen, "XMLHttpRequest Level 1", W3C Working 394 Draft WD-XMLHttpRequest-20140130, January 2014, . 398 Latest version available at 399 . 401 URIs 403 [1] 405 [2] 407 Appendix A. Sample Code and Test Cases 409 [[anchor19: TBD]] 411 Author's Address 413 Julian F. Reschke 414 greenbytes GmbH 415 Hafenweg 16 416 Muenster, NW 48155 417 Germany 419 EMail: julian.reschke@greenbytes.de 420 URI: http://greenbytes.de/tech/webdav/