idnits 2.17.1
draft-ietf-httpbis-jfv-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 :
----------------------------------------------------------------------------
** 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.
** 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 443: '... 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 (October 24, 2016) is 2734 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: 5 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 October 24, 2016
5 Expires: April 27, 2017
7 A JSON Encoding for HTTP Header Field Values
8 draft-ietf-httpbis-jfv-02
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 April 27, 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. Interoperability Considerations . . . . . . . . . . . . . . . 9
74 9.1. Encoding and Characters . . . . . . . . . . . . . . . . . 9
75 9.2. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 10
76 9.3. Object Constraints . . . . . . . . . . . . . . . . . . . . 10
77 10. Internationalization Considerations . . . . . . . . . . . . . 10
78 11. Security Considerations . . . . . . . . . . . . . . . . . . . 10
79 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
80 12.1. Normative References . . . . . . . . . . . . . . . . . . . 11
81 12.2. Informative References . . . . . . . . . . . . . . . . . . 11
82 Appendix A. Change Log (to be removed by RFC Editor before
83 publication) . . . . . . . . . . . . . . . . . . . . 12
84 A.1. Since draft-reschke-http-jfv-00 . . . . . . . . . . . . . 12
85 A.2. Since draft-reschke-http-jfv-01 . . . . . . . . . . . . . 12
86 A.3. Since draft-reschke-http-jfv-02 . . . . . . . . . . . . . 12
87 A.4. Since draft-reschke-http-jfv-03 . . . . . . . . . . . . . 13
88 A.5. Since draft-reschke-http-jfv-04 . . . . . . . . . . . . . 13
89 A.6. Since draft-ietf-httpbis-jfv-00 . . . . . . . . . . . . . 13
90 A.7. Since draft-ietf-httpbis-jfv-01 . . . . . . . . . . . . . 13
91 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 13
93 1. Introduction
95 Defining syntax for new HTTP header fields ([RFC7230], Section 3.2)
96 is non-trivial. Among the commonly encountered problems are:
98 o There is no common syntax for complex field values. Several well-
99 known header fields do use a similarly looking syntax, but it is
100 hard to write generic parsing code that will both correctly handle
101 valid field values but also reject invalid ones.
103 o The HTTP message format allows header fields to repeat, so field
104 syntax needs to be designed in a way that these cases are either
105 meaningful, or can be unambiguously detected and rejected.
107 o HTTP/1.1 does not define a character encoding scheme ([RFC6365],
108 Section 2), so header fields are either stuck with US-ASCII
109 ([RFC0020]), or need out-of-band information to decide what
110 encoding scheme is used. Furthermore, APIs usually assume a
111 default encoding scheme in order to map from octet sequences to
112 strings (for instance, [XMLHttpRequest] uses the IDL type
113 "ByteString", effectively resulting in the ISO-8859-1 character
114 encoding scheme [ISO-8859-1] being used).
116 (See Section 8.3.1 of [RFC7231] for a summary of considerations for
117 new header fields.)
119 This specification addresses the issues listed above by defining both
120 a generic JSON-based ([RFC7159]) data model and a concrete wire
121 format that can be used in definitions of new header fields, where
122 the goals were:
124 o to be compatible with header field recombination when fields occur
125 multiple times in a single message (Section 3.2.2 of [RFC7230]),
126 and
128 o not to use any problematic characters in the field value (non-
129 ASCII characters and certain whitespace characters).
131 2. Data Model and Format
133 In HTTP, header fields with the same field name can occur multiple
134 times within a single message (Section 3.2.2 of [RFC7230]). When
135 this happens, recipients are allowed to combine the field values
136 using commas as delimiter. This rule matches nicely JSON's array
137 format (Section 5 of [RFC7159]). Thus, the basic data model used
138 here is the JSON array.
140 Header field definitions that need only a single value can restrict
141 themselves to arrays of length 1, and are encouraged to define error
142 handling in case more values are received (such as "first wins",
143 "last wins", or "abort with fatal error message").
145 JSON arrays are mapped to field values by creating a sequence of
146 serialized member elements, separated by commas and optionally
147 whitespace. This is equivalent to using the full JSON array format,
148 while leaving out the "begin-array" ('[') and "end-array" (']')
149 delimiters.
151 The ABNF character names and classes below are used (copied from
152 [RFC5234], Appendix B.1):
154 CR = %x0D ; carriage return
155 HTAB = %x09 ; horizontal tab
156 LF = %x0A ; line feed
157 SP = %x20 ; space
158 VCHAR = %x21-7E ; visible (printing) characters
160 Characters in JSON strings that are not allowed or discouraged in
161 HTTP header field values -- that is, not in the "VCHAR" definition --
162 need to be represented using JSON's "backslash" escaping mechanism
163 ([RFC7159], Section 7).
165 The control characters CR, LF, and HTAB do not appear inside JSON
166 strings, but can be used outside (line breaks, indentation etc.).
167 These characters need to be either stripped or replaced by space
168 characters (ABNF "SP").
170 Formally, using the HTTP specification's ABNF extensions defined in
171 Section 7 of [RFC7230]:
173 json-field-value = #json-field-item
174 json-field-item = JSON-Text
175 ; see [RFC7159], Section 2,
176 ; post-processed so that only VCHAR characters
177 ; are used
179 3. Sender Requirements
181 To map a JSON array to an HTTP header field value, process each array
182 element separately by:
184 1. generating the JSON representation,
186 2. stripping all JSON control characters (CR, HTAB, LF), or
187 replacing them by space ("SP") characters,
189 3. replacing all remaining non-VSPACE characters by the equivalent
190 backslash-escape sequence ([RFC7159], Section 7).
192 The resulting list of strings is transformed into an HTTP field value
193 by combining them using comma (%x2C) plus optional SP as delimiter,
194 and encoding the resulting string into an octet sequence using the
195 US-ASCII character encoding scheme ([RFC0020]).
197 4. Recipient Requirements
199 To map a set of HTTP header field instances to a JSON array:
201 1. combine all header field instances into a single field as per
202 Section 3.2.2 of [RFC7230],
204 2. add a leading begin-array ("[") octet and a trailing end-array
205 ("]") octet, then
207 3. run the resulting octet sequence through a JSON parser.
209 The result of the parsing operation is either an error (in which case
210 the header field values needs to be considered invalid), or a JSON
211 array.
213 5. Using this Format in Header Field Definitions
215 [[anchor5: Explain what a definition of a new header field needs to
216 do precisely to use this format, mention must-ignore extensibility]]
218 6. Examples
220 This section shows how some of the existing HTTP header fields would
221 look like if they would use the format defined by this specification.
223 6.1. Content-Length
225 "Content-Length" is defined in Section 3.3.2 of [RFC7230], with the
226 field value's ABNF being:
228 Content-Length = 1*DIGIT
230 So the field value is similar to a JSON number ([RFC7159], Section
231 6).
233 Content-Length is restricted to a single field instance, as it
234 doesn't use the list production (as per Section 3.2.2 of [RFC7230]).
235 However, in practice multiple instances do occur, and the definition
236 of the header field does indeed discuss how to handle these cases.
238 If Content-Length was defined using the JSON format discussed here,
239 the ABNF would be something like:
241 Content-Length = #number
242 ; number: [RFC7159], Section 6
244 ...and the prose definition would:
246 o restrict all numbers to be non-negative integers without
247 fractions, and
249 o require that the array of values is of length 1 (but allow the
250 case where the array is longer, but all members represent the same
251 value)
253 6.2. Content-Disposition
255 Content-Disposition field values, defined in [RFC6266], consist of a
256 "disposition type" (a string), plus multiple parameters, of which at
257 least one ("filename") sometime needs to carry non-ASCII characters.
259 For instance, the first example in Section 5 of [RFC6266]:
261 Attachment; filename=example.html
263 has a disposition type of "Attachment", with filename parameter value
264 "example.html". A JSON representation of this information might be:
266 {
267 "Attachment": {
268 "filename" : "example.html"
269 }
270 }
272 which would translate to a header field value of:
274 { "Attachment": { "filename" : "example.html" } }
276 The third example in Section 5 of [RFC6266] uses a filename parameter
277 containing non-US-ASCII characters:
279 attachment; filename*=UTF-8''%e2%82%ac%20rates
281 Note that in this case, the "filename*" parameter uses the encoding
282 defined in [RFC5987], representing a filename starting with the
283 Unicode character U+20AC (EURO SIGN), followed by " rates". If the
284 definition of Content-Disposition would have used the format proposed
285 here, the workaround involving the "parameter*" syntax would not have
286 been needed at all.
288 The JSON representation of this value could then be:
290 { "attachment": { "filename" : "\u20AC rates" } }
292 6.3. WWW-Authenticate
294 The WWW-Authenticate header field value is defined in Section 4.1 of
295 [RFC7235] as a list of "challenges":
297 WWW-Authenticate = 1#challenge
299 ...where a challenge consists of a scheme with optional parameters:
301 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ]
303 An example for a complex header field value given in the definition
304 of the header field is:
306 Newauth realm="apps", type=1, title="Login to \"apps\"",
307 Basic realm="simple"
309 (line break added for readability)
311 A possible JSON representation of this field value would be the array
312 below:
314 [
315 {
316 "Newauth" : {
317 "realm": "apps",
318 "type" : 1,
319 "title" : "Login to \"apps\""
320 }
321 },
322 {
323 "Basic" : {
324 "realm": "simple"
325 }
326 }
327 ]
329 ...which would translate to a header field value of:
331 { "Newauth" : { "realm": "apps", "type" : 1,
332 "title": "Login to \"apps\"" }},
333 { "Basic" : { "realm": "simple"}}
335 6.4. Accept-Encoding
337 The Accept-Encoding header field value is defined in Section 5.3.4 of
338 [RFC7231] as a list of codings, each of which allowing a weight
339 parameter 'q':
341 Accept-Encoding = #( codings [ weight ] )
342 codings = content-coding / "identity" / "*"
343 weight = OWS ";" OWS "q=" qvalue
344 qvalue = ( "0" [ "." 0*3DIGIT ] )
345 / ( "1" [ "." 0*3("0") ] )
347 An example for a complex header field value given in the definition
348 of the header field is:
350 gzip;q=1.0, identity; q=0.5, *;q=0
352 Due to the defaulting rules for the quality value ([RFC7231], Section
353 5.3.1), this could also be written as:
355 gzip, identity; q=0.5, *; q=0
357 A JSON representation could be:
359 [
360 {
361 "gzip" : {
362 }
363 },
364 {
365 "identity" : {
366 "q": 0.5
367 }
368 },
369 {
370 "*" : {
371 "q": 0
372 }
373 }
374 ]
376 ...which would translate to a header field value of:
378 {"gzip": {}}, {"identity": {"q": 0.5}}, {"*": {"q": 0}}
380 In this example, the part about "gzip" appears unnecessarily verbose,
381 as the value is just an empty object. A simpler notation would
382 collapse members like these to string literals:
384 "gzip", {"identity": {"q": 0.5}}, {"*": {"q": 0}}
386 If this is desirable, the header field definition could allow both
387 string literals and objects, and define that a mere string literal
388 would be mapped to a member whose name is given by the string
389 literal, and the value is an empty object.
391 For what it's worth, one of the most common cases for 'Accept-
392 Encoding' would become:
394 "gzip", "deflate"
396 which would be only a small overhead over the original format.
398 7. Discussion
400 This approach uses a default of "JSON array", using implicit array
401 markers. An alternative would be a default of "JSON object". This
402 would simplify the syntax for non-list-typed header fields, but all
403 the benefits of having the same data model for both types of header
404 fields would be gone. A hybrid approach might make sense, as long as
405 it doesn't require any heuristics on the recipient's side.
407 Note: a concrete proposal was made by Kazuho Oku in .
410 [[anchor7: Use of generic libs vs compactness of field values..]]
412 [[anchor8: Mention potential "Key" header field extension ([KEY]).]]
414 8. Deployment Considerations
416 This JSON-based syntax will only apply to newly introduced header
417 fields, thus backwards compatibility is not a problem. That being
418 said, it is conceivable that there is existing code that might trip
419 over double quotes not being used for HTTP's quoted-string syntax
420 (Section 3.2.6 of [RFC7230]).
422 9. Interoperability Considerations
424 The "I-JSON Message Format" specification ([RFC7493]) addresses known
425 JSON interoperability pain points. This specification borrows from
426 the requirements made over there:
428 9.1. Encoding and Characters
430 This specification requires that field values use only US-ASCII
431 characters, and thus by definition use a subset of UTF-8 (Section 2.1
432 of [RFC7493]).
434 9.2. Numbers
436 Be aware of the issues around number precision, as discussed in
437 Section 2.2 of [RFC7493].
439 9.3. Object Constraints
441 As described in Section 4 of [RFC7159], JSON parser implementations
442 differ in the handling of duplicate object names. Therefore, senders
443 MUST NOT use duplicate object names, and recipients SHOULD either
444 treat field values with duplicate names as invalid (consistent with
445 [RFC7493], Section 2.3) or use the lexically last value (consistent
446 with [ECMA-262], Section 24.3.1.1).
448 Furthermore, ordering of object members is not significant and can
449 not be relied upon.
451 10. Internationalization Considerations
453 In HTTP/1.1, header field values are represented by octet sequences,
454 usually used to transmit ASCII characters, with restrictions on the
455 use of certain control characters, and no associated default
456 character encoding, nor a way to describe it ([RFC7230], Section
457 3.2). HTTP/2 does not change this.
459 This specification maps all characters which can cause problems to
460 JSON escape sequences, thereby solving the HTTP header field
461 internationalization problem.
463 Future specifications of HTTP might change to allow non-ASCII
464 characters natively. In that case, header fields using the syntax
465 defined by this specification would have a simple migration path (by
466 just stopping to require escaping of non-ASCII characters).
468 11. Security Considerations
470 Using JSON-shaped field values is believed to not introduce any new
471 threads beyond those described in Section 12 of [RFC7159], namely the
472 risk of recipients using the wrong tools to parse them.
474 Other than that, any syntax that makes extensions easy can be used to
475 smuggle information through field values; however, this concern is
476 shared with other widely used formats, such as those using parameters
477 in the form of name/value pairs.
479 12. References
480 12.1. Normative References
482 [RFC0020] Cerf, V., "ASCII format for network interchange",
483 STD 80, RFC 20, DOI 10.17487/RFC0020, October 1969,
484 .
486 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for
487 Syntax Specifications: ABNF", STD 68, RFC 5234,
488 DOI 10.17487/RFC5234, January 2008,
489 .
491 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON)
492 Data Interchange Format", RFC 7159, DOI 10.17487/
493 RFC7159, March 2014,
494 .
496 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
497 Transfer Protocol (HTTP/1.1): Message Syntax and
498 Routing", RFC 7230, DOI 10.17487/RFC7230,
499 June 2014,
500 .
502 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
503 Transfer Protocol (HTTP/1.1): Semantics and
504 Content", RFC 7231, DOI 10.17487/RFC7231,
505 June 2014,
506 .
508 [RFC7493] Bray, T., Ed., "The I-JSON Message Format",
509 RFC 7493, DOI 10.17487/RFC7493, March 2015,
510 .
512 12.2. Informative References
514 [ECMA-262] Ecma International, "ECMA-262 6th Edition, The
515 ECMAScript 2015 Language Specification",
516 Standard ECMA-262, June 2015,
517 .
519 [ISO-8859-1] International Organization for Standardization,
520 "Information technology -- 8-bit single-byte coded
521 graphic character sets -- Part 1: Latin alphabet
522 No. 1", ISO/IEC 8859-1:1998, 1998.
524 [KEY] Fielding, R. and M. Nottingham, "The Key HTTP
525 Response Header Field", draft-ietf-httpbis-key-01
526 (work in progress), March 2016.
528 [RFC5987] Reschke, J., "Character Set and Language Encoding
529 for Hypertext Transfer Protocol (HTTP) Header Field
530 Parameters", RFC 5987, DOI 10.17487/RFC5987,
531 August 2010,
532 .
534 [RFC6266] Reschke, J., "Use of the Content-Disposition Header
535 Field in the Hypertext Transfer Protocol (HTTP)",
536 RFC 6266, DOI 10.17487/RFC6266, June 2011,
537 .
539 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in
540 Internationalization in the IETF", BCP 166,
541 RFC 6365, DOI 10.17487/RFC6365, September 2011,
542 .
544 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext
545 Transfer Protocol (HTTP/1.1): Authentication",
546 RFC 7235, DOI 10.17487/RFC7235, June 2014,
547 .
549 [XMLHttpRequest] van Kesteren, A., Aubourg, J., Song, J., and H.
550 Steen, "XMLHttpRequest Level 1", W3C Working
551 Draft WD-XMLHttpRequest-20140130, January 2014, .
555 Latest version available at
556 .
558 Appendix A. Change Log (to be removed by RFC Editor before publication)
560 A.1. Since draft-reschke-http-jfv-00
562 Editorial fixes + working on the TODOs.
564 A.2. Since draft-reschke-http-jfv-01
566 Mention slightly increased risk of smuggling information in header
567 field values.
569 A.3. Since draft-reschke-http-jfv-02
571 Mention Kazuho Oku's proposal for abbreviated forms.
573 Added a bit of text about the motivation for a concrete JSON subset
574 (ack Cory Benfield).
576 Expand I18N section.
578 A.4. Since draft-reschke-http-jfv-03
580 Mention relation to KEY header field.
582 A.5. Since draft-reschke-http-jfv-04
584 Change to HTTP Working Group draft.
586 A.6. Since draft-ietf-httpbis-jfv-00
588 Added example for "Accept-Encoding" (inspired by Kazuho's feedback),
589 showing a potential way to optimize the format when default values
590 apply.
592 A.7. Since draft-ietf-httpbis-jfv-01
594 Add interop discussion, building on I-JSON and ECMA-262 (see
595 ).
597 Appendix B. Acknowledgements
599 Thanks go to the Hypertext Transfer Protocol Working Group
600 participants.
602 Author's Address
604 Julian F. Reschke
605 greenbytes GmbH
606 Hafenweg 16
607 Muenster, NW 48155
608 Germany
610 EMail: julian.reschke@greenbytes.de
611 URI: http://greenbytes.de/tech/webdav/