idnits 2.17.1
draft-reschke-http-jfv-05.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.
** The document seems to lack a both a reference to RFC 2119 and the
recommended RFC 2119 boilerplate, even if it appears to use RFC 2119
keywords.
RFC 2119 keyword, line 251: '... MUST NOT use duplicate object names...'
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (December 16, 2016) is 2686 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: 6 errors (**), 0 flaws (~~), 1 warning (==), 3 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 December 16, 2016
5 Expires: June 19, 2017
7 A JSON Encoding for HTTP Header Field Values
8 draft-reschke-http-jfv-05
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 The changes in this draft are summarized in Appendix C.5.
31 Status of This Memo
33 This Internet-Draft is submitted in full conformance with the
34 provisions of BCP 78 and BCP 79.
36 Internet-Drafts are working documents of the Internet Engineering
37 Task Force (IETF). Note that other groups may also distribute
38 working documents as Internet-Drafts. The list of current Internet-
39 Drafts is at http://datatracker.ietf.org/drafts/current/.
41 Internet-Drafts are draft documents valid for a maximum of six months
42 and may be updated, replaced, or obsoleted by other documents at any
43 time. It is inappropriate to use Internet-Drafts as reference
44 material or to cite them other than as "work in progress."
46 This Internet-Draft will expire on June 19, 2017.
48 Copyright Notice
49 Copyright (c) 2016 IETF Trust and the persons identified as the
50 document authors. All rights reserved.
52 This document is subject to BCP 78 and the IETF Trust's Legal
53 Provisions Relating to IETF Documents
54 (http://trustee.ietf.org/license-info) in effect on the date of
55 publication of this document. Please review these documents
56 carefully, as they describe your rights and restrictions with respect
57 to this document. Code Components extracted from this document must
58 include Simplified BSD License text as described in Section 4.e of
59 the Trust Legal Provisions and are provided without warranty as
60 described in the Simplified BSD License.
62 Table of Contents
64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
65 2. Data Model and Format . . . . . . . . . . . . . . . . . . . . 3
66 3. Sender Requirements . . . . . . . . . . . . . . . . . . . . . 4
67 4. Recipient Requirements . . . . . . . . . . . . . . . . . . . . 5
68 5. Using this Format in Header Field Definitions . . . . . . . . 5
69 6. Deployment Considerations . . . . . . . . . . . . . . . . . . 5
70 7. Interoperability Considerations . . . . . . . . . . . . . . . 5
71 7.1. Encoding and Characters . . . . . . . . . . . . . . . . . 5
72 7.2. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 6
73 7.3. Object Constraints . . . . . . . . . . . . . . . . . . . . 6
74 8. Internationalization Considerations . . . . . . . . . . . . . 6
75 9. Security Considerations . . . . . . . . . . . . . . . . . . . 6
76 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
77 10.1. Normative References . . . . . . . . . . . . . . . . . . . 7
78 10.2. Informative References . . . . . . . . . . . . . . . . . . 7
79 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 8
80 A.1. Content-Length . . . . . . . . . . . . . . . . . . . . . . 8
81 A.2. Content-Disposition . . . . . . . . . . . . . . . . . . . 9
82 A.3. WWW-Authenticate . . . . . . . . . . . . . . . . . . . . . 10
83 A.4. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 11
84 Appendix B. Discussion . . . . . . . . . . . . . . . . . . . . . 12
85 Appendix C. Change Log (to be removed by RFC Editor before
86 publication) . . . . . . . . . . . . . . . . . . . . 12
87 C.1. Since draft-reschke-http-jfv-00 . . . . . . . . . . . . . 12
88 C.2. Since draft-reschke-http-jfv-01 . . . . . . . . . . . . . 12
89 C.3. Since draft-reschke-http-jfv-02 . . . . . . . . . . . . . 13
90 C.4. Since draft-reschke-http-jfv-03 . . . . . . . . . . . . . 13
91 C.5. Since draft-reschke-http-jfv-04 . . . . . . . . . . . . . 13
92 C.5.1. Since draft-ietf-httpbis-jfv-00 . . . . . . . . . . . 13
93 C.5.2. Since draft-ietf-httpbis-jfv-01 . . . . . . . . . . . 13
94 C.5.3. Since draft-ietf-httpbis-jfv-02 . . . . . . . . . . . 13
95 Appendix D. Acknowledgements . . . . . . . . . . . . . . . . . . 13
97 1. Introduction
99 Defining syntax for new HTTP header fields ([RFC7230], Section 3.2)
100 is non-trivial. Among the commonly encountered problems are:
102 o There is no common syntax for complex field values. Several well-
103 known header fields do use a similarly looking syntax, but it is
104 hard to write generic parsing code that will both correctly handle
105 valid field values but also reject invalid ones.
107 o The HTTP message format allows header fields to repeat, so field
108 syntax needs to be designed in a way that these cases are either
109 meaningful, or can be unambiguously detected and rejected.
111 o HTTP/1.1 does not define a character encoding scheme ([RFC6365],
112 Section 2), so header fields are either stuck with US-ASCII
113 ([RFC0020]), or need out-of-band information to decide what
114 encoding scheme is used. Furthermore, APIs usually assume a
115 default encoding scheme in order to map from octet sequences to
116 strings (for instance, [XMLHttpRequest] uses the IDL type
117 "ByteString", effectively resulting in the ISO-8859-1 character
118 encoding scheme [ISO-8859-1] being used).
120 (See Section 8.3.1 of [RFC7231] for a summary of considerations for
121 new header fields.)
123 This specification addresses the issues listed above by defining both
124 a generic JSON-based ([RFC7159]) data model and a concrete wire
125 format that can be used in definitions of new header fields, where
126 the goals were:
128 o to be compatible with header field recombination when fields occur
129 multiple times in a single message (Section 3.2.2 of [RFC7230]),
130 and
132 o not to use any problematic characters in the field value (non-
133 ASCII characters and certain whitespace characters).
135 2. Data Model and Format
137 In HTTP, header fields with the same field name can occur multiple
138 times within a single message (Section 3.2.2 of [RFC7230]). When
139 this happens, recipients are allowed to combine the field values
140 using commas as delimiter. This rule matches nicely JSON's array
141 format (Section 5 of [RFC7159]). Thus, the basic data model used
142 here is the JSON array.
144 Header field definitions that need only a single value can restrict
145 themselves to arrays of length 1, and are encouraged to define error
146 handling in case more values are received (such as "first wins",
147 "last wins", or "abort with fatal error message").
149 JSON arrays are mapped to field values by creating a sequence of
150 serialized member elements, separated by commas and optionally
151 whitespace. This is equivalent to using the full JSON array format,
152 while leaving out the "begin-array" ('[') and "end-array" (']')
153 delimiters.
155 The ABNF character names and classes below are used (copied from
156 [RFC5234], Appendix B.1):
158 CR = %x0D ; carriage return
159 HTAB = %x09 ; horizontal tab
160 LF = %x0A ; line feed
161 SP = %x20 ; space
162 VCHAR = %x21-7E ; visible (printing) characters
164 Characters in JSON strings that are not allowed or discouraged in
165 HTTP header field values -- that is, not in the "VCHAR" definition --
166 need to be represented using JSON's "backslash" escaping mechanism
167 ([RFC7159], Section 7).
169 The control characters CR, LF, and HTAB do not appear inside JSON
170 strings, but can be used outside (line breaks, indentation etc.).
171 These characters need to be either stripped or replaced by space
172 characters (ABNF "SP").
174 Formally, using the HTTP specification's ABNF extensions defined in
175 Section 7 of [RFC7230]:
177 json-field-value = #json-field-item
178 json-field-item = JSON-Text
179 ; see [RFC7159], Section 2,
180 ; post-processed so that only VCHAR characters
181 ; are used
183 3. Sender Requirements
185 To map a JSON array to an HTTP header field value, process each array
186 element separately by:
188 1. generating the JSON representation,
190 2. stripping all JSON control characters (CR, HTAB, LF), or
191 replacing them by space ("SP") characters,
193 3. replacing all remaining non-VSPACE characters by the equivalent
194 backslash-escape sequence ([RFC7159], Section 7).
196 The resulting list of strings is transformed into an HTTP field value
197 by combining them using comma (%x2C) plus optional SP as delimiter,
198 and encoding the resulting string into an octet sequence using the
199 US-ASCII character encoding scheme ([RFC0020]).
201 4. Recipient Requirements
203 To map a set of HTTP header field instances to a JSON array:
205 1. combine all header field instances into a single field as per
206 Section 3.2.2 of [RFC7230],
208 2. add a leading begin-array ("[") octet and a trailing end-array
209 ("]") octet, then
211 3. run the resulting octet sequence through a JSON parser.
213 The result of the parsing operation is either an error (in which case
214 the header field values needs to be considered invalid), or a JSON
215 array.
217 5. Using this Format in Header Field Definitions
219 [[anchor5: Explain what a definition of a new header field needs to
220 do precisely to use this format, mention must-ignore extensibility]]
222 6. Deployment Considerations
224 This JSON-based syntax will only apply to newly introduced header
225 fields, thus backwards compatibility is not a problem. That being
226 said, it is conceivable that there is existing code that might trip
227 over double quotes not being used for HTTP's quoted-string syntax
228 (Section 3.2.6 of [RFC7230]).
230 7. Interoperability Considerations
232 The "I-JSON Message Format" specification ([RFC7493]) addresses known
233 JSON interoperability pain points. This specification borrows from
234 the requirements made over there:
236 7.1. Encoding and Characters
238 This specification requires that field values use only US-ASCII
239 characters, and thus by definition use a subset of UTF-8 (Section 2.1
240 of [RFC7493]).
242 7.2. Numbers
244 Be aware of the issues around number precision, as discussed in
245 Section 2.2 of [RFC7493].
247 7.3. Object Constraints
249 As described in Section 4 of [RFC7159], JSON parser implementations
250 differ in the handling of duplicate object names. Therefore, senders
251 MUST NOT use duplicate object names, and recipients SHOULD either
252 treat field values with duplicate names as invalid (consistent with
253 [RFC7493], Section 2.3) or use the lexically last value (consistent
254 with [ECMA-262], Section 24.3.1.1).
256 Furthermore, ordering of object members is not significant and can
257 not be relied upon.
259 8. Internationalization Considerations
261 In HTTP/1.1, header field values are represented by octet sequences,
262 usually used to transmit ASCII characters, with restrictions on the
263 use of certain control characters, and no associated default
264 character encoding, nor a way to describe it ([RFC7230], Section
265 3.2). HTTP/2 does not change this.
267 This specification maps all characters which can cause problems to
268 JSON escape sequences, thereby solving the HTTP header field
269 internationalization problem.
271 Future specifications of HTTP might change to allow non-ASCII
272 characters natively. In that case, header fields using the syntax
273 defined by this specification would have a simple migration path (by
274 just stopping to require escaping of non-ASCII characters).
276 9. Security Considerations
278 Using JSON-shaped field values is believed to not introduce any new
279 threads beyond those described in Section 12 of [RFC7159], namely the
280 risk of recipients using the wrong tools to parse them.
282 Other than that, any syntax that makes extensions easy can be used to
283 smuggle information through field values; however, this concern is
284 shared with other widely used formats, such as those using parameters
285 in the form of name/value pairs.
287 10. References
288 10.1. Normative References
290 [RFC0020] Cerf, V., "ASCII format for network interchange",
291 STD 80, RFC 20, DOI 10.17487/RFC0020, October 1969,
292 .
294 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for
295 Syntax Specifications: ABNF", STD 68, RFC 5234,
296 DOI 10.17487/RFC5234, January 2008,
297 .
299 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON)
300 Data Interchange Format", RFC 7159, DOI 10.17487/
301 RFC7159, March 2014,
302 .
304 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
305 Transfer Protocol (HTTP/1.1): Message Syntax and
306 Routing", RFC 7230, DOI 10.17487/RFC7230,
307 June 2014,
308 .
310 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
311 Transfer Protocol (HTTP/1.1): Semantics and
312 Content", RFC 7231, DOI 10.17487/RFC7231,
313 June 2014,
314 .
316 [RFC7493] Bray, T., Ed., "The I-JSON Message Format",
317 RFC 7493, DOI 10.17487/RFC7493, March 2015,
318 .
320 10.2. Informative References
322 [ECMA-262] Ecma International, "ECMA-262 6th Edition, The
323 ECMAScript 2015 Language Specification",
324 Standard ECMA-262, June 2015,
325 .
327 [ISO-8859-1] International Organization for Standardization,
328 "Information technology -- 8-bit single-byte coded
329 graphic character sets -- Part 1: Latin alphabet
330 No. 1", ISO/IEC 8859-1:1998, 1998.
332 [KEY] Fielding, R. and M. Nottingham, "The Key HTTP
333 Response Header Field", draft-ietf-httpbis-key-01
334 (work in progress), March 2016.
336 [RFC5987] Reschke, J., "Character Set and Language Encoding
337 for Hypertext Transfer Protocol (HTTP) Header Field
338 Parameters", RFC 5987, DOI 10.17487/RFC5987,
339 August 2010,
340 .
342 [RFC6266] Reschke, J., "Use of the Content-Disposition Header
343 Field in the Hypertext Transfer Protocol (HTTP)",
344 RFC 6266, DOI 10.17487/RFC6266, June 2011,
345 .
347 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in
348 Internationalization in the IETF", BCP 166,
349 RFC 6365, DOI 10.17487/RFC6365, September 2011,
350 .
352 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
353 Transfer Protocol (HTTP/1.1): Authentication",
354 RFC 7235, DOI 10.17487/RFC7235, June 2014,
355 .
357 [XMLHttpRequest] WhatWG, "XMLHttpRequest",
358 .
360 URIs
362 [1]
364 [2]
366 Appendix A. Examples
368 This section shows how some of the existing HTTP header fields would
369 look like if they would use the format defined by this specification.
371 A.1. Content-Length
373 "Content-Length" is defined in Section 3.3.2 of [RFC7230], with the
374 field value's ABNF being:
376 Content-Length = 1*DIGIT
378 So the field value is similar to a JSON number ([RFC7159], Section
379 6).
381 Content-Length is restricted to a single field instance, as it
382 doesn't use the list production (as per Section 3.2.2 of [RFC7230]).
383 However, in practice multiple instances do occur, and the definition
384 of the header field does indeed discuss how to handle these cases.
386 If Content-Length was defined using the JSON format discussed here,
387 the ABNF would be something like:
389 Content-Length = #number
390 ; number: [RFC7159], Section 6
392 ...and the prose definition would:
394 o restrict all numbers to be non-negative integers without
395 fractions, and
397 o require that the array of values is of length 1 (but allow the
398 case where the array is longer, but all members represent the same
399 value)
401 A.2. Content-Disposition
403 Content-Disposition field values, defined in [RFC6266], consist of a
404 "disposition type" (a string), plus multiple parameters, of which at
405 least one ("filename") sometime needs to carry non-ASCII characters.
407 For instance, the first example in Section 5 of [RFC6266]:
409 Attachment; filename=example.html
411 has a disposition type of "Attachment", with filename parameter value
412 "example.html". A JSON representation of this information might be:
414 {
415 "Attachment": {
416 "filename" : "example.html"
417 }
418 }
420 which would translate to a header field value of:
422 { "Attachment": { "filename" : "example.html" } }
424 The third example in Section 5 of [RFC6266] uses a filename parameter
425 containing non-US-ASCII characters:
427 attachment; filename*=UTF-8''%e2%82%ac%20rates
429 Note that in this case, the "filename*" parameter uses the encoding
430 defined in [RFC5987], representing a filename starting with the
431 Unicode character U+20AC (EURO SIGN), followed by " rates". If the
432 definition of Content-Disposition would have used the format proposed
433 here, the workaround involving the "parameter*" syntax would not have
434 been needed at all.
436 The JSON representation of this value could then be:
438 { "attachment": { "filename" : "\u20AC rates" } }
440 A.3. WWW-Authenticate
442 The WWW-Authenticate header field value is defined in Section 4.1 of
443 [RFC7235] as a list of "challenges":
445 WWW-Authenticate = 1#challenge
447 ...where a challenge consists of a scheme with optional parameters:
449 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ]
451 An example for a complex header field value given in the definition
452 of the header field is:
454 Newauth realm="apps", type=1, title="Login to \"apps\"",
455 Basic realm="simple"
457 (line break added for readability)
459 A possible JSON representation of this field value would be the array
460 below:
462 [
463 {
464 "Newauth" : {
465 "realm": "apps",
466 "type" : 1,
467 "title" : "Login to \"apps\""
468 }
469 },
470 {
471 "Basic" : {
472 "realm": "simple"
473 }
474 }
475 ]
477 ...which would translate to a header field value of:
479 { "Newauth" : { "realm": "apps", "type" : 1,
480 "title": "Login to \"apps\"" }},
481 { "Basic" : { "realm": "simple"}}
483 A.4. Accept-Encoding
485 The Accept-Encoding header field value is defined in Section 5.3.4 of
486 [RFC7231] as a list of codings, each of which allowing a weight
487 parameter 'q':
489 Accept-Encoding = #( codings [ weight ] )
490 codings = content-coding / "identity" / "*"
491 weight = OWS ";" OWS "q=" qvalue
492 qvalue = ( "0" [ "." 0*3DIGIT ] )
493 / ( "1" [ "." 0*3("0") ] )
495 An example for a complex header field value given in the definition
496 of the header field is:
498 gzip;q=1.0, identity; q=0.5, *;q=0
500 Due to the defaulting rules for the quality value ([RFC7231], Section
501 5.3.1), this could also be written as:
503 gzip, identity; q=0.5, *; q=0
505 A JSON representation could be:
507 [
508 {
509 "gzip" : {
510 }
511 },
512 {
513 "identity" : {
514 "q": 0.5
515 }
516 },
517 {
518 "*" : {
519 "q": 0
520 }
521 }
522 ]
524 ...which would translate to a header field value of:
526 {"gzip": {}}, {"identity": {"q": 0.5}}, {"*": {"q": 0}}
528 In this example, the part about "gzip" appears unnecessarily verbose,
529 as the value is just an empty object. A simpler notation would
530 collapse members like these to string literals:
532 "gzip", {"identity": {"q": 0.5}}, {"*": {"q": 0}}
534 If this is desirable, the header field definition could allow both
535 string literals and objects, and define that a mere string literal
536 would be mapped to a member whose name is given by the string
537 literal, and the value is an empty object.
539 For what it's worth, one of the most common cases for 'Accept-
540 Encoding' would become:
542 "gzip", "deflate"
544 which would be only a small overhead over the original format.
546 Appendix B. Discussion
548 This approach uses a default of "JSON array", using implicit array
549 markers. An alternative would be a default of "JSON object". This
550 would simplify the syntax for non-list-typed header fields, but all
551 the benefits of having the same data model for both types of header
552 fields would be gone. A hybrid approach might make sense, as long as
553 it doesn't require any heuristics on the recipient's side.
555 Note: a concrete proposal was made by Kazuho Oku in .
558 [[anchor15: Use of generic libs vs compactness of field values..]]
560 [[anchor16: Mention potential "Key" header field extension ([KEY]).]]
562 Appendix C. Change Log (to be removed by RFC Editor before publication)
564 C.1. Since draft-reschke-http-jfv-00
566 Editorial fixes + working on the TODOs.
568 C.2. Since draft-reschke-http-jfv-01
570 Mention slightly increased risk of smuggling information in header
571 field values.
573 C.3. Since draft-reschke-http-jfv-02
575 Mention Kazuho Oku's proposal for abbreviated forms.
577 Added a bit of text about the motivation for a concrete JSON subset
578 (ack Cory Benfield).
580 Expand I18N section.
582 C.4. Since draft-reschke-http-jfv-03
584 Mention relation to KEY header field.
586 C.5. Since draft-reschke-http-jfv-04
588 Between June and December 2016, this was a work item of the HTTP
589 working group (see
590 ). Work
591 (if any) continues now on
592 .
594 Changes made while this was a work item of the HTTP Working Group:
596 C.5.1. Since draft-ietf-httpbis-jfv-00
598 Added example for "Accept-Encoding" (inspired by Kazuho's feedback),
599 showing a potential way to optimize the format when default values
600 apply.
602 C.5.2. Since draft-ietf-httpbis-jfv-01
604 Add interop discussion, building on I-JSON and ECMA-262 (see
605 ).
607 C.5.3. Since draft-ietf-httpbis-jfv-02
609 Move non-essential parts into appendix.
611 Updated XHR reference.
613 Appendix D. Acknowledgements
615 Thanks go to the Hypertext Transfer Protocol Working Group
616 participants.
618 Author's Address
620 Julian F. Reschke
621 greenbytes GmbH
622 Hafenweg 16
623 Muenster, NW 48155
624 Germany
626 EMail: julian.reschke@greenbytes.de
627 URI: http://greenbytes.de/tech/webdav/