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/