draft-ietf-httpbis-jfv-00.txt   draft-ietf-httpbis-jfv-01.txt 
HTTP Working Group J. Reschke HTTP Working Group J. Reschke
Internet-Draft greenbytes Internet-Draft greenbytes
Intended status: Standards Track June 24, 2016 Intended status: Standards Track July 8, 2016
Expires: December 26, 2016 Expires: January 9, 2017
A JSON Encoding for HTTP Header Field Values A JSON Encoding for HTTP Header Field Values
draft-ietf-httpbis-jfv-00 draft-ietf-httpbis-jfv-01
Abstract Abstract
This document establishes a convention for use of JSON-encoded field This document establishes a convention for use of JSON-encoded field
values in HTTP header fields. values in HTTP header fields.
Editorial Note (To be removed by RFC Editor before publication) Editorial Note (To be removed by RFC Editor before publication)
Discussion of this draft takes place on the HTTPBIS working group Discussion of this draft takes place on the HTTPBIS working group
mailing list (ietf-http-wg@w3.org), which is archived at mailing list (ietf-http-wg@w3.org), which is archived at
skipping to change at page 1, line 43 skipping to change at page 1, line 43
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 26, 2016. This Internet-Draft will expire on January 9, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 26 skipping to change at page 2, line 26
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Data Model and Format . . . . . . . . . . . . . . . . . . . . 3 2. Data Model and Format . . . . . . . . . . . . . . . . . . . . 3
3. Sender Requirements . . . . . . . . . . . . . . . . . . . . . 4 3. Sender Requirements . . . . . . . . . . . . . . . . . . . . . 4
4. Recipient Requirements . . . . . . . . . . . . . . . . . . . . 5 4. Recipient Requirements . . . . . . . . . . . . . . . . . . . . 5
5. Using this Format in Header Field Definitions . . . . . . . . 5 5. Using this Format in Header Field Definitions . . . . . . . . 5
6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
6.1. Content-Length . . . . . . . . . . . . . . . . . . . . . . 5 6.1. Content-Length . . . . . . . . . . . . . . . . . . . . . . 5
6.2. Content-Disposition . . . . . . . . . . . . . . . . . . . 6 6.2. Content-Disposition . . . . . . . . . . . . . . . . . . . 6
6.3. WWW-Authenticate . . . . . . . . . . . . . . . . . . . . . 7 6.3. WWW-Authenticate . . . . . . . . . . . . . . . . . . . . . 7
7. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 8 6.4. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 8
8. Deployment Considerations . . . . . . . . . . . . . . . . . . 8 7. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 9
9. Internationalization Considerations . . . . . . . . . . . . . 8 8. Deployment Considerations . . . . . . . . . . . . . . . . . . 9
10. Security Considerations . . . . . . . . . . . . . . . . . . . 8 9. Internationalization Considerations . . . . . . . . . . . . . 9
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 10. Security Considerations . . . . . . . . . . . . . . . . . . . 10
11.1. Normative References . . . . . . . . . . . . . . . . . . . 9 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10
11.2. Informative References . . . . . . . . . . . . . . . . . . 9 11.1. Normative References . . . . . . . . . . . . . . . . . . . 10
11.2. Informative References . . . . . . . . . . . . . . . . . . 11
Appendix A. Change Log (to be removed by RFC Editor before Appendix A. Change Log (to be removed by RFC Editor before
publication) . . . . . . . . . . . . . . . . . . . . 10 publication) . . . . . . . . . . . . . . . . . . . . 11
A.1. Since draft-reschke-http-jfv-00 . . . . . . . . . . . . . 10 A.1. Since draft-reschke-http-jfv-00 . . . . . . . . . . . . . 11
A.2. Since draft-reschke-http-jfv-01 . . . . . . . . . . . . . 10 A.2. Since draft-reschke-http-jfv-01 . . . . . . . . . . . . . 12
A.3. Since draft-reschke-http-jfv-02 . . . . . . . . . . . . . 10 A.3. Since draft-reschke-http-jfv-02 . . . . . . . . . . . . . 12
A.4. Since draft-reschke-http-jfv-03 . . . . . . . . . . . . . 11 A.4. Since draft-reschke-http-jfv-03 . . . . . . . . . . . . . 12
A.5. Since draft-reschke-http-jfv-04 . . . . . . . . . . . . . 11 A.5. Since draft-reschke-http-jfv-04 . . . . . . . . . . . . . 12
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 11 A.6. Since draft-ietf-httpbis-jfv-00 . . . . . . . . . . . . . 12
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 12
1. Introduction 1. Introduction
Defining syntax for new HTTP header fields ([RFC7230], Section 3.2) Defining syntax for new HTTP header fields ([RFC7230], Section 3.2)
is non-trivial. Among the commonly encountered problems are: is non-trivial. Among the commonly encountered problems are:
o There is no common syntax for complex field values. Several well- o There is no common syntax for complex field values. Several well-
known header fields do use a similarly looking syntax, but it is known header fields do use a similarly looking syntax, but it is
hard to write generic parsing code that will both correctly handle hard to write generic parsing code that will both correctly handle
valid field values but also reject invalid ones. valid field values but also reject invalid ones.
skipping to change at page 4, line 29 skipping to change at page 4, line 29
LF = %x0A ; line feed LF = %x0A ; line feed
SP = %x20 ; space SP = %x20 ; space
VCHAR = %x21-7E ; visible (printing) characters VCHAR = %x21-7E ; visible (printing) characters
Characters in JSON strings that are not allowed or discouraged in Characters in JSON strings that are not allowed or discouraged in
HTTP header field values -- that is, not in the "VCHAR" definition -- HTTP header field values -- that is, not in the "VCHAR" definition --
need to be represented using JSON's "backslash" escaping mechanism need to be represented using JSON's "backslash" escaping mechanism
([RFC7159], Section 7). ([RFC7159], Section 7).
The control characters CR, LF, and HTAB do not appear inside JSON The control characters CR, LF, and HTAB do not appear inside JSON
strings, but can be used outside (line breaks, indentation etc). strings, but can be used outside (line breaks, indentation etc.).
These characters need to be either stripped or replaced by space These characters need to be either stripped or replaced by space
characters (ABNF "SP"). characters (ABNF "SP").
Formally, using the HTTP specification's ABNF extensions defined in Formally, using the HTTP specification's ABNF extensions defined in
Section 7 of [RFC7230]: Section 7 of [RFC7230]:
json-field-value = #json-field-item json-field-value = #json-field-item
json-field-item = JSON-Text json-field-item = JSON-Text
; see [RFC7159], Section 2, ; see [RFC7159], Section 2,
; post-processed so that only VCHAR characters ; post-processed so that only VCHAR characters
skipping to change at page 5, line 32 skipping to change at page 5, line 32
3. run the resulting octet sequence through a JSON parser. 3. run the resulting octet sequence through a JSON parser.
The result of the parsing operation is either an error (in which case The result of the parsing operation is either an error (in which case
the header field values needs to be considered invalid), or a JSON the header field values needs to be considered invalid), or a JSON
array. array.
5. Using this Format in Header Field Definitions 5. Using this Format in Header Field Definitions
[[anchor5: Explain what a definition of a new header field needs to [[anchor5: Explain what a definition of a new header field needs to
do precisely to use this format, mention must-ignore extensibiliy]] do precisely to use this format, mention must-ignore extensibility]]
6. Examples 6. Examples
This section shows how some of the existing HTTP header fields would This section shows how some of the existing HTTP header fields would
look like if they would use the format defined by this specification. look like if they would use the format defined by this specification.
6.1. Content-Length 6.1. Content-Length
"Content-Length" is defined in Section 3.3.2 of [RFC7230], with the "Content-Length" is defined in Section 3.3.2 of [RFC7230], with the
field value's ABNF being: field value's ABNF being:
skipping to change at page 8, line 5 skipping to change at page 8, line 5
} }
} }
] ]
...which would translate to a header field value of: ...which would translate to a header field value of:
{ "Newauth" : { "realm": "apps", "type" : 1, { "Newauth" : { "realm": "apps", "type" : 1,
"title": "Login to \"apps\"" }}, "title": "Login to \"apps\"" }},
{ "Basic" : { "realm": "simple"}} { "Basic" : { "realm": "simple"}}
6.4. Accept-Encoding
The Accept-Encoding header field value is defined in Section 5.3.4 of
[RFC7231] as a list of codings, each of which allowing a weight
parameter 'q':
Accept-Encoding = #( codings [ weight ] )
codings = content-coding / "identity" / "*"
weight = OWS ";" OWS "q=" qvalue
qvalue = ( "0" [ "." 0*3DIGIT ] )
/ ( "1" [ "." 0*3("0") ] )
An example for a complex header field value given in the definition
of the header field is:
gzip;q=1.0, identity; q=0.5, *;q=0
Due to the defaulting rules for the quality value ([RFC7231], Section
5.3.1), this could also be written as:
gzip, identity; q=0.5, *; q=0
A JSON representation could be:
[
{
"gzip" : {
}
},
{
"identity" : {
"q": 0.5
}
},
{
"*" : {
"q": 0
}
}
]
...which would translate to a header field value of:
{"gzip": {}}, {"identity": {"q": 0.5}}, {"*": {"q": 0}}
In this example, the part about "gzip" appears unnecessarily verbose,
as the value is just an empty object. A simpler notation would
collapse members like these to string literals:
"gzip", {"identity": {"q": 0.5}}, {"*": {"q": 0}}
If this is desirable, the header field definition could allow both
string literals and objects, and define that a mere string literal
would be mapped to a member whose name is given by the string
literal, and the value is an empty object.
For what it's worth, one of the most common cases for 'Accept-
Encoding' would become:
"gzip", "deflate"
which would be only a small overhead over the original format.
7. Discussion 7. Discussion
This approach uses a default of "JSON array", using implicit array This approach uses a default of "JSON array", using implicit array
markers. An alternative would be a default of "JSON object". This markers. An alternative would be a default of "JSON object". This
would simplify the syntax for non-list-typed header fields, but all would simplify the syntax for non-list-typed header fields, but all
the benefits of having the same data model for both types of header the benefits of having the same data model for both types of header
fields would be gone. A hybrid approach might make sense, as long as fields would be gone. A hybrid approach might make sense, as long as
it doesn't require any heuristics on the recipient's side. it doesn't require any heuristics on the recipient's side.
Note: a concrete proposal was made by Kazuho Oku in <https:// Note: a concrete proposal was made by Kazuho Oku in <https://
skipping to change at page 11, line 13 skipping to change at page 12, line 27
Expand I18N section. Expand I18N section.
A.4. Since draft-reschke-http-jfv-03 A.4. Since draft-reschke-http-jfv-03
Mention relation to KEY header field. Mention relation to KEY header field.
A.5. Since draft-reschke-http-jfv-04 A.5. Since draft-reschke-http-jfv-04
Change to HTTP Working Group draft. Change to HTTP Working Group draft.
A.6. Since draft-ietf-httpbis-jfv-00
Added example for "Accept-Encoding" (inspired by Kazuho's feedback),
showing a potential way to optimize the format when default values
apply.
Appendix B. Acknowledgements Appendix B. Acknowledgements
Thanks go to the Hypertext Transfer Protocol Working Group Thanks go to the Hypertext Transfer Protocol Working Group
participants. participants.
Author's Address Author's Address
Julian F. Reschke Julian F. Reschke
greenbytes GmbH greenbytes GmbH
Hafenweg 16 Hafenweg 16
 End of changes. 9 change blocks. 
20 lines changed or deleted 91 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/