idnits 2.17.1
draft-reschke-http-jfv-13.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:
----------------------------------------------------------------------------
== There is 1 instance of lines with non-ascii characters in the document.
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 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 288: '... 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 (22 February 2021) is 1158 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
== Missing Reference: 'CLEARSITE' is mentioned on line 419, but not defined
== Missing Reference: 'FEATUREPOL' is mentioned on line 424, but not defined
== Missing Reference: 'REPORTING' is mentioned on line 411, but not defined
== Outdated reference: A later version (-19) exists of
draft-ietf-httpbis-semantics-14
Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group J. F. Reschke
3 Internet-Draft greenbytes
4 Intended status: Informational 22 February 2021
5 Expires: 26 August 2021
7 A JSON Encoding for HTTP Field Values
8 draft-reschke-http-jfv-13
10 Abstract
12 This document establishes a convention for use of JSON-encoded field
13 values in HTTP fields.
15 Editorial Note
17 This note is to be removed before publishing as an RFC.
19 Distribution of this document is unlimited. Although this is not a
20 work item of the HTTPbis Working Group, comments should be sent to
21 the Hypertext Transfer Protocol (HTTP) mailing list at ietf-http-
22 wg@w3.org (mailto:ietf-http-wg@w3.org), which may be joined by
23 sending a message with subject "subscribe" to ietf-http-wg-
24 request@w3.org (mailto:ietf-http-wg-
25 request@w3.org?subject=subscribe).
27 Discussions of the HTTPbis Working Group are archived at
28 .
30 XML versions and latest edits for this document are available from
31 .
33 The changes in this draft are summarized in Appendix B.16.
35 Status of This Memo
37 This Internet-Draft is submitted in full conformance with the
38 provisions of BCP 78 and BCP 79.
40 Internet-Drafts are working documents of the Internet Engineering
41 Task Force (IETF). Note that other groups may also distribute
42 working documents as Internet-Drafts. The list of current Internet-
43 Drafts is at https://datatracker.ietf.org/drafts/current/.
45 Internet-Drafts are draft documents valid for a maximum of six months
46 and may be updated, replaced, or obsoleted by other documents at any
47 time. It is inappropriate to use Internet-Drafts as reference
48 material or to cite them other than as "work in progress."
49 This Internet-Draft will expire on 26 August 2021.
51 Copyright Notice
53 Copyright (c) 2021 IETF Trust and the persons identified as the
54 document authors. All rights reserved.
56 This document is subject to BCP 78 and the IETF Trust's Legal
57 Provisions Relating to IETF Documents (https://trustee.ietf.org/
58 license-info) in effect on the date of publication of this document.
59 Please review these documents carefully, as they describe your rights
60 and restrictions with respect to this document. Code Components
61 extracted from this document must include Simplified BSD License text
62 as described in Section 4.e of the Trust Legal Provisions and are
63 provided without warranty as described in the Simplified BSD License.
65 Table of Contents
67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
68 2. Data Model and Format . . . . . . . . . . . . . . . . . . . . 4
69 3. Sender Requirements . . . . . . . . . . . . . . . . . . . . . 5
70 4. Recipient Requirements . . . . . . . . . . . . . . . . . . . 5
71 5. Using this Format in Field Definitions . . . . . . . . . . . 5
72 6. Deployment Considerations . . . . . . . . . . . . . . . . . . 6
73 7. Interoperability Considerations . . . . . . . . . . . . . . . 6
74 7.1. Encoding and Characters . . . . . . . . . . . . . . . . . 6
75 7.2. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 6
76 7.3. Object Constraints . . . . . . . . . . . . . . . . . . . 7
77 8. Internationalization Considerations . . . . . . . . . . . . . 7
78 9. Security Considerations . . . . . . . . . . . . . . . . . . . 7
79 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 7
80 10.1. Normative References . . . . . . . . . . . . . . . . . . 7
81 10.2. Informative References . . . . . . . . . . . . . . . . . 8
82 10.3. Specifications Using This Syntax (at some point of
83 time) . . . . . . . . . . . . . . . . . . . . . . . . . 8
84 Appendix A. Use of JSON Field Value Encoding in the Wild . . . . 9
85 A.1. W3C Reporting API Specification . . . . . . . . . . . . . 9
86 A.2. W3C Clear Site Data Specification . . . . . . . . . . . . 9
87 A.3. W3C Feature Policy Specification . . . . . . . . . . . . 10
88 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 10
89 B.1. Since draft-reschke-http-jfv-00 . . . . . . . . . . . . . 10
90 B.2. Since draft-reschke-http-jfv-01 . . . . . . . . . . . . . 10
91 B.3. Since draft-reschke-http-jfv-02 . . . . . . . . . . . . . 10
92 B.4. Since draft-reschke-http-jfv-03 . . . . . . . . . . . . . 10
93 B.5. Since draft-reschke-http-jfv-04 . . . . . . . . . . . . . 10
94 B.6. Since draft-ietf-httpbis-jfv-00 . . . . . . . . . . . . . 10
95 B.7. Since draft-ietf-httpbis-jfv-01 . . . . . . . . . . . . . 11
96 B.8. Since draft-ietf-httpbis-jfv-02 . . . . . . . . . . . . . 11
97 B.9. Since draft-reschke-http-jfv-05 . . . . . . . . . . . . . 11
98 B.10. Since draft-reschke-http-jfv-06 . . . . . . . . . . . . . 11
99 B.11. Since draft-reschke-http-jfv-07 . . . . . . . . . . . . . 11
100 B.12. Since draft-reschke-http-jfv-08 . . . . . . . . . . . . . 11
101 B.13. Since draft-reschke-http-jfv-09 . . . . . . . . . . . . . 11
102 B.14. Since draft-reschke-http-jfv-10 . . . . . . . . . . . . . 12
103 B.15. Since draft-reschke-http-jfv-11 . . . . . . . . . . . . . 12
104 B.16. Since draft-reschke-http-jfv-12 . . . . . . . . . . . . . 12
105 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 12
106 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12
108 1. Introduction
110 Defining syntax for new HTTP fields ([HTTP], Section 5) is non-
111 trivial. Among the commonly encountered problems are:
113 * There is no common syntax for complex field values. Several well-
114 known fields do use a similarly looking syntax, but it is hard to
115 write generic parsing code that will both correctly handle valid
116 field values but also reject invalid ones.
118 * The HTTP message format allows field lines to repeat, so field
119 syntax needs to be designed in a way that these cases are either
120 meaningful, or can be unambiguously detected and rejected.
122 * HTTP does not define a character encoding scheme ([RFC6365],
123 Section 2), so fields are either stuck with US-ASCII ([RFC0020]),
124 or need out-of-band information to decide what encoding scheme is
125 used. Furthermore, APIs usually assume a default encoding scheme
126 in order to map from octet sequences to strings (for instance,
127 [XMLHttpRequest] uses the IDL type "ByteString", effectively
128 resulting in the ISO-8859-1 character encoding scheme [ISO-8859-1]
129 being used).
131 (See Section 16.3 of [HTTP] for a summary of considerations for new
132 fields.)
134 This specification addresses the issues listed above by defining both
135 a generic JSON-based ([RFC8259]) data model and a concrete wire
136 format that can be used in definitions of new fields, where the goals
137 were:
139 * to be compatible with field recombination when field lines occur
140 multiple times in a single message (Section 5.3 of [HTTP]), and
142 * not to use any problematic characters in the field value (non-
143 ASCII characters and certain whitespace characters).
145 | *Note:* [RFC8941], a work item of the IETF HTTP Working Group,
146 | is a different attempt to address this set of problems - it
147 | tries to identify and formalize common field structures in
148 | existing fields; the syntax defined over there would usually
149 | lead to a more compact notation.
151 2. Data Model and Format
153 In HTTP, field lines with the same field name can occur multiple
154 times within a single message (Section 5.3 of [HTTP]). When this
155 happens, recipients are allowed to combine the field line values
156 using commas as delimiter, forming a combined "field value". This
157 rule matches nicely JSON's array format (Section 5 of [RFC8259]).
158 Thus, the basic data model used here is the JSON array.
160 Field definitions that need only a single value can restrict
161 themselves to arrays of length 1, and are encouraged to define error
162 handling in case more values are received (such as "first wins",
163 "last wins", or "abort with fatal error message").
165 JSON arrays are mapped to field values by creating a sequence of
166 serialized member elements, separated by commas and optionally
167 whitespace. This is equivalent to using the full JSON array format,
168 while leaving out the "begin-array" ('[') and "end-array" (']')
169 delimiters.
171 The ABNF character names and classes below are used (copied from
172 [RFC5234], Appendix B.1):
174 CR = %x0D ; carriage return
175 HTAB = %x09 ; horizontal tab
176 LF = %x0A ; line feed
177 SP = %x20 ; space
178 VCHAR = %x21-7E ; visible (printing) characters
180 Characters in JSON strings that are not allowed or discouraged in
181 HTTP field values - that is, not in the "VCHAR" definition - need to
182 be represented using JSON's "backslash" escaping mechanism
183 ([RFC8259], Section 7).
185 The control characters CR, LF, and HTAB do not appear inside JSON
186 strings, but can be used outside (line breaks, indentation etc.).
187 These characters need to be either stripped or replaced by space
188 characters (ABNF "SP").
190 Formally, using the HTTP specification's ABNF extensions defined in
191 Section 5.6.1 of [HTTP]:
193 json-field-value = #json-field-item
194 json-field-item = JSON-Text
195 ; see [RFC8259], Section 2,
196 ; post-processed so that only VCHAR characters
197 ; are used
199 3. Sender Requirements
201 To map a JSON array to an HTTP field value, process each array
202 element separately by:
204 1. generating the JSON representation,
206 2. stripping all JSON control characters (CR, HTAB, LF), or
207 replacing them by space ("SP") characters,
209 3. replacing all remaining non-VSPACE characters by the equivalent
210 backslash-escape sequence ([RFC8259], Section 7).
212 The resulting list of strings is transformed into an HTTP field value
213 by combining them using comma (%x2C) plus optional SP as delimiter,
214 and encoding the resulting string into an octet sequence using the
215 US-ASCII character encoding scheme ([RFC0020]).
217 4. Recipient Requirements
219 To map a set of HTTP field line values to a JSON array:
221 1. combine all field line values into a single field value as per
222 Section 5.3 of [HTTP],
224 2. add a leading begin-array ("[") octet and a trailing end-array
225 ("]") octet, then
227 3. run the resulting octet sequence through a JSON parser.
229 The result of the parsing operation is either an error (in which case
230 the field values needs to be considered invalid), or a JSON array.
232 5. Using this Format in Field Definitions
234 Specifications defining new HTTP fields need to take the
235 considerations listed in Section 16.3 of [HTTP] into account. Many
236 of these will already be accounted for by using the format defined in
237 this specification.
239 Readers of HTTP-related specifications frequently expect an ABNF
240 definition of the field value syntax. This is not really needed
241 here, as the actual syntax is JSON text, as defined in Section 2 of
242 [RFC8259].
244 A very simple way to use this JSON encoding thus is just to cite this
245 specification - specifically the "json-field-value" ABNF production
246 defined in Section 2 - and otherwise not to talk about the details of
247 the field syntax at all.
249 An alternative approach is just to repeat the ABNF-related parts from
250 Section 2.
252 This frees the specification from defining the concrete on-the-wire
253 syntax. What's left is defining the field value in terms of a JSON
254 array. An important aspect is the question of extensibility, e.g.
255 how recipients ought to treat unknown field names. In general, a
256 "must ignore" approach will allow protocols to evolve without
257 versioning or even using entire new field names.
259 6. Deployment Considerations
261 This JSON-based syntax will only apply to newly introduced fields,
262 thus backwards compatibility is not a problem. That being said, it
263 is conceivable that there is existing code that might trip over
264 double quotes not being used for HTTP's quoted-string syntax
265 (Section 5.6.4 of [HTTP]).
267 7. Interoperability Considerations
269 The "I-JSON Message Format" specification ([RFC7493]) addresses known
270 JSON interoperability pain points. This specification borrows from
271 the requirements made over there:
273 7.1. Encoding and Characters
275 This specification requires that field values use only US-ASCII
276 characters, and thus by definition use a subset of UTF-8 (Section 2.1
277 of [RFC7493]).
279 7.2. Numbers
281 Be aware of the issues around number precision, as discussed in
282 Section 2.2 of [RFC7493].
284 7.3. Object Constraints
286 As described in Section 4 of [RFC8259], JSON parser implementations
287 differ in the handling of duplicate object names. Therefore, senders
288 MUST NOT use duplicate object names, and recipients SHOULD either
289 treat field values with duplicate names as invalid (consistent with
290 [RFC7493], Section 2.3) or use the lexically last value (consistent
291 with [ECMA-262], Section 24.3.1.1).
293 Furthermore, ordering of object members is not significant and can
294 not be relied upon.
296 8. Internationalization Considerations
298 In current versions of HTTP, field values are represented by octet
299 sequences, usually used to transmit ASCII characters, with
300 restrictions on the use of certain control characters, and no
301 associated default character encoding, nor a way to describe it
302 ([HTTP], Section 5).
304 This specification maps all characters which can cause problems to
305 JSON escape sequences, thereby solving the HTTP field
306 internationalization problem.
308 Future specifications of HTTP might change to allow non-ASCII
309 characters natively. In that case, fields using the syntax defined
310 by this specification would have a simple migration path (by just
311 stopping to require escaping of non-ASCII characters).
313 9. Security Considerations
315 Using JSON-shaped field values is believed to not introduce any new
316 threads beyond those described in Section 12 of [RFC8259], namely the
317 risk of recipients using the wrong tools to parse them.
319 Other than that, any syntax that makes extensions easy can be used to
320 smuggle information through field values; however, this concern is
321 shared with other widely used formats, such as those using parameters
322 in the form of name/value pairs.
324 10. References
326 10.1. Normative References
328 [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
329 Ed., "HTTP Semantics", Work in Progress, Internet-Draft,
330 draft-ietf-httpbis-semantics-14, 13 January 2021,
331 .
334 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80,
335 RFC 20, DOI 10.17487/RFC0020, October 1969,
336 .
338 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
339 Specifications: ABNF", STD 68, RFC 5234,
340 DOI 10.17487/RFC5234, January 2008,
341 .
343 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
344 DOI 10.17487/RFC7493, March 2015,
345 .
347 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
348 Interchange Format", RFC 8259, DOI 10.17487/RFC8259,
349 December 2017, .
351 10.2. Informative References
353 [ECMA-262] Ecma International, "ECMA-262 6th Edition, The ECMAScript
354 2015 Language Specification", Standard ECMA-262, June
355 2015, .
357 [ISO-8859-1]
358 International Organization for Standardization,
359 "Information technology -- 8-bit single-byte coded graphic
360 character sets -- Part 1: Latin alphabet No. 1", ISO/
361 IEC 8859-1:1998, 1998.
363 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in
364 Internationalization in the IETF", BCP 166, RFC 6365,
365 DOI 10.17487/RFC6365, September 2011,
366 .
368 [RFC8941] Nottingham, M. and P-H. Kamp, "Structured Field Values for
369 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
370 .
372 [XMLHttpRequest]
373 WhatWG, "XMLHttpRequest", .
375 10.3. Specifications Using This Syntax (at some point of time)
377 [CLEARSITE]
378 West, M., "Clear Site Data", W3C Working Draft WD-clear-
379 site-data-20171130, 30 November 2017,
380 .
381 Latest version available at .
384 [FEATUREPOL]
385 Clelland, I., "Feature Policy", W3C Editor's Draft ,
386 .
388 [REPORTING]
389 Creager, D., Grigorik, I., Meyer, P., and M. West,
390 "Reporting API", W3C Working Draft WD-reporting-
391 1-20180925, 25 September 2018,
392 .
393 Latest version available at .
396 Appendix A. Use of JSON Field Value Encoding in the Wild
398 This section is to be removed before publishing as an RFC.
400 Since work started on this document, various specifications have
401 adopted this format. At least one of these moved away after the HTTP
402 Working Group decided to focus on [RFC8941] (see thread starting at
403 ).
406 The sections below summarize the current usage of this format.
408 A.1. W3C Reporting API Specification
410 Defined in W3C Working Draft "Reporting API" (Section 3.1 of
411 [REPORTING]). Still in use in latest working draft dated September
412 2018.
414 A.2. W3C Clear Site Data Specification
416 Used in earlier versions of "Clear Site Data". The current version
417 replaces the use of JSON with a custom syntax that happens to be
418 somewhat compatible with an array of JSON strings (see Section 3.1 of
419 [CLEARSITE] and for feedback).
422 A.3. W3C Feature Policy Specification
424 Originally defined in W3C document "Feature Policy" ([FEATUREPOL]),
425 but switched to use of Structured Header Fields ([RFC8941]).
427 Appendix B. Change Log
429 This section is to be removed before publishing as an RFC.
431 B.1. Since draft-reschke-http-jfv-00
433 Editorial fixes + working on the TODOs.
435 B.2. Since draft-reschke-http-jfv-01
437 Mention slightly increased risk of smuggling information in header
438 field values.
440 B.3. Since draft-reschke-http-jfv-02
442 Mention Kazuho Oku's proposal for abbreviated forms.
444 Added a bit of text about the motivation for a concrete JSON subset
445 (ack Cory Benfield).
447 Expand I18N section.
449 B.4. Since draft-reschke-http-jfv-03
451 Mention relation to KEY header field.
453 B.5. Since draft-reschke-http-jfv-04
455 Between June and December 2016, this was a work item of the HTTP
456 working group (see ). Work (if any) continues now on
458 .
460 Changes made while this was a work item of the HTTP Working Group:
462 B.6. Since draft-ietf-httpbis-jfv-00
464 Added example for "Accept-Encoding" (inspired by Kazuho's feedback),
465 showing a potential way to optimize the format when default values
466 apply.
468 B.7. Since draft-ietf-httpbis-jfv-01
470 Add interop discussion, building on I-JSON and ECMA-262 (see
471 ).
473 B.8. Since draft-ietf-httpbis-jfv-02
475 Move non-essential parts into appendix.
477 Updated XHR reference.
479 B.9. Since draft-reschke-http-jfv-05
481 Add meat to "Using this Format in Header Field Definitions".
483 Add a few lines on the relation to "Key".
485 Summarize current use of the format.
487 B.10. Since draft-reschke-http-jfv-06
489 RFC 5987 is obsoleted by RFC 8187.
491 Update CLEARSITE comment.
493 B.11. Since draft-reschke-http-jfv-07
495 Update JSON and HSTRUCT references.
497 FEATUREPOL doesn't use JSON syntax anymore.
499 B.12. Since draft-reschke-http-jfv-08
501 Update HSTRUCT reference.
503 Update notes about CLEARSITE and FEATUREPOL.
505 B.13. Since draft-reschke-http-jfv-09
507 Update HSTRUCT and FEATUREPOL references.
509 Update note about REPORTING.
511 Changed category to "informational".
513 B.14. Since draft-reschke-http-jfv-10
515 Update HSTRUCT reference.
517 B.15. Since draft-reschke-http-jfv-11
519 Update HSTRUCT reference.
521 Update note about FEATUREPOL (now using Structured Fields).
523 Reference [HTTP] instead if RFC723* and adjust (header) field
524 terminology accordingly.
526 Remove discussion about the relation to KEY (as that spec is dormant:
527 ).
529 Remove appendices "Examples" and "Discussion".
531 Mark "Use of JSON Field Value Encoding in the Wild" for removal in
532 RFC.
534 B.16. Since draft-reschke-http-jfv-12
536 Update HTTP reference and update terminology some more.
538 Update HSTRUCT reference (now RFC 8941).
540 Acknowledgements
542 Thanks go to the Hypertext Transfer Protocol Working Group
543 participants.
545 Author's Address
547 Julian F. Reschke
548 greenbytes GmbH
549 Hafenweg 16
550 48155 Münster
551 Germany
553 Email: julian.reschke@greenbytes.de
554 URI: http://greenbytes.de/tech/webdav/