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/