idnits 2.17.1 draft-ietf-httpbis-jfv-01.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.) == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 8, 2016) is 2849 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) -- 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: 4 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP Working Group J. Reschke 3 Internet-Draft greenbytes 4 Intended status: Standards Track July 8, 2016 5 Expires: January 9, 2017 7 A JSON Encoding for HTTP Header Field Values 8 draft-ietf-httpbis-jfv-01 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 Discussion of this draft takes place on the HTTPBIS working group 18 mailing list (ietf-http-wg@w3.org), which is archived at 19 . 21 Working Group information can be found at ; 22 source code and issues list for this draft can be found at 23 . 25 The changes in this draft are summarized in Appendix A. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on January 9, 2017. 44 Copyright Notice 46 Copyright (c) 2016 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Data Model and Format . . . . . . . . . . . . . . . . . . . . 3 63 3. Sender Requirements . . . . . . . . . . . . . . . . . . . . . 4 64 4. Recipient Requirements . . . . . . . . . . . . . . . . . . . . 5 65 5. Using this Format in Header Field Definitions . . . . . . . . 5 66 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 6.1. Content-Length . . . . . . . . . . . . . . . . . . . . . . 5 68 6.2. Content-Disposition . . . . . . . . . . . . . . . . . . . 6 69 6.3. WWW-Authenticate . . . . . . . . . . . . . . . . . . . . . 7 70 6.4. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 8 71 7. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 9 72 8. Deployment Considerations . . . . . . . . . . . . . . . . . . 9 73 9. Internationalization Considerations . . . . . . . . . . . . . 9 74 10. Security Considerations . . . . . . . . . . . . . . . . . . . 10 75 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 76 11.1. Normative References . . . . . . . . . . . . . . . . . . . 10 77 11.2. Informative References . . . . . . . . . . . . . . . . . . 11 78 Appendix A. Change Log (to be removed by RFC Editor before 79 publication) . . . . . . . . . . . . . . . . . . . . 11 80 A.1. Since draft-reschke-http-jfv-00 . . . . . . . . . . . . . 11 81 A.2. Since draft-reschke-http-jfv-01 . . . . . . . . . . . . . 12 82 A.3. Since draft-reschke-http-jfv-02 . . . . . . . . . . . . . 12 83 A.4. Since draft-reschke-http-jfv-03 . . . . . . . . . . . . . 12 84 A.5. Since draft-reschke-http-jfv-04 . . . . . . . . . . . . . 12 85 A.6. Since draft-ietf-httpbis-jfv-00 . . . . . . . . . . . . . 12 86 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 12 88 1. Introduction 90 Defining syntax for new HTTP header fields ([RFC7230], Section 3.2) 91 is non-trivial. Among the commonly encountered problems are: 93 o There is no common syntax for complex field values. Several well- 94 known header fields do use a similarly looking syntax, but it is 95 hard to write generic parsing code that will both correctly handle 96 valid field values but also reject invalid ones. 98 o The HTTP message format allows header fields to repeat, so field 99 syntax needs to be designed in a way that these cases are either 100 meaningful, or can be unambiguously detected and rejected. 102 o HTTP/1.1 does not define a character encoding scheme ([RFC6365], 103 Section 2), so header fields are either stuck with US-ASCII 104 ([RFC0020]), or need out-of-band information to decide what 105 encoding scheme is used. Furthermore, APIs usually assume a 106 default encoding scheme in order to map from octet sequences to 107 strings (for instance, [XMLHttpRequest] uses the IDL type 108 "ByteString", effectively resulting in the ISO-8859-1 character 109 encoding scheme [ISO-8859-1] being used). 111 (See Section 8.3.1 of [RFC7231] for a summary of considerations for 112 new header fields.) 114 This specification addresses the issues listed above by defining both 115 a generic JSON-based ([RFC7159]) data model and a concrete wire 116 format that can be used in definitions of new header fields, where 117 the goals were: 119 o to be compatible with header field recombination when fields occur 120 multiple times in a single message (Section 3.2.2 of [RFC7230]), 121 and 123 o not to use any problematic characters in the field value (non- 124 ASCII characters and certain whitespace characters). 126 2. Data Model and Format 128 In HTTP, header fields with the same field name can occur multiple 129 times within a single message (Section 3.2.2 of [RFC7230]). When 130 this happens, recipients are allowed to combine the field values 131 using commas as delimiter. This rule matches nicely JSON's array 132 format (Section 5 of [RFC7159]). Thus, the basic data model used 133 here is the JSON array. 135 Header field definitions that need only a single value can restrict 136 themselves to arrays of length 1, and are encouraged to define error 137 handling in case more values are received (such as "first wins", 138 "last wins", or "abort with fatal error message"). 140 JSON arrays are mapped to field values by creating a sequence of 141 serialized member elements, separated by commas and optionally 142 whitespace. This is equivalent to using the full JSON array format, 143 while leaving out the "begin-array" ('[') and "end-array" (']') 144 delimiters. 146 The ABNF character names and classes below are used (copied from 147 [RFC5234], Appendix B.1): 149 CR = %x0D ; carriage return 150 HTAB = %x09 ; horizontal tab 151 LF = %x0A ; line feed 152 SP = %x20 ; space 153 VCHAR = %x21-7E ; visible (printing) characters 155 Characters in JSON strings that are not allowed or discouraged in 156 HTTP header field values -- that is, not in the "VCHAR" definition -- 157 need to be represented using JSON's "backslash" escaping mechanism 158 ([RFC7159], Section 7). 160 The control characters CR, LF, and HTAB do not appear inside JSON 161 strings, but can be used outside (line breaks, indentation etc.). 162 These characters need to be either stripped or replaced by space 163 characters (ABNF "SP"). 165 Formally, using the HTTP specification's ABNF extensions defined in 166 Section 7 of [RFC7230]: 168 json-field-value = #json-field-item 169 json-field-item = JSON-Text 170 ; see [RFC7159], Section 2, 171 ; post-processed so that only VCHAR characters 172 ; are used 174 3. Sender Requirements 176 To map a JSON array to an HTTP header field value, process each array 177 element separately by: 179 1. generating the JSON representation, 181 2. stripping all JSON control characters (CR, HTAB, LF), or 182 replacing them by space ("SP") characters, 184 3. replacing all remaining non-VSPACE characters by the equivalent 185 backslash-escape sequence ([RFC7159], Section 7). 187 The resulting list of strings is transformed into an HTTP field value 188 by combining them using comma (%x2C) plus optional SP as delimiter, 189 and encoding the resulting string into an octet sequence using the 190 US-ASCII character encoding scheme ([RFC0020]). 192 4. Recipient Requirements 194 To map a set of HTTP header field instances to a JSON array: 196 1. combine all header field instances into a single field as per 197 Section 3.2.2 of [RFC7230], 199 2. add a leading begin-array ("[") octet and a trailing end-array 200 ("]") octet, then 202 3. run the resulting octet sequence through a JSON parser. 204 The result of the parsing operation is either an error (in which case 205 the header field values needs to be considered invalid), or a JSON 206 array. 208 5. Using this Format in Header Field Definitions 210 [[anchor5: Explain what a definition of a new header field needs to 211 do precisely to use this format, mention must-ignore extensibility]] 213 6. Examples 215 This section shows how some of the existing HTTP header fields would 216 look like if they would use the format defined by this specification. 218 6.1. Content-Length 220 "Content-Length" is defined in Section 3.3.2 of [RFC7230], with the 221 field value's ABNF being: 223 Content-Length = 1*DIGIT 225 So the field value is similar to a JSON number ([RFC7159], Section 226 6). 228 Content-Length is restricted to a single field instance, as it 229 doesn't use the list production (as per Section 3.2.2 of [RFC7230]). 230 However, in practice multiple instances do occur, and the definition 231 of the header field does indeed discuss how to handle these cases. 233 If Content-Length was defined using the JSON format discussed here, 234 the ABNF would be something like: 236 Content-Length = #number 237 ; number: [RFC7159], Section 6 239 ...and the prose definition would: 241 o restrict all numbers to be non-negative integers without 242 fractions, and 244 o require that the array of values is of length 1 (but allow the 245 case where the array is longer, but all members represent the same 246 value) 248 6.2. Content-Disposition 250 Content-Disposition field values, defined in [RFC6266], consist of a 251 "disposition type" (a string), plus multiple parameters, of which at 252 least one ("filename") sometime needs to carry non-ASCII characters. 254 For instance, the first example in Section 5 of [RFC6266]: 256 Attachment; filename=example.html 258 has a disposition type of "Attachment", with filename parameter value 259 "example.html". A JSON representation of this information might be: 261 { 262 "Attachment": { 263 "filename" : "example.html" 264 } 265 } 267 which would translate to a header field value of: 269 { "Attachment": { "filename" : "example.html" } } 271 The third example in Section 5 of [RFC6266] uses a filename parameter 272 containing non-US-ASCII characters: 274 attachment; filename*=UTF-8''%e2%82%ac%20rates 276 Note that in this case, the "filename*" parameter uses the encoding 277 defined in [RFC5987], representing a filename starting with the 278 Unicode character U+20AC (EURO SIGN), followed by " rates". If the 279 definition of Content-Disposition would have used the format proposed 280 here, the workaround involving the "parameter*" syntax would not have 281 been needed at all. 283 The JSON representation of this value could then be: 285 { "attachment": { "filename" : "\u20AC rates" } } 287 6.3. WWW-Authenticate 289 The WWW-Authenticate header field value is defined in Section 4.1 of 290 [RFC7235] as a list of "challenges": 292 WWW-Authenticate = 1#challenge 294 ...where a challenge consists of a scheme with optional parameters: 296 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ] 298 An example for a complex header field value given in the definition 299 of the header field is: 301 Newauth realm="apps", type=1, title="Login to \"apps\"", 302 Basic realm="simple" 304 (line break added for readability) 306 A possible JSON representation of this field value would be the array 307 below: 309 [ 310 { 311 "Newauth" : { 312 "realm": "apps", 313 "type" : 1, 314 "title" : "Login to \"apps\"" 315 } 316 }, 317 { 318 "Basic" : { 319 "realm": "simple" 320 } 321 } 322 ] 324 ...which would translate to a header field value of: 326 { "Newauth" : { "realm": "apps", "type" : 1, 327 "title": "Login to \"apps\"" }}, 328 { "Basic" : { "realm": "simple"}} 330 6.4. Accept-Encoding 332 The Accept-Encoding header field value is defined in Section 5.3.4 of 333 [RFC7231] as a list of codings, each of which allowing a weight 334 parameter 'q': 336 Accept-Encoding = #( codings [ weight ] ) 337 codings = content-coding / "identity" / "*" 338 weight = OWS ";" OWS "q=" qvalue 339 qvalue = ( "0" [ "." 0*3DIGIT ] ) 340 / ( "1" [ "." 0*3("0") ] ) 342 An example for a complex header field value given in the definition 343 of the header field is: 345 gzip;q=1.0, identity; q=0.5, *;q=0 347 Due to the defaulting rules for the quality value ([RFC7231], Section 348 5.3.1), this could also be written as: 350 gzip, identity; q=0.5, *; q=0 352 A JSON representation could be: 354 [ 355 { 356 "gzip" : { 357 } 358 }, 359 { 360 "identity" : { 361 "q": 0.5 362 } 363 }, 364 { 365 "*" : { 366 "q": 0 367 } 368 } 369 ] 371 ...which would translate to a header field value of: 373 {"gzip": {}}, {"identity": {"q": 0.5}}, {"*": {"q": 0}} 375 In this example, the part about "gzip" appears unnecessarily verbose, 376 as the value is just an empty object. A simpler notation would 377 collapse members like these to string literals: 379 "gzip", {"identity": {"q": 0.5}}, {"*": {"q": 0}} 381 If this is desirable, the header field definition could allow both 382 string literals and objects, and define that a mere string literal 383 would be mapped to a member whose name is given by the string 384 literal, and the value is an empty object. 386 For what it's worth, one of the most common cases for 'Accept- 387 Encoding' would become: 389 "gzip", "deflate" 391 which would be only a small overhead over the original format. 393 7. Discussion 395 This approach uses a default of "JSON array", using implicit array 396 markers. An alternative would be a default of "JSON object". This 397 would simplify the syntax for non-list-typed header fields, but all 398 the benefits of having the same data model for both types of header 399 fields would be gone. A hybrid approach might make sense, as long as 400 it doesn't require any heuristics on the recipient's side. 402 Note: a concrete proposal was made by Kazuho Oku in . 405 [[anchor7: Use of generic libs vs compactness of field values..]] 407 [[anchor8: Mention potential "Key" header field extension ([KEY]).]] 409 8. Deployment Considerations 411 This JSON-based syntax will only apply to newly introduced header 412 fields, thus backwards compatibility is not a problem. That being 413 said, it is conceivable that there is existing code that might trip 414 over double quotes not being used for HTTP's quoted-string syntax 415 (Section 3.2.6 of [RFC7230]). 417 9. Internationalization Considerations 419 In HTTP/1.1, header field values are represented by octet sequences, 420 usually used to transmit ASCII characters, with restrictions on the 421 use of certain control characters, and no associated default 422 character encoding, nor a way to describe it ([RFC7230], Section 423 3.2). HTTP/2 does not change this. 425 This specification maps all characters which can cause problems to 426 JSON escape sequences, thereby solving the HTTP header field 427 internationalization problem. 429 Future specifications of HTTP might change to allow non-ASCII 430 characters natively. In that case, header fields using the syntax 431 defined by this specification would have a simple migration path (by 432 just stopping to require escaping of non-ASCII characters). 434 10. Security Considerations 436 Using JSON-shaped field values is believed to not introduce any new 437 threads beyond those described in Section 12 of [RFC7159], namely the 438 risk of recipients using the wrong tools to parse them. 440 Other than that, any syntax that makes extensions easy can be used to 441 smuggle information through field values; however, this concern is 442 shared with other widely used formats, such as those using parameters 443 in the form of name/value pairs. 445 11. References 447 11.1. Normative References 449 [RFC0020] Cerf, V., "ASCII format for network interchange", 450 STD 80, RFC 20, DOI 10.17487/RFC0020, October 1969, 451 . 453 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for 454 Syntax Specifications: ABNF", STD 68, RFC 5234, 455 DOI 10.17487/RFC5234, January 2008, 456 . 458 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) 459 Data Interchange Format", RFC 7159, DOI 10.17487/ 460 RFC7159, March 2014, 461 . 463 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 464 Transfer Protocol (HTTP/1.1): Message Syntax and 465 Routing", RFC 7230, DOI 10.17487/RFC7230, 466 June 2014, 467 . 469 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 470 Transfer Protocol (HTTP/1.1): Semantics and 471 Content", RFC 7231, DOI 10.17487/RFC7231, 472 June 2014, 473 . 475 11.2. Informative References 477 [ISO-8859-1] International Organization for Standardization, 478 "Information technology -- 8-bit single-byte coded 479 graphic character sets -- Part 1: Latin alphabet 480 No. 1", ISO/IEC 8859-1:1998, 1998. 482 [KEY] Fielding, R. and M. Nottingham, "The Key HTTP 483 Response Header Field", draft-ietf-httpbis-key-01 484 (work in progress), March 2016. 486 [RFC5987] Reschke, J., "Character Set and Language Encoding 487 for Hypertext Transfer Protocol (HTTP) Header Field 488 Parameters", RFC 5987, DOI 10.17487/RFC5987, 489 August 2010, 490 . 492 [RFC6266] Reschke, J., "Use of the Content-Disposition Header 493 Field in the Hypertext Transfer Protocol (HTTP)", 494 RFC 6266, DOI 10.17487/RFC6266, June 2011, 495 . 497 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 498 Internationalization in the IETF", BCP 166, 499 RFC 6365, DOI 10.17487/RFC6365, September 2011, 500 . 502 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 503 Transfer Protocol (HTTP/1.1): Authentication", 504 RFC 7235, DOI 10.17487/RFC7235, June 2014, 505 . 507 [XMLHttpRequest] van Kesteren, A., Aubourg, J., Song, J., and H. 508 Steen, "XMLHttpRequest Level 1", W3C Working 509 Draft WD-XMLHttpRequest-20140130, January 2014, . 513 Latest version available at 514 . 516 Appendix A. Change Log (to be removed by RFC Editor before publication) 518 A.1. Since draft-reschke-http-jfv-00 520 Editorial fixes + working on the TODOs. 522 A.2. Since draft-reschke-http-jfv-01 524 Mention slightly increased risk of smuggling information in header 525 field values. 527 A.3. Since draft-reschke-http-jfv-02 529 Mention Kazuho Oku's proposal for abbreviated forms. 531 Added a bit of text about the motivation for a concrete JSON subset 532 (ack Cory Benfield). 534 Expand I18N section. 536 A.4. Since draft-reschke-http-jfv-03 538 Mention relation to KEY header field. 540 A.5. Since draft-reschke-http-jfv-04 542 Change to HTTP Working Group draft. 544 A.6. Since draft-ietf-httpbis-jfv-00 546 Added example for "Accept-Encoding" (inspired by Kazuho's feedback), 547 showing a potential way to optimize the format when default values 548 apply. 550 Appendix B. Acknowledgements 552 Thanks go to the Hypertext Transfer Protocol Working Group 553 participants. 555 Author's Address 557 Julian F. Reschke 558 greenbytes GmbH 559 Hafenweg 16 560 Muenster, NW 48155 561 Germany 563 EMail: julian.reschke@greenbytes.de 564 URI: http://greenbytes.de/tech/webdav/