draft-reschke-http-jfv-10.txt		draft-reschke-http-jfv-11.txt
	Network Working Group J. F. Reschke		Network Working Group J. F. Reschke
	Internet-Draft greenbytes		Internet-Draft greenbytes
	Intended status: Informational 14 October 2019		Intended status: Informational 20 November 2019
	Expires: 16 April 2020		Expires: 23 May 2020
	A JSON Encoding for HTTP Header Field Values		A JSON Encoding for HTTP Header Field Values
	draft-reschke-http-jfv-10		draft-reschke-http-jfv-11
	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		Editorial Note
	This note is to be removed before publishing as an RFC.		This note is to be removed before publishing as an RFC.
	skipping to change at page 1, line 34 ¶		skipping to change at page 1, line 34 ¶
	sending a message with subject "subscribe" to ietf-http-wg-		sending a message with subject "subscribe" to ietf-http-wg-
	request@w3.org (mailto:ietf-http-wg-		request@w3.org (mailto:ietf-http-wg-
	request@w3.org?subject=subscribe).		request@w3.org?subject=subscribe).
	Discussions of the HTTPbis Working Group are archived at		Discussions of the HTTPbis Working Group are archived at
	http://lists.w3.org/Archives/Public/ietf-http-wg/.		http://lists.w3.org/Archives/Public/ietf-http-wg/.
	XML versions and latest edits for this document are available from		XML versions and latest edits for this document are available from
	http://greenbytes.de/tech/webdav/#draft-reschke-http-jfv.		http://greenbytes.de/tech/webdav/#draft-reschke-http-jfv.
	The changes in this draft are summarized in Appendix E.13.		The changes in this draft are summarized in Appendix E.14.
	Status of This Memo		Status of This Memo
	This Internet-Draft is submitted in full conformance with the		This Internet-Draft is submitted in full conformance with the
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	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 https://datatracker.ietf.org/drafts/current/.		Drafts is at https://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 16 April 2020.		This Internet-Draft will expire on 23 May 2020.
	Copyright Notice		Copyright Notice
	Copyright (c) 2019 IETF Trust and the persons identified as the		Copyright (c) 2019 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 (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	skipping to change at page 2, line 26 ¶		skipping to change at page 2, line 26 ¶
	extracted from this document must include Simplified BSD License text		extracted from this document must include Simplified BSD License text
	as described in Section 4.e of the Trust Legal Provisions and are		as described in Section 4.e of the Trust Legal Provisions and are
	provided without warranty as described in the Simplified BSD License.		provided without warranty as described in the Simplified BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
	2. Data Model and Format . . . . . . . . . . . . . . . . . . . . 4		2. Data Model and Format . . . . . . . . . . . . . . . . . . . . 4
	3. Sender Requirements . . . . . . . . . . . . . . . . . . . . . 5		3. Sender Requirements . . . . . . . . . . . . . . . . . . . . . 5
	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 . . . . . . . . 6
	6. Deployment Considerations . . . . . . . . . . . . . . . . . . 6		6. Deployment Considerations . . . . . . . . . . . . . . . . . . 6
	7. Interoperability Considerations . . . . . . . . . . . . . . . 6		7. Interoperability Considerations . . . . . . . . . . . . . . . 6
	7.1. Encoding and Characters . . . . . . . . . . . . . . . . . 6		7.1. Encoding and Characters . . . . . . . . . . . . . . . . . 6
	7.2. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 6		7.2. Numbers . . . . . . . . . . . . . . . . . . . . . . . . . 7
	7.3. Object Constraints . . . . . . . . . . . . . . . . . . . 6		7.3. Object Constraints . . . . . . . . . . . . . . . . . . . 7
	8. Internationalization Considerations . . . . . . . . . . . . . 7		8. Internationalization Considerations . . . . . . . . . . . . . 7
	9. Security Considerations . . . . . . . . . . . . . . . . . . . 7		9. Security Considerations . . . . . . . . . . . . . . . . . . . 7
	10. References . . . . . . . . . . . . . . . . . . . . . . . . . 7		10. References . . . . . . . . . . . . . . . . . . . . . . . . . 7
	10.1. Normative References . . . . . . . . . . . . . . . . . . 7		10.1. Normative References . . . . . . . . . . . . . . . . . . 7
	10.2. Informative References . . . . . . . . . . . . . . . . . 8		10.2. Informative References . . . . . . . . . . . . . . . . . 8
	Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 9		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10
	A.1. Content-Length . . . . . . . . . . . . . . . . . . . . . 9		A.1. Content-Length . . . . . . . . . . . . . . . . . . . . . 10
	A.2. Content-Disposition . . . . . . . . . . . . . . . . . . . 10		A.2. Content-Disposition . . . . . . . . . . . . . . . . . . . 10
	A.3. WWW-Authenticate . . . . . . . . . . . . . . . . . . . . 11		A.3. WWW-Authenticate . . . . . . . . . . . . . . . . . . . . 11
	A.4. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 12		A.4. Accept-Encoding . . . . . . . . . . . . . . . . . . . . . 12
	Appendix B. Use of JSON Field Value Encoding in the		Appendix B. Use of JSON Field Value Encoding in the Wild . . . . 13
	Wild . . . . . . . . . . . . . . . . . . . . . . . . . . 13		B.1. W3C Reporting API Specification . . . . . . . . . . . . . 14
	B.1. W3C Reporting API Specification . . . . . . . . . . . . . 13		B.2. W3C Clear Site Data Specification . . . . . . . . . . . . 14
	B.2. W3C Clear Site Data Specification . . . . . . . . . . . . 13		B.3. W3C Feature Policy Specification . . . . . . . . . . . . 14
	B.3. W3C Feature Policy Specification . . . . . . . . . . . . 13
	Appendix C. Relation to HTTP 'Key' Header Field . . . . . . . . 14		Appendix C. Relation to HTTP 'Key' Header Field . . . . . . . . 14
	Appendix D. Discussion . . . . . . . . . . . . . . . . . . . . . 14		Appendix D. Discussion . . . . . . . . . . . . . . . . . . . . . 14
	Appendix E. Change Log . . . . . . . . . . . . . . . . . . . . . 14		Appendix E. Change Log . . . . . . . . . . . . . . . . . . . . . 14
	E.1. Since draft-reschke-http-jfv-00 . . . . . . . . . . . . . 14		E.1. Since draft-reschke-http-jfv-00 . . . . . . . . . . . . . 15
	E.2. Since draft-reschke-http-jfv-01 . . . . . . . . . . . . . 14		E.2. Since draft-reschke-http-jfv-01 . . . . . . . . . . . . . 15
	E.3. Since draft-reschke-http-jfv-02 . . . . . . . . . . . . . 14		E.3. Since draft-reschke-http-jfv-02 . . . . . . . . . . . . . 15
	E.4. Since draft-reschke-http-jfv-03 . . . . . . . . . . . . . 15		E.4. Since draft-reschke-http-jfv-03 . . . . . . . . . . . . . 15
	E.5. Since draft-reschke-http-jfv-04 . . . . . . . . . . . . . 15		E.5. Since draft-reschke-http-jfv-04 . . . . . . . . . . . . . 15
	E.6. Since draft-ietf-httpbis-jfv-00 . . . . . . . . . . . . . 15		E.6. Since draft-ietf-httpbis-jfv-00 . . . . . . . . . . . . . 15
	E.7. Since draft-ietf-httpbis-jfv-01 . . . . . . . . . . . . . 15		E.7. Since draft-ietf-httpbis-jfv-01 . . . . . . . . . . . . . 15
	E.8. Since draft-ietf-httpbis-jfv-02 . . . . . . . . . . . . . 15		E.8. Since draft-ietf-httpbis-jfv-02 . . . . . . . . . . . . . 15
	E.9. Since draft-reschke-http-jfv-05 . . . . . . . . . . . . . 15		E.9. Since draft-reschke-http-jfv-05 . . . . . . . . . . . . . 16
	E.10. Since draft-reschke-http-jfv-06 . . . . . . . . . . . . . 15		E.10. Since draft-reschke-http-jfv-06 . . . . . . . . . . . . . 16
	E.11. Since draft-reschke-http-jfv-07 . . . . . . . . . . . . . 15		E.11. Since draft-reschke-http-jfv-07 . . . . . . . . . . . . . 16
	E.12. Since draft-reschke-http-jfv-08 . . . . . . . . . . . . . 16		E.12. Since draft-reschke-http-jfv-08 . . . . . . . . . . . . . 16
	E.13. Since draft-reschke-http-jfv-09 . . . . . . . . . . . . . 16		E.13. Since draft-reschke-http-jfv-09 . . . . . . . . . . . . . 16
			E.14. Since draft-reschke-http-jfv-10 . . . . . . . . . . . . . 16
	Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16		Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
	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:
	* There is no common syntax for complex field values. Several well-		* 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
	skipping to change at page 4, line 37 ¶		skipping to change at page 4, line 37 ¶
	JSON arrays are mapped to field values by creating a sequence of		JSON arrays are mapped to field values by creating a sequence of
	serialized member elements, separated by commas and optionally		serialized member elements, separated by commas and optionally
	whitespace. This is equivalent to using the full JSON array format,		whitespace. This is equivalent to using the full JSON array format,
	while leaving out the "begin-array" ('[') and "end-array" (']')		while leaving out the "begin-array" ('[') and "end-array" (']')
	delimiters.		delimiters.
	The ABNF character names and classes below are used (copied from		The ABNF character names and classes below are used (copied from
	[RFC5234], Appendix B.1):		[RFC5234], Appendix B.1):
	CR = %x0D ; carriage return HTAB = %x09 ; horizontal tab LF = %x0A ; line feed SP = %x20 ; space VCHAR = %x21-7E ; visible (printing) characters		CR = %x0D ; carriage return
			HTAB = %x09 ; horizontal tab
			LF = %x0A ; line feed
			SP = %x20 ; space
			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
	([RFC8259], Section 7).		([RFC8259], 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-item = JSON-Text ; see [RFC8259], Section 2, ; post-processed so that only VCHAR characters ; are used		json-field-value = #json-field-item
			json-field-item = JSON-Text
			; see [RFC8259], Section 2,
			; post-processed so that only VCHAR characters
			; are used
	3. Sender Requirements		3. Sender Requirements
	To map a JSON array to an HTTP header field value, process each array		To map a JSON array to an HTTP header field value, process each array
	element separately by:		element separately by:
	1. generating the JSON representation,		1. generating the JSON representation,
	2. stripping all JSON control characters (CR, HTAB, LF), or		2. stripping all JSON control characters (CR, HTAB, LF), or
	replacing them by space ("SP") characters,		replacing them by space ("SP") characters,
	skipping to change at page 8, line 37 ¶		skipping to change at page 8, line 51 ¶
	[ECMA-262] Ecma International, "ECMA-262 6th Edition, The ECMAScript		[ECMA-262] Ecma International, "ECMA-262 6th Edition, The ECMAScript
	2015 Language Specification", Standard ECMA-262, June		2015 Language Specification", Standard ECMA-262, June
	2015, <http://www.ecma-international.org/ecma-262/6.0/>.		2015, <http://www.ecma-international.org/ecma-262/6.0/>.
	[FEATUREPOL]		[FEATUREPOL]
	Clelland, I., "Feature Policy", W3C Draft Community Group		Clelland, I., "Feature Policy", W3C Draft Community Group
	Report , 3 October 2019,		Report , 3 October 2019,
	<https://wicg.github.io/feature-policy/>.		<https://wicg.github.io/feature-policy/>.
	[HSTRUCT] Nottingham, M. and P-H. Kamp, "Structured Headers for		[HSTRUCT] Nottingham, M. and P-H. Kamp, "Structured Headers for
	HTTP", Internet-Draft, draft-ietf-httpbis-header-		HTTP", Work in Progress, Internet-Draft, draft-ietf-
	structure-13, August 2019,		httpbis-header-structure-14, October 2019,
	<https://tools.ietf.org/html/draft-ietf-httpbis-header-		<https://tools.ietf.org/html/draft-ietf-httpbis-header-
	structure-13>.		structure-14>.
	[ISO-8859-1]		[ISO-8859-1]
	International Organization for Standardization,		International Organization for Standardization,
	"Information technology -- 8-bit single-byte coded graphic		"Information technology -- 8-bit single-byte coded graphic
	character sets -- Part 1: Latin alphabet No. 1", ISO/		character sets -- Part 1: Latin alphabet No. 1", ISO/
	IEC 8859-1:1998, 1998.		IEC 8859-1:1998, 1998.
	[KEY] Fielding, R. and M. Nottingham, "The Key HTTP Response		[KEY] Fielding, R. and M. Nottingham, "The Key HTTP Response
	Header Field", Internet-Draft, draft-ietf-httpbis-key-01,		Header Field", Work in Progress, Internet-Draft, draft-
	March 2016,		ietf-httpbis-key-01, March 2016,
	<https://tools.ietf.org/html/draft-ietf-httpbis-key-01>.		<https://tools.ietf.org/html/draft-ietf-httpbis-key-01>.
	[REPORTING]		[REPORTING]
	Creager, D., Grigorik, I., Meyer, P., and M. West,		Creager, D., Grigorik, I., Meyer, P., and M. West,
	"Reporting API", W3C Working Draft WD-reporting-		"Reporting API", W3C Working Draft WD-reporting-
	1-20180925, 25 September 2018,		1-20180925, 25 September 2018,
	<https://www.w3.org/TR/2018/WD-reporting-1-20180925/>.		<https://www.w3.org/TR/2018/WD-reporting-1-20180925/>.
	Latest version available at https://www.w3.org/TR/		Latest version available at https://www.w3.org/TR/
	reporting-1/.		reporting-1/.
	skipping to change at page 9, line 34 ¶		skipping to change at page 9, line 47 ¶
	Transfer Protocol (HTTP/1.1): Authentication", RFC 7235,		Transfer Protocol (HTTP/1.1): Authentication", RFC 7235,
	DOI 10.17487/RFC7235, June 2014,		DOI 10.17487/RFC7235, June 2014,
	<https://www.rfc-editor.org/info/rfc7235>.		<https://www.rfc-editor.org/info/rfc7235>.
	[RFC8187] Reschke, J. F., "Indicating Character Encoding and		[RFC8187] Reschke, J. F., "Indicating Character Encoding and
	Language for HTTP Header Field Parameters", RFC 8187,		Language for HTTP Header Field Parameters", RFC 8187,
	DOI 10.17487/RFC8187, September 2017,		DOI 10.17487/RFC8187, September 2017,
	<https://www.rfc-editor.org/info/rfc8187>.		<https://www.rfc-editor.org/info/rfc8187>.
	[XMLHttpRequest]		[XMLHttpRequest]
	WhatWG, "XMLHttpRequest", October 2019,		WhatWG, "XMLHttpRequest", <https://xhr.spec.whatwg.org/>.
	<https://xhr.spec.whatwg.org/>.
	Appendix A. Examples		Appendix A. 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.
	A.1. Content-Length		A.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:
	Content-Length = 1*DIGIT		Content-Length = 1*DIGIT
	So the field value is similar to a JSON number ([RFC8259],		So the field value is similar to a JSON number ([RFC8259],
	Section 6).		Section 6).
	Content-Length is restricted to a single field instance, as it		Content-Length is restricted to a single field instance, as it
	doesn't use the list production (as per Section 3.2.2 of [RFC7230]).		doesn't use the list production (as per Section 3.2.2 of [RFC7230]).
	However, in practice multiple instances do occur, and the definition		However, in practice multiple instances do occur, and the definition
	of the header field does indeed discuss how to handle these cases.		of the header field does indeed discuss how to handle these cases.
	If Content-Length was defined using the JSON format discussed here,		If Content-Length was defined using the JSON format discussed here,
	the ABNF would be something like:		the ABNF would be something like:
	Content-Length = #number ; number: [RFC8259], Section 6		Content-Length = #number
			; number: [RFC8259], Section 6
	...and the prose definition would:		...and the prose definition would:
	* restrict all numbers to be non-negative integers without		* restrict all numbers to be non-negative integers without
	fractions, and		fractions, and
	* require that the array of values is of length 1 (but allow the		* require that the array of values is of length 1 (but allow the
	case where the array is longer, but all members represent the same		case where the array is longer, but all members represent the same
	value)		value)
	skipping to change at page 12, line 17 ¶		skipping to change at page 12, line 32 ¶
	{ "Newauth" : { "realm": "apps", "type" : 1,		{ "Newauth" : { "realm": "apps", "type" : 1,
	"title": "Login to \"apps\"" }},		"title": "Login to \"apps\"" }},
	{ "Basic" : { "realm": "simple"}}		{ "Basic" : { "realm": "simple"}}
	A.4. Accept-Encoding		A.4. Accept-Encoding
	The Accept-Encoding header field value is defined in Section 5.3.4 of		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		[RFC7231] as a list of codings, each of which allowing a weight
	parameter 'q':		parameter 'q':
	Accept-Encoding = #( codings [ weight ] ) codings = content-coding / "identity" / "*" weight = OWS ";" OWS "q=" qvalue qvalue = ( "0" [ "." 0*3DIGIT ] ) / ( "1" [ "." 0*3("0") ] )		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		An example for a complex header field value given in the definition
	of the header field is:		of the header field is:
	gzip;q=1.0, identity; q=0.5, *;q=0		gzip;q=1.0, identity; q=0.5, *;q=0
	Due to the defaulting rules for the quality value ([RFC7231],		Due to the defaulting rules for the quality value ([RFC7231],
	Section 5.3.1), this could also be written as:		Section 5.3.1), this could also be written as:
	gzip, identity; q=0.5, *; q=0		gzip, identity; q=0.5, *; q=0
	skipping to change at page 16, line 21 ¶		skipping to change at page 16, line 39 ¶
	Update notes about CLEARSITE and FEATUREPOL.		Update notes about CLEARSITE and FEATUREPOL.
	E.13. Since draft-reschke-http-jfv-09		E.13. Since draft-reschke-http-jfv-09
	Update HSTRUCT and FEATUREPOL references.		Update HSTRUCT and FEATUREPOL references.
	Update note about REPORTING.		Update note about REPORTING.
	Changed category to "informational".		Changed category to "informational".
			E.14. Since draft-reschke-http-jfv-10
			Update HSTRUCT reference.
	Acknowledgements		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. 21 change blocks.
	33 lines changed or deleted		49 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/