idnits 2.17.1
draft-reschke-http-jfv-09.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 292: '... 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 (July 2, 2018) is 2118 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)
-- Looks like a reference, but probably isn't: '1' on line 426
-- Looks like a reference, but probably isn't: '2' on line 428
** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112)
** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110)
== Outdated reference: A later version (-19) exists of
draft-ietf-httpbis-header-structure-07
-- Obsolete informational reference (is this intentional?): RFC 7235
(Obsoleted by RFC 9110)
Summary: 5 errors (**), 0 flaws (~~), 2 warnings (==), 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, 2018
5 Expires: January 3, 2019
7 A JSON Encoding for HTTP Header Field Values
8 draft-reschke-http-jfv-09
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 ietf-http-
20 wg@w3.org [1], which may be joined by sending a message with subject
21 "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 E.12.
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 https://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 January 3, 2019.
48 Copyright Notice
50 Copyright (c) 2018 IETF Trust and the persons identified as the
51 document authors. All rights reserved.
53 This document is subject to BCP 78 and the IETF Trust's Legal
54 Provisions Relating to IETF Documents
55 (https://trustee.ietf.org/license-info) in effect on the date of
56 publication of this document. Please review these documents
57 carefully, as they describe your rights and restrictions with respect
58 to this document. Code Components extracted from this document must
59 include Simplified BSD License text as described in Section 4.e of
60 the Trust Legal Provisions and are provided without warranty as
61 described in the Simplified BSD License.
63 Table of Contents
65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
66 2. Data Model and Format . . . . . . . . . . . . . . . . . . . . 4
67 3. Sender Requirements . . . . . . . . . . . . . . . . . . . . . 5
68 4. Recipient Requirements . . . . . . . . . . . . . . . . . . . 5
69 5. Using this Format in Header Field Definitions . . . . . . . . 5
70 6. Deployment Considerations . . . . . . . . . . . . . . . . . . 6
71 7. Interoperability Considerations . . . . . . . . . . . . . . . 6
72 7.1. Encoding and Characters . . . . . . . . . . . . . . . . . 6
73 7.2. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 6
74 7.3. Object Constraints . . . . . . . . . . . . . . . . . . . 7
75 8. Internationalization Considerations . . . . . . . . . . . . . 7
76 9. Security Considerations . . . . . . . . . . . . . . . . . . . 7
77 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 7
78 10.1. Normative References . . . . . . . . . . . . . . . . . . 7
79 10.2. Informative References . . . . . . . . . . . . . . . . . 8
80 10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 9
81 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10
82 A.1. Content-Length . . . . . . . . . . . . . . . . . . . . . 10
83 A.2. Content-Disposition . . . . . . . . . . . . . . . . . . . 10
84 A.3. WWW-Authenticate . . . . . . . . . . . . . . . . . . . . 11
85 A.4. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 12
86 Appendix B. Use of JSON Field Value Encoding in the Wild . . . . 13
87 B.1. W3C Reporting API Specification . . . . . . . . . . . . . 14
88 B.2. W3C Clear Site Data Specification . . . . . . . . . . . . 14
89 B.3. W3C Feature Policy Specification . . . . . . . . . . . . 14
90 Appendix C. Relation to HTTP 'Key' Header Field . . . . . . . . 14
91 Appendix D. Discussion . . . . . . . . . . . . . . . . . . . . . 14
92 Appendix E. Change Log (to be removed by RFC Editor before
93 publication) . . . . . . . . . . . . . . . . . . . . 14
94 E.1. Since draft-reschke-http-jfv-00 . . . . . . . . . . . . . 15
95 E.2. Since draft-reschke-http-jfv-01 . . . . . . . . . . . . . 15
96 E.3. Since draft-reschke-http-jfv-02 . . . . . . . . . . . . . 15
97 E.4. Since draft-reschke-http-jfv-03 . . . . . . . . . . . . . 15
98 E.5. Since draft-reschke-http-jfv-04 . . . . . . . . . . . . . 15
99 E.6. Since draft-ietf-httpbis-jfv-00 . . . . . . . . . . . . . 15
100 E.7. Since draft-ietf-httpbis-jfv-01 . . . . . . . . . . . . . 15
101 E.8. Since draft-ietf-httpbis-jfv-02 . . . . . . . . . . . . . 15
102 E.9. Since draft-reschke-http-jfv-05 . . . . . . . . . . . . . 16
103 E.10. Since draft-reschke-http-jfv-06 . . . . . . . . . . . . . 16
104 E.11. Since draft-reschke-http-jfv-07 . . . . . . . . . . . . . 16
105 E.12. Since draft-reschke-http-jfv-08 . . . . . . . . . . . . . 16
106 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16
107 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
109 1. Introduction
111 Defining syntax for new HTTP header fields ([RFC7230], Section 3.2)
112 is non-trivial. Among the commonly encountered problems are:
114 o There is no common syntax for complex field values. Several well-
115 known header fields do use a similarly looking syntax, but it is
116 hard to write generic parsing code that will both correctly handle
117 valid field values but also reject invalid ones.
119 o The HTTP message format allows header fields to repeat, so field
120 syntax needs to be designed in a way that these cases are either
121 meaningful, or can be unambiguously detected and rejected.
123 o HTTP/1.1 does not define a character encoding scheme ([RFC6365],
124 Section 2), so header fields are either stuck with US-ASCII
125 ([RFC0020]), or need out-of-band information to decide what
126 encoding scheme is used. Furthermore, APIs usually assume a
127 default encoding scheme in order to map from octet sequences to
128 strings (for instance, [XMLHttpRequest] uses the IDL type
129 "ByteString", effectively resulting in the ISO-8859-1 character
130 encoding scheme [ISO-8859-1] being used).
132 (See Section 8.3.1 of [RFC7231] for a summary of considerations for
133 new header fields.)
135 This specification addresses the issues listed above by defining both
136 a generic JSON-based ([RFC8259]) data model and a concrete wire
137 format that can be used in definitions of new header fields, where
138 the goals were:
140 o to be compatible with header field recombination when fields occur
141 multiple times in a single message (Section 3.2.2 of [RFC7230]),
142 and
144 o not to use any problematic characters in the field value (non-
145 ASCII characters and certain whitespace characters).
147 Note: [HSTRUCT], a work item of the IETF HTTP Working Group, is a
148 different attempt to address this set of problems -- it tries to
149 identify and formalize common field structures in existing header
150 fields; the syntax defined over there would usually lead to a more
151 compact notation.
153 2. Data Model and Format
155 In HTTP, header fields with the same field name can occur multiple
156 times within a single message (Section 3.2.2 of [RFC7230]). When
157 this happens, recipients are allowed to combine the field values
158 using commas as delimiter. This rule matches nicely JSON's array
159 format (Section 5 of [RFC8259]). Thus, the basic data model used
160 here is the JSON array.
162 Header field definitions that need only a single value can restrict
163 themselves to arrays of length 1, and are encouraged to define error
164 handling in case more values are received (such as "first wins",
165 "last wins", or "abort with fatal error message").
167 JSON arrays are mapped to field values by creating a sequence of
168 serialized member elements, separated by commas and optionally
169 whitespace. This is equivalent to using the full JSON array format,
170 while leaving out the "begin-array" ('[') and "end-array" (']')
171 delimiters.
173 The ABNF character names and classes below are used (copied from
174 [RFC5234], Appendix B.1):
176 CR = %x0D ; carriage return
177 HTAB = %x09 ; horizontal tab
178 LF = %x0A ; line feed
179 SP = %x20 ; space
180 VCHAR = %x21-7E ; visible (printing) characters
182 Characters in JSON strings that are not allowed or discouraged in
183 HTTP header field values -- that is, not in the "VCHAR" definition --
184 need to be represented using JSON's "backslash" escaping mechanism
185 ([RFC8259], Section 7).
187 The control characters CR, LF, and HTAB do not appear inside JSON
188 strings, but can be used outside (line breaks, indentation etc.).
189 These characters need to be either stripped or replaced by space
190 characters (ABNF "SP").
192 Formally, using the HTTP specification's ABNF extensions defined in
193 Section 7 of [RFC7230]:
195 json-field-value = #json-field-item
196 json-field-item = JSON-Text
197 ; see [RFC8259], Section 2,
198 ; post-processed so that only VCHAR characters
199 ; are used
201 3. Sender Requirements
203 To map a JSON array to an HTTP header field value, process each array
204 element separately by:
206 1. generating the JSON representation,
208 2. stripping all JSON control characters (CR, HTAB, LF), or
209 replacing them by space ("SP") characters,
211 3. replacing all remaining non-VSPACE characters by the equivalent
212 backslash-escape sequence ([RFC8259], Section 7).
214 The resulting list of strings is transformed into an HTTP field value
215 by combining them using comma (%x2C) plus optional SP as delimiter,
216 and encoding the resulting string into an octet sequence using the
217 US-ASCII character encoding scheme ([RFC0020]).
219 4. Recipient Requirements
221 To map a set of HTTP header field instances to a JSON array:
223 1. combine all header field instances into a single field as per
224 Section 3.2.2 of [RFC7230],
226 2. add a leading begin-array ("[") octet and a trailing end-array
227 ("]") octet, then
229 3. run the resulting octet sequence through a JSON parser.
231 The result of the parsing operation is either an error (in which case
232 the header field values needs to be considered invalid), or a JSON
233 array.
235 5. Using this Format in Header Field Definitions
237 Specifications defining new HTTP header fields need to take the
238 considerations listed in Section 8.3.1 of [RFC7231] into account.
240 Many of these will already be accounted for by using the format
241 defined in this specification.
243 Readers of HTTP-related specifications frequently expect an ABNF
244 definition of the field value syntax. This is not really needed
245 here, as the actual syntax is JSON text, as defined in Section 2 of
246 [RFC8259].
248 A very simple way to use this JSON encoding thus is just to cite this
249 specification -- specifically the "json-field-value" ABNF production
250 defined in Section 2 -- and otherwise not to talk about the details
251 of the field syntax at all.
253 An alternative approach is just to repeat the ABNF-related parts from
254 Section 2.
256 This frees the specification from defining the concrete on-the-wire
257 syntax. What's left is defining the field value in terms of a JSON
258 array. An important aspect is the question of extensibility, e.g.
259 how recipients ought to treat unknown field names. In general, a
260 "must ignore" approach will allow protocols to evolve without
261 versioning or even using entire new field names.
263 6. Deployment Considerations
265 This JSON-based syntax will only apply to newly introduced header
266 fields, thus backwards compatibility is not a problem. That being
267 said, it is conceivable that there is existing code that might trip
268 over double quotes not being used for HTTP's quoted-string syntax
269 (Section 3.2.6 of [RFC7230]).
271 7. Interoperability Considerations
273 The "I-JSON Message Format" specification ([RFC7493]) addresses known
274 JSON interoperability pain points. This specification borrows from
275 the requirements made over there:
277 7.1. Encoding and Characters
279 This specification requires that field values use only US-ASCII
280 characters, and thus by definition use a subset of UTF-8 (Section 2.1
281 of [RFC7493]).
283 7.2. Numbers
285 Be aware of the issues around number precision, as discussed in
286 Section 2.2 of [RFC7493].
288 7.3. Object Constraints
290 As described in Section 4 of [RFC8259], JSON parser implementations
291 differ in the handling of duplicate object names. Therefore, senders
292 MUST NOT use duplicate object names, and recipients SHOULD either
293 treat field values with duplicate names as invalid (consistent with
294 [RFC7493], Section 2.3) or use the lexically last value (consistent
295 with [ECMA-262], Section 24.3.1.1).
297 Furthermore, ordering of object members is not significant and can
298 not be relied upon.
300 8. Internationalization Considerations
302 In HTTP/1.1, header field values are represented by octet sequences,
303 usually used to transmit ASCII characters, with restrictions on the
304 use of certain control characters, and no associated default
305 character encoding, nor a way to describe it ([RFC7230],
306 Section 3.2). HTTP/2 does not change this.
308 This specification maps all characters which can cause problems to
309 JSON escape sequences, thereby solving the HTTP header field
310 internationalization problem.
312 Future specifications of HTTP might change to allow non-ASCII
313 characters natively. In that case, header fields using the syntax
314 defined by this specification would have a simple migration path (by
315 just stopping to require escaping of non-ASCII characters).
317 9. Security Considerations
319 Using JSON-shaped field values is believed to not introduce any new
320 threads beyond those described in Section 12 of [RFC8259], namely the
321 risk of recipients using the wrong tools to parse them.
323 Other than that, any syntax that makes extensions easy can be used to
324 smuggle information through field values; however, this concern is
325 shared with other widely used formats, such as those using parameters
326 in the form of name/value pairs.
328 10. References
330 10.1. Normative References
332 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80,
333 RFC 20, DOI 10.17487/RFC0020, October 1969,
334 .
336 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
337 Specifications: ABNF", STD 68, RFC 5234,
338 DOI 10.17487/RFC5234, January 2008,
339 .
341 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
342 Protocol (HTTP/1.1): Message Syntax and Routing",
343 RFC 7230, DOI 10.17487/RFC7230, June 2014,
344 .
346 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
347 Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
348 DOI 10.17487/RFC7231, June 2014,
349 .
351 [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC 7493,
352 DOI 10.17487/RFC7493, March 2015,
353 .
355 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
356 Interchange Format", RFC 8259, DOI 10.17487/RFC8259,
357 December 2017, .
359 10.2. Informative References
361 [CLEARSITE]
362 West, M., "Clear Site Data", W3C Working Draft WD-clear-
363 site-data-20171130, November 2017,
364 .
366 Latest version available at .
369 [ECMA-262]
370 Ecma International, "ECMA-262 6th Edition, The ECMAScript
371 2015 Language Specification", Standard ECMA-262, June
372 2015, .
374 [FEATUREPOL]
375 Clelland, I., "Feature Policy", W3C Draft Community Group
376 Report , June 2018,
377 .
379 [HSTRUCT] Nottingham, M. and P-H. Kamp, "Structured Headers for
380 HTTP", draft-ietf-httpbis-header-structure-07 (work in
381 progress), July 2018.
383 [ISO-8859-1]
384 International Organization for Standardization,
385 "Information technology -- 8-bit single-byte coded graphic
386 character sets -- Part 1: Latin alphabet No. 1", ISO/
387 IEC 8859-1:1998, 1998.
389 [KEY] Fielding, R. and M. Nottingham, "The Key HTTP Response
390 Header Field", draft-ietf-httpbis-key-01 (work in
391 progress), March 2016.
393 [REPORTING]
394 Grigorik, I. and M. West, "Reporting API 1", W3C Group
395 Note NOTE-reporting-1-20160607, June 2016,
396 .
398 Latest version available at .
401 [RFC6266] Reschke, J., "Use of the Content-Disposition Header Field
402 in the Hypertext Transfer Protocol (HTTP)", RFC 6266,
403 DOI 10.17487/RFC6266, June 2011,
404 .
406 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in
407 Internationalization in the IETF", BCP 166, RFC 6365,
408 DOI 10.17487/RFC6365, September 2011,
409 .
411 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
412 Protocol (HTTP/1.1): Authentication", RFC 7235,
413 DOI 10.17487/RFC7235, June 2014,
414 .
416 [RFC8187] Reschke, J., "Indicating Character Encoding and Language
417 for HTTP Header Field Parameters", RFC 8187,
418 DOI 10.17487/RFC8187, September 2017,
419 .
421 [XMLHttpRequest]
422 WhatWG, "XMLHttpRequest", .
424 10.3. URIs
426 [1] mailto:ietf-http-wg@w3.org
428 [2] mailto:ietf-http-wg-request@w3.org?subject=subscribe
430 Appendix A. Examples
432 This section shows how some of the existing HTTP header fields would
433 look like if they would use the format defined by this specification.
435 A.1. Content-Length
437 "Content-Length" is defined in Section 3.3.2 of [RFC7230], with the
438 field value's ABNF being:
440 Content-Length = 1*DIGIT
442 So the field value is similar to a JSON number ([RFC8259],
443 Section 6).
445 Content-Length is restricted to a single field instance, as it
446 doesn't use the list production (as per Section 3.2.2 of [RFC7230]).
447 However, in practice multiple instances do occur, and the definition
448 of the header field does indeed discuss how to handle these cases.
450 If Content-Length was defined using the JSON format discussed here,
451 the ABNF would be something like:
453 Content-Length = #number
454 ; number: [RFC8259], Section 6
456 ...and the prose definition would:
458 o restrict all numbers to be non-negative integers without
459 fractions, and
461 o require that the array of values is of length 1 (but allow the
462 case where the array is longer, but all members represent the same
463 value)
465 A.2. Content-Disposition
467 Content-Disposition field values, defined in [RFC6266], consist of a
468 "disposition type" (a string), plus multiple parameters, of which at
469 least one ("filename") sometime needs to carry non-ASCII characters.
471 For instance, the first example in Section 5 of [RFC6266]:
473 Attachment; filename=example.html
475 has a disposition type of "Attachment", with filename parameter value
476 "example.html". A JSON representation of this information might be:
478 {
479 "Attachment": {
480 "filename" : "example.html"
481 }
482 }
484 which would translate to a header field value of:
486 { "Attachment": { "filename" : "example.html" } }
488 The third example in Section 5 of [RFC6266] uses a filename parameter
489 containing non-US-ASCII characters:
491 attachment; filename*=UTF-8''%e2%82%ac%20rates
493 Note that in this case, the "filename*" parameter uses the encoding
494 defined in [RFC8187], representing a filename starting with the
495 Unicode character U+20AC (EURO SIGN), followed by " rates". If the
496 definition of Content-Disposition would have used the format proposed
497 here, the workaround involving the "parameter*" syntax would not have
498 been needed at all.
500 The JSON representation of this value could then be:
502 { "attachment": { "filename" : "\u20AC rates" } }
504 A.3. WWW-Authenticate
506 The WWW-Authenticate header field value is defined in Section 4.1 of
507 [RFC7235] as a list of "challenges":
509 WWW-Authenticate = 1#challenge
511 ...where a challenge consists of a scheme with optional parameters:
513 challenge = auth-scheme [ 1*SP ( token68 / #auth-param ) ]
515 An example for a complex header field value given in the definition
516 of the header field is:
518 Newauth realm="apps", type=1, title="Login to \"apps\"",
519 Basic realm="simple"
521 (line break added for readability)
523 A possible JSON representation of this field value would be the array
524 below:
526 [
527 {
528 "Newauth" : {
529 "realm": "apps",
530 "type" : 1,
531 "title" : "Login to \"apps\""
532 }
533 },
534 {
535 "Basic" : {
536 "realm": "simple"
537 }
538 }
539 ]
541 ...which would translate to a header field value of:
543 { "Newauth" : { "realm": "apps", "type" : 1,
544 "title": "Login to \"apps\"" }},
545 { "Basic" : { "realm": "simple"}}
547 A.4. Accept-Encoding
549 The Accept-Encoding header field value is defined in Section 5.3.4 of
550 [RFC7231] as a list of codings, each of which allowing a weight
551 parameter 'q':
553 Accept-Encoding = #( codings [ weight ] )
554 codings = content-coding / "identity" / "*"
555 weight = OWS ";" OWS "q=" qvalue
556 qvalue = ( "0" [ "." 0*3DIGIT ] )
557 / ( "1" [ "." 0*3("0") ] )
559 An example for a complex header field value given in the definition
560 of the header field is:
562 gzip;q=1.0, identity; q=0.5, *;q=0
564 Due to the defaulting rules for the quality value ([RFC7231],
565 Section 5.3.1), this could also be written as:
567 gzip, identity; q=0.5, *; q=0
569 A JSON representation could be:
571 [
572 {
573 "gzip" : {
574 }
575 },
576 {
577 "identity" : {
578 "q": 0.5
579 }
580 },
581 {
582 "*" : {
583 "q": 0
584 }
585 }
586 ]
588 ...which would translate to a header field value of:
590 {"gzip": {}}, {"identity": {"q": 0.5}}, {"*": {"q": 0}}
592 In this example, the part about "gzip" appears unnecessarily verbose,
593 as the value is just an empty object. A simpler notation would
594 collapse members like these to string literals:
596 "gzip", {"identity": {"q": 0.5}}, {"*": {"q": 0}}
598 If this is desirable, the header field definition could allow both
599 string literals and objects, and define that a mere string literal
600 would be mapped to a member whose name is given by the string
601 literal, and the value is an empty object.
603 For what it's worth, one of the most common cases for 'Accept-
604 Encoding' would become:
606 "gzip", "deflate"
608 which would be only a small overhead over the original format.
610 Appendix B. Use of JSON Field Value Encoding in the Wild
612 Since work started on this document, various specifications have
613 adopted this format. At least one of these moved away after the HTTP
614 Working Group decided to focus on [HSTRUCT] (see thread starting at
615 ).
618 The sections below summarize the current usage of this format.
620 B.1. W3C Reporting API Specification
622 Defined in W3C Note "Reporting API 1" (Section 3.1 of [REPORTING]).
623 Still in use in latest editor copy as of June 2017.
625 B.2. W3C Clear Site Data Specification
627 Used in earlier versions of "Clear Site Data". The current version
628 replaces the use of JSON with a custom syntax that happens to be
629 somewhat compatible with an array of JSON strings (see Section 3.1 of
630 [CLEARSITE] and for feedback).
633 B.3. W3C Feature Policy Specification
635 Originally defined in W3C Draft Community Group Report "Feature
636 Policy" ([FEATUREPOL]), but now replaced with a custom syntax (see
637 ).
639 Appendix C. Relation to HTTP 'Key' Header Field
641 [KEY] aims to improve the cacheability of responses that vary based
642 on certain request header fields, addressing lack of granularity in
643 the existing "Vary" response header field ([RFC7231], Section 7.1.4).
644 If the JSON-based format described by this document gains popularity,
645 it might be useful to add a JSON-aware "Key Parameter" (see
646 Section 2.3 of [KEY]).
648 Appendix D. Discussion
650 This approach uses a default of "JSON array", using implicit array
651 markers. An alternative would be a default of "JSON object". This
652 would simplify the syntax for non-list-typed header fields, but all
653 the benefits of having the same data model for both types of header
654 fields would be gone. A hybrid approach might make sense, as long as
655 it doesn't require any heuristics on the recipient's side.
657 Note: a concrete proposal was made by Kazuho Oku in
658 .
661 [[CREF1: Use of generic libs vs compactness of field values..]]
663 Appendix E. Change Log (to be removed by RFC Editor before publication)
664 E.1. Since draft-reschke-http-jfv-00
666 Editorial fixes + working on the TODOs.
668 E.2. Since draft-reschke-http-jfv-01
670 Mention slightly increased risk of smuggling information in header
671 field values.
673 E.3. Since draft-reschke-http-jfv-02
675 Mention Kazuho Oku's proposal for abbreviated forms.
677 Added a bit of text about the motivation for a concrete JSON subset
678 (ack Cory Benfield).
680 Expand I18N section.
682 E.4. Since draft-reschke-http-jfv-03
684 Mention relation to KEY header field.
686 E.5. Since draft-reschke-http-jfv-04
688 Between June and December 2016, this was a work item of the HTTP
689 working group (see ). Work (if any) continues now on
691 .
693 Changes made while this was a work item of the HTTP Working Group:
695 E.6. Since draft-ietf-httpbis-jfv-00
697 Added example for "Accept-Encoding" (inspired by Kazuho's feedback),
698 showing a potential way to optimize the format when default values
699 apply.
701 E.7. Since draft-ietf-httpbis-jfv-01
703 Add interop discussion, building on I-JSON and ECMA-262 (see
704 ).
706 E.8. Since draft-ietf-httpbis-jfv-02
708 Move non-essential parts into appendix.
710 Updated XHR reference.
712 E.9. Since draft-reschke-http-jfv-05
714 Add meat to "Using this Format in Header Field Definitions".
716 Add a few lines on the relation to "Key".
718 Summarize current use of the format.
720 E.10. Since draft-reschke-http-jfv-06
722 RFC 5987 is obsoleted by RFC 8187.
724 Update CLEARSITE comment.
726 E.11. Since draft-reschke-http-jfv-07
728 Update JSON and HSTRUCT references.
730 FEATUREPOL doesn't use JSON syntax anymore.
732 E.12. Since draft-reschke-http-jfv-08
734 Update HSTRUCT reference.
736 Update notes about CLEARSITE and FEATUREPOL.
738 Acknowledgements
740 Thanks go to the Hypertext Transfer Protocol Working Group
741 participants.
743 Author's Address
745 Julian F. Reschke
746 greenbytes GmbH
747 Hafenweg 16
748 Muenster, NW 48155
749 Germany
751 EMail: julian.reschke@greenbytes.de
752 URI: http://greenbytes.de/tech/webdav/