< draft-ietf-appsawg-http-problem-01.txt		draft-ietf-appsawg-http-problem-02.txt >
	Network Working Group M. Nottingham		Network Working Group M. Nottingham
	Internet-Draft Akamai		Internet-Draft Akamai
	Intended status: Standards Track E. Wilde		Intended status: Standards Track E. Wilde
	Expires: March 10, 2016 UC Berkeley		Expires: June 8, 2016 December 6, 2015
	September 7, 2015
	Problem Details for HTTP APIs		Problem Details for HTTP APIs
	draft-ietf-appsawg-http-problem-01		draft-ietf-appsawg-http-problem-02
	Abstract		Abstract
	This document defines a "problem detail" as a way to carry machine-		This document defines a "problem detail" as a way to carry machine-
	readable details of errors in a HTTP response, to avoid the need to		readable details of errors in a HTTP response, to avoid the need to
	invent new error response formats for HTTP APIs.		define new error response formats for HTTP APIs.
	Note to Readers		Note to Readers
	This draft should be discussed on the apps-discuss mailing list [1].		This draft should be discussed on the apps-discuss mailing list [1].
			This section is to be removed before publication.
			Note to RFC Editor
			Please replace all occurrences of "XXXX" with the final RFC number
			chosen for this draft.
			This section is to be removed before publication.
	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 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 March 10, 2016.		This Internet-Draft will expire on June 8, 2016.
	Copyright Notice		Copyright Notice
	Copyright (c) 2015 IETF Trust and the persons identified as the		Copyright (c) 2015 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
	carefully, as they describe your rights and restrictions with respect		carefully, as they describe your rights and restrictions with respect
	to this document. Code Components extracted from this document must		to this document. Code Components extracted from this document must
	include Simplified BSD License text as described in Section 4.e of		include Simplified BSD License text as described in Section 4.e of
	the Trust Legal Provisions and are provided without warranty as		the Trust Legal Provisions and are provided without warranty as
	described in the Simplified BSD License.		described in the Simplified BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 3		2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4		3. The Problem Details JSON Object . . . . . . . . . . . . . . . 4
	3.1. Problem Details Object Members . . . . . . . . . . . . . 5		3.1. Problem Details Object Members . . . . . . . . . . . . . 5
	3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 6		3.2. Extension Members . . . . . . . . . . . . . . . . . . . . 6
	4. Defining New Problem Types . . . . . . . . . . . . . . . . . 6		4. Defining New Problem Types . . . . . . . . . . . . . . . . . 6
	4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8		4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8
	4.2. Pre-Defined Problem Types . . . . . . . . . . . . . . . . 8		4.2. Pre-Defined Problem Types . . . . . . . . . . . . . . . . 8
	5. Security Considerations . . . . . . . . . . . . . . . . . . . 9		5. Security Considerations . . . . . . . . . . . . . . . . . . . 9
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
	7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10		7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11
	8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11		8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
	8.1. Normative References . . . . . . . . . . . . . . . . . . 11		8.1. Normative References . . . . . . . . . . . . . . . . . . 11
	8.2. Informative References . . . . . . . . . . . . . . . . . 11		8.2. Informative References . . . . . . . . . . . . . . . . . 12
	Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 12		Appendix A. HTTP Problems and XML . . . . . . . . . . . . . . . 13
	Appendix B. Using Problem Details with Other Formats . . . . . . 14		Appendix B. Using Problem Details with Other Formats . . . . . . 15
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
	1. Introduction		1. Introduction
	HTTP [RFC7230] status codes are sometimes not sufficient to convey		HTTP [RFC7230] status codes are sometimes not sufficient to convey
	enough information about an error to be helpful. While humans behind		enough information about an error to be helpful. While humans behind
	Web browsers can be informed about the nature of the problem with an		Web browsers can be informed about the nature of the problem with an
	HTML [W3C.REC-html401-19991224] response body, non-human consumers of		HTML [W3C.REC-html5-20141028] response body, non-human consumers of
	so-called "HTTP APIs" are usually not.		so-called "HTTP APIs" are usually not.
	This specification defines simple JSON [RFC7159] and XML		This specification defines simple JSON [RFC7159] and XML
	[W3C.REC-xml-20081126] document formats to suit this purpose. They		[W3C.REC-xml-20081126] document formats to suit this purpose. They
	are designed to be reused by HTTP APIs, which can identify distinct		are designed to be reused by HTTP APIs, which can identify distinct
	"problem types" specific to their needs.		"problem types" specific to their needs.
	Thus, API clients can be informed of both the high-level error class		Thus, API clients can be informed of both the high-level error class
	(using the status code) and the finer-grained details of the problem		(using the status code) and the finer-grained details of the problem
	(using one of these formats).		(using one of these formats).
	skipping to change at page 5, line 5 ¶		skipping to change at page 5, line 5 ¶
	Here, the out-of-credit problem (identified by its type URI)		Here, the out-of-credit problem (identified by its type URI)
	indicates the reason for the 403 in "title", gives a reference for		indicates the reason for the 403 in "title", gives a reference for
	the specific problem occurrence with "instance", gives occurrence-		the specific problem occurrence with "instance", gives occurrence-
	specific details in "detail", and adds two extensions; "balance"		specific details in "detail", and adds two extensions; "balance"
	conveys the account's balance, and "accounts" gives links where the		conveys the account's balance, and "accounts" gives links where the
	account can be topped up.		account can be topped up.
	The ability to convey problem-specific extensions allows more than		The ability to convey problem-specific extensions allows more than
	one problem to be conveyed. For example:		one problem to be conveyed. For example:
	HTTP/1.1 400 Bad Request		HTTP/1.1 400 Bad Request
	Content-Type: application/problem+json		Content-Type: application/problem+json
	Content-Language: en		Content-Language: en
	{		{
	"type": "https://example.net/validation-error",		"type": "https://example.net/validation-error",
	"title": "Your request parameters didn't validate.",		"title": "Your request parameters didn't validate.",
	"invalid-params": [ {		"invalid-params": [ {
	"name": "age",		"name": "age",
	"reason": "must be a positive integer"		"reason": "must be a positive integer"
	},		},
	{		{
	"name": "color",		"name": "color",
	"reason": "must be 'green', 'red' or 'blue'"}		"reason": "must be 'green', 'red' or 'blue'"}
	]		]
	}		}
	Note that this requires each of the sub-problems to be similar enough		Note that this requires each of the sub-problems to be similar enough
	to use the same HTTP status code. If they do not, the 207 (Multi-		to use the same HTTP status code. If they do not, the 207 (Multi-
	Status) [RFC4918] code could be used to encapsulate multiple status		Status) [RFC4918] code could be used to encapsulate multiple status
	messages.		messages.
	3.1. Problem Details Object Members		3.1. Problem Details Object Members
	A problem details object MAY have the following members:		A problem details object can have the following members:
	o "type" (string) - A URI reference [RFC3986] that identifies the		o "type" (string) - A URI reference [RFC3986] that identifies the
	problem type. When dereferenced, it is encouraged to provide		problem type. When dereferenced, it is encouraged to provide
	human-readable documentation for the problem type (e.g., using		human-readable documentation for the problem type (e.g., using
	HTML [W3C.REC-html401-19991224]). When this member is not		HTML [W3C.REC-html5-20141028]). When this member is not present,
	present, its value is assumed to be "about:blank".		its value is assumed to be "about:blank".
	o "title" (string) - A short, human-readable summary of the problem		o "title" (string) - A short, human-readable summary of the problem
	type. It SHOULD NOT change from occurrence to occurrence of the		type. It SHOULD NOT change from occurrence to occurrence of the
	problem, except for purposes of localisation.		problem, except for purposes of localisation (e.g., using
			proactive content negotiation; see [RFC7231], Section 3.4).
	o "status" (number) - The HTTP status code ([RFC7231], Section 6)		o "status" (number) - The HTTP status code ([RFC7231], Section 6)
	generated by the origin server for this occurrence of the problem.		generated by the origin server for this occurrence of the problem.
	o "detail" (string) - An human readable explanation specific to this		o "detail" (string) - An human readable explanation specific to this
	occurrence of the problem.		occurrence of the problem.
	o "instance" (string) - A URI reference that identifies the specific		o "instance" (string) - A URI reference that identifies the specific
	occurrence of the problem. It may or may not yield further		occurrence of the problem. It may or may not yield further
	information if dereferenced.		information if dereferenced.
	skipping to change at page 6, line 15 ¶		skipping to change at page 6, line 18 ¶
	the ability to discover them (e.g., offline log analysis). Consumers		the ability to discover them (e.g., offline log analysis). Consumers
	SHOULD NOT automatically dereference the type URI.		SHOULD NOT automatically dereference the type URI.
	The status member, if present, is only advisory; it conveys the HTTP		The status member, if present, is only advisory; it conveys the HTTP
	status code used for the convenience of the consumer. Generators		status code used for the convenience of the consumer. Generators
	MUST use the same status code in the actual HTTP response, to assure		MUST use the same status code in the actual HTTP response, to assure
	that generic HTTP software that does not understand this format still		that generic HTTP software that does not understand this format still
	behaves correctly. See Section 5 for further caveats regarding its		behaves correctly. See Section 5 for further caveats regarding its
	use.		use.
	The detail member, if present, SHOULD focus on helping the client		The detail member, if present, ought to focus on helping the client
	correct the problem, rather than giving debugging information.		correct the problem, rather than giving debugging information.
	Consumers SHOULD NOT parse the detail member for information;		Consumers SHOULD NOT parse the detail member for information;
	extensions are more suitable and less error-prone ways to obtain such		extensions are more suitable and less error-prone ways to obtain such
	information.		information.
	Note that both "type" and "instance" accept relative URIs; this means		Note that both "type" and "instance" accept relative URIs; this means
	that they must be resolved relative to the document's base URI, as		that they must be resolved relative to the document's base URI, as
	per {{RFC3986}}, Section 5.		per [RFC3986], Section 5.
	3.2. Extension Members		3.2. Extension Members
	Problem type definitions MAY extend the problem details object with		Problem type definitions MAY extend the problem details object with
	additional members.		additional members.
	For example, our "out of credit" problem above defines two such		For example, our "out of credit" problem above defines two such
	extensions, "balance" and "accounts" to convey additional, problem-		extensions, "balance" and "accounts" to convey additional, problem-
	specific information.		specific information.
	skipping to change at page 7, line 18 ¶		skipping to change at page 7, line 21 ¶
	consider the Security Considerations (Section 5); in particular the		consider the Security Considerations (Section 5); in particular the
	risk of exposing attack vectors by exposing implementation internals		risk of exposing attack vectors by exposing implementation internals
	through error messages.		through error messages.
	Likewise, truly generic problems - i.e., conditions that could		Likewise, truly generic problems - i.e., conditions that could
	potentially apply to any resource on the Web - are usually better		potentially apply to any resource on the Web - are usually better
	expressed as plain status codes. For example, a "write access		expressed as plain status codes. For example, a "write access
	disallowed" problem is probably unnecessary, since a 403 Forbidden		disallowed" problem is probably unnecessary, since a 403 Forbidden
	status code in response to a PUT request is self-explanatory.		status code in response to a PUT request is self-explanatory.
	Finally, an application may have a more appropriate way to carry an		Finally, an application might have a more appropriate way to carry an
	error in a format that it already defines. Problem details are		error in a format that it already defines. Problem details are
	intended to avoid the necessity of establishing new "fault" or		intended to avoid the necessity of establishing new "fault" or
	"error" document formats, not to replace existing domain-specific		"error" document formats, not to replace existing domain-specific
	formats.		formats.
	That said, it is possible to add support for problem details to		That said, it is possible to add support for problem details to
	existing HTTP APIs using HTTP content negotiation (e.g., using the		existing HTTP APIs using HTTP content negotiation (e.g., using the
	Accept request header to indicate a preference for this format).		Accept request header to indicate a preference for this format; see
			[RFC7231], Section 5.3.2).
	New problem type definitions MUST document:		New problem type definitions MUST document:
	1. A type URI (typically, with the "http" scheme),		1. A type URI (typically, with the "http" scheme),
	2. A title that appropriately describes it (think short), and		2. A title that appropriately describes it (think short), and
	3. The HTTP status code for it to be used with.		3. The HTTP status code for it to be used with.
	Problem types MAY specify the use of the Retry-After response header		Problem type definitions MAY specify the use of the Retry-After
	in appropriate circumstances.		response header ([RFC7231], Section 7.1.3) in appropriate
			circumstances.
	A problem's type URI SHOULD resolve to HTML		A problem's type URI SHOULD resolve to HTML [W3C.REC-html5-20141028]
	[W3C.REC-html401-19991224] documentation that explains how to resolve		documentation that explains how to resolve the problem.
	the problem.
	A problem type definition MAY specify additional members on the		A problem type definition MAY specify additional members on the
	Problem Details object. For example, an extension might use typed		Problem Details object. For example, an extension might use typed
	links [RFC5988] to another resource that can be used by machines to		links [RFC5988] to another resource that can be used by machines to
	resolve the problem.		resolve the problem.
	If such additional members are defined, their names SHOULD start with		If such additional members are defined, their names SHOULD start with
	a letter (ALPHA, as per [RFC5234]) and SHOULD consist of characters		a letter (ALPHA, as per [RFC5234], Appendix B.1) and SHOULD consist
	from ALPHA, DIGIT, and "_" (so that it can be serialized in formats		of characters from ALPHA, DIGIT (Ibid.), and "_" (so that it can be
	other than JSON), and SHOULD be three characters or longer.		serialized in formats other than JSON), and SHOULD be three
			characters or longer.
	4.1. Example		4.1. Example
	For example, if you are publishing an HTTP API to your online		For example, if you are publishing an HTTP API to your online
	shopping cart, you might need to indicate that the user is out of		shopping cart, you might need to indicate that the user is out of
	credit (our example from above), and therefore cannot make the		credit (our example from above), and therefore cannot make the
	purchase.		purchase.
	If you already have an application-specific format that can		If you already have an application-specific format that can
	accommodate this information, it's probably best to do that.		accommodate this information, it's probably best to do that.
	skipping to change at page 10, line 5 ¶		skipping to change at page 9, line 37 ¶
	modified the HTTP status code in transit. As such, those defining		modified the HTTP status code in transit. As such, those defining
	problem types as well as generators and consumers of problems need to		problem types as well as generators and consumers of problems need to
	be aware that generic software (such as proxies, load balancers,		be aware that generic software (such as proxies, load balancers,
	firewalls, virus scanners) are unlikely to know of or respect the		firewalls, virus scanners) are unlikely to know of or respect the
	status code conveyed in this member.		status code conveyed in this member.
	6. IANA Considerations		6. IANA Considerations
	This specification defines two new Internet media types [RFC6838]:		This specification defines two new Internet media types [RFC6838]:
	Type name: application		Type name: application
	Subtype name: problem+json
	Required parameters: None
	Optional parameters: None; unrecognised parameters
	should be ignored
	Encoding considerations: Same as [RFC7159]
	Security considerations: see [this document]
	Interoperability considerations: None.
	Published specification: [this document]
	Applications that use this media type: HTTP
	Additional information:
	Magic number(s): n/a
	File extension(s): n/a
	Macintosh file type code(s): n/a
	Person & email address to contact for further information:
	Mark Nottingham <mnot@mnot.net>
	Intended usage: COMMON
	Restrictions on usage: None.
	Author: Mark Nottingham <mnot@mnot.net>
	Change controller: IESG
	Type name: application		Subtype name: problem+json
	Subtype name: problem+xml
	Required parameters: None		Required parameters: None
	Optional parameters: None; unrecognized parameters
	should be ignored		Optional parameters: None; unrecognised parameters should be ignored
	Encoding considerations: Same as [RFC7303]
	Security considerations: see [this document]		Encoding considerations: Same as [RFC7159]
	Interoperability considerations: None.
	Published specification: [this document]		Security considerations: see Section 5 of this document
	Applications that use this media type: HTTP
	Additional information:		Interoperability considerations: None
	Magic number(s): n/a
	File extension(s): n/a		Published specification: [this document]
	Macintosh file type code(s): n/a		Applications that use this media type: HTTP
	Person & email address to contact for further information:
	Mark Nottingham <mnot@mnot.net>		Fragment identifier considerations: Same as for application/json
	Intended usage: COMMON		([RFC7159])
	Restrictions on usage: None.
	Author: Mark Nottingham <mnot@mnot.net>		Additional information:
	Change controller: IESG
			Deprecated alias names for this type: n/a
			Magic number(s): n/a
			File extension(s): n/a
			Macintosh file type code(s): n/a
			Person and email address to contact for further information: Mark No
			ttingham <mnot@mnot.net>
			Intended usage: COMMON
			Restrictions on usage: None.
			Author: Mark Nottingham <mnot@mnot.net>
			Change controller: IESG
			Type name: application
			Subtype name: problem+xml
			Required parameters: None
			Optional parameters: None; unrecognised parameters should be ignored
			Encoding considerations: Same as [RFC7303]
			Security considerations: see Section 5 of this document
			Interoperability considerations: None
			Published specification: [this document]
			Applications that use this media type: HTTP
			Fragment identifier considerations: Same as for application/xml (as
			specified by Section 5 of [RFC7303])
			Additional information:
			Deprecated alias names for this type: n/a
			Magic number(s): n/a
			File extension(s): n/a
			Macintosh file type code(s): n/a
			Person and email address to contact for further information: Mark No
			ttingham <mnot@mnot.net>
			Intended usage: COMMON
			Restrictions on usage: None.
			Author: Mark Nottingham <mnot@mnot.net>
			Change controller: IESG
	7. Acknowledgements		7. Acknowledgements
	The authors would like to thank Jan Algermissen, Mike Amundsen, Subbu		The authors would like to thank Jan Algermissen, Mike Amundsen, Subbu
	Allamaraju, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall,		Allamaraju, Roy Fielding, Eran Hammer, Sam Johnston, Mike McCall,
	Julian Reschke, and James Snell for review of this specification.		Julian Reschke, and James Snell for review of this specification.
	8. References		8. References
	8.1. Normative References		8.1. Normative References
	skipping to change at page 11, line 38 ¶		skipping to change at page 12, line 15 ¶
	[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer		[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
	Protocol (HTTP/1.1): Message Syntax and Routing", RFC		Protocol (HTTP/1.1): Message Syntax and Routing", RFC
	7230, DOI 10.17487/RFC7230, June 2014,		7230, DOI 10.17487/RFC7230, June 2014,
	<http://www.rfc-editor.org/info/rfc7230>.		<http://www.rfc-editor.org/info/rfc7230>.
	[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer		[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
	Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI		Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI
	10.17487/RFC7231, June 2014,		10.17487/RFC7231, June 2014,
	<http://www.rfc-editor.org/info/rfc7231>.		<http://www.rfc-editor.org/info/rfc7231>.
			[W3C.REC-xml-20081126]
			Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
			F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth
			Edition)", World Wide Web Consortium Recommendation REC-
			xml-20081126, November 2008,
			<http://www.w3.org/TR/2008/REC-xml-20081126>.
	8.2. Informative References		8.2. Informative References
	[ISO-19757-2]		[ISO-19757-2]
	International Organization for Standardization,		International Organization for Standardization,
	"Information Technology --- Document Schema Definition		"Information Technology --- Document Schema Definition
	Languages (DSDL) --- Part 2: Grammar-based Validation ---		Languages (DSDL) --- Part 2: Grammar-based Validation ---
	RELAX NG", ISO/IEC 19757-2, 2003.		RELAX NG", ISO/IEC 19757-2, 2003.
	[RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed		[RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed
	Authoring and Versioning (WebDAV)", RFC 4918, DOI		Authoring and Versioning (WebDAV)", RFC 4918, DOI
	skipping to change at page 12, line 22 ¶		skipping to change at page 13, line 5 ¶
	[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type		[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
	Specifications and Registration Procedures", BCP 13, RFC		Specifications and Registration Procedures", BCP 13, RFC
	6838, DOI 10.17487/RFC6838, January 2013,		6838, DOI 10.17487/RFC6838, January 2013,
	<http://www.rfc-editor.org/info/rfc6838>.		<http://www.rfc-editor.org/info/rfc6838>.
	[RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303,		[RFC7303] Thompson, H. and C. Lilley, "XML Media Types", RFC 7303,
	DOI 10.17487/RFC7303, July 2014,		DOI 10.17487/RFC7303, July 2014,
	<http://www.rfc-editor.org/info/rfc7303>.		<http://www.rfc-editor.org/info/rfc7303>.
	[W3C.REC-html401-19991224]		[W3C.REC-html5-20141028]
	Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01		Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
	Specification", World Wide Web Consortium Recommendation		Navara, E., O&#039;Connor, E., and S. Pfeiffer, "HTML5",
	REC-html401-19991224, December 1999,		World Wide Web Consortium Recommendation REC-
	<http://www.w3.org/TR/1999/REC-html401-19991224>.		html5-20141028, October 2014,
			<http://www.w3.org/TR/2014/REC-html5-20141028>.
	[W3C.REC-rdfa-core-20120607]		[W3C.REC-rdfa-core-20130822]
	Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa		Adida, B., Birbeck, M., McCarron, S., and I. Herman, "RDFa
	Core 1.1", World Wide Web Consortium Recommendation REC-		Core 1.1 - Second Edition", World Wide Web Consortium
	rdfa-core-20120607, June 2012,		Recommendation REC-rdfa-core-20130822, August 2013,
	<http://www.w3.org/TR/2012/REC-rdfa-core-20120607>.		<http://www.w3.org/TR/2013/REC-rdfa-core-20130822>.
	[W3C.REC-xml-20081126]		[W3C.REC-xml-stylesheet-20101028]
	Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and		Clark, J., Pieters, S., and H. Thompson, "Associating
	F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth		Style Sheets with XML documents 1.0 (Second Edition)",
	Edition)", World Wide Web Consortium Recommendation REC-		World Wide Web Consortium Recommendation REC-xml-
	xml-20081126, November 2008,		stylesheet-20101028, October 2010,
	<http://www.w3.org/TR/2008/REC-xml-20081126>.		<http://www.w3.org/TR/2010/REC-xml-stylesheet-20101028>.
	Appendix A. HTTP Problems and XML		Appendix A. HTTP Problems and XML
	Some HTTP-based APIs use XML [W3C.REC-xml-20081126] as their primary		Some HTTP-based APIs use XML [W3C.REC-xml-20081126] as their primary
	format convention. Such APIs MAY express problem details using the		format convention. Such APIs can express problem details using the
	format defined in this appendix.		format defined in this appendix.
	The OPTIONAL RELAX NG schema [ISO-19757-2] for the XML format is:		The RELAX NG schema [ISO-19757-2] for the XML format is as follows.
			Keep in mind that this schema is only meant as documentation, and not
			as a normative schema that captures all constraints of the XML
			format. Also, it would be possible to use other XML schema languages
			to define a similar set of constraints (depending on the features of
			the chosen schema language).
	default namespace ns = "urn:ietf:rfc:XXXX"		default namespace ns = "urn:ietf:rfc:XXXX"
	start = problem		start = problem
	problem =		problem =
	element problem {		element problem {
	( element type { xsd:anyURI }?		( element type { xsd:anyURI }?
	& element title { xsd:string }?		& element title { xsd:string }?
	& element detail { xsd:string }?		& element detail { xsd:string }?
	skipping to change at page 13, line 25 ¶		skipping to change at page 14, line 25 ¶
	& element instance { xsd:anyURI }? ),		& element instance { xsd:anyURI }? ),
	anyNsElement		anyNsElement
	}		}
	anyNsElement =		anyNsElement =
	( element ns:* { anyNsElement | text }		( element ns:* { anyNsElement | text }
	| attribute * { text })*		| attribute * { text })*
	The media type for this format is "application/problem+xml".		The media type for this format is "application/problem+xml".
	Extension arrays and objects can be serialized into the XML format by		Extension arrays and objects are serialized into the XML format by
	considering an element containing a child or children to represent an		considering an element containing a child or children to represent an
	object, except for elements that contain only child element(s) named		object, except for elements that contain only child element(s) named
	'i', which are considered arrays. For example, an alternate version		'i', which are considered arrays. For example, the XML version of
	of the example above would appear in XML as:		the example above appears in XML as follows:
	HTTP/1.1 403 Forbidden		HTTP/1.1 403 Forbidden
	Content-Type: application/problem+xml		Content-Type: application/problem+xml
	Content-Language: en		Content-Language: en
	<?xml version="1.0" encoding="UTF-8"?>		<?xml version="1.0" encoding="UTF-8"?>
	<problem xmlns="urn:ietf:rfc:XXXX">		<problem xmlns="urn:ietf:rfc:XXXX">
	<type>https://example.com/probs/out-of-credit</type>		<type>https://example.com/probs/out-of-credit</type>
	<title>You do not have enough credit.</title>		<title>You do not have enough credit.</title>
	<detail>Your current balance is 30, but that costs 50.</detail>		<detail>Your current balance is 30, but that costs 50.</detail>
	<instance>		<instance>https://example.net/account/12345/msgs/abc</instance>
	https://example.net/account/12345/msgs/abc
	</instance>
	<balance>30</balance>		<balance>30</balance>
	<accounts>		<accounts>
	<i>https://example.net/account/12345</i>		<i>https://example.net/account/12345</i>
	<i>https://example.net/account/67890</i>		<i>https://example.net/account/67890</i>
	</accounts>		</accounts>
	</problem>		</problem>
	Note that this format uses an XML Namespace. This is primarily to		Note that this format uses an XML Namespace. This is primarily to
	allow embedding it into other XML-based formats; it does not imply		allow embedding it into other XML-based formats; it does not imply
	that it can or should be extended with elements or attributes in		that it can or should be extended with elements or attributes in
	other namespaces. The RELAX NG schema explicitly only allows		other namespaces. The RELAX NG schema explicitly only allows
	elements from the one namespace used in the XML format. Any		elements from the one namespace used in the XML format. Any
	extension arrays and objects MUST be serialized into XML markup using		extension arrays and objects MUST be serialized into XML markup using
	only that namespace.		only that namespace.
			When using the XML format, it is possible to embed an XML Processing
			Instruction in the XML that instructs clients to transform the XML,
			using the referenced XSLT code [W3C.REC-xml-stylesheet-20101028]. If
			this code is transforming the XML into (X)HTML, then it is possible
			to serve the XML format, and yet have clients capable of performing
			the transformation display human-friendly (X)HTML that is rendered
			and displayed at the client. Note that when using this method, it is
			advisable to use XSLT 1.0, in order to maximize the number of clients
			capable of executing the XSLT code.
	Appendix B. Using Problem Details with Other Formats		Appendix B. Using Problem Details with Other Formats
	In some situations, it can be advantageous to embed Problem Details		In some situations, it can be advantageous to embed Problem Details
	in formats other than those described here. For example, an API that		in formats other than those described here. For example, an API that
	uses HTML [W3C.REC-html401-19991224] might want to also use HTML for		uses HTML [W3C.REC-html5-20141028] might want to also use HTML for
	expressing its problem details.		expressing its problem details.
	Problem details can be embedded in other formats by either		Problem details can be embedded in other formats by either
	encapsulating one of the existing serializations (JSON or XML) into		encapsulating one of the existing serializations (JSON or XML) into
	that format, or by translating the model of a Problem Detail (as		that format, or by translating the model of a Problem Detail (as
	specified in Section 3) into the format's conventions.		specified in Section 3) into the format's conventions.
	For example, in HTML, a problem could be embedded by encapsulating		For example, in HTML, a problem could be embedded by encapsulating
	JSON in a script tag:		JSON in a script tag:
	skipping to change at page 14, line 35 ¶		skipping to change at page 15, line 43 ¶
	{		{
	"type": "https://example.com/probs/out-of-credit",		"type": "https://example.com/probs/out-of-credit",
	"title": "You do not have enough credit.",		"title": "You do not have enough credit.",
	"detail": "Your current balance is 30, but that costs 50.",		"detail": "Your current balance is 30, but that costs 50.",
	"instance": "/account/12345/msgs/abc",		"instance": "/account/12345/msgs/abc",
	"balance": 30,		"balance": 30,
	"accounts": ["/account/12345",		"accounts": ["/account/12345",
	"/account/67890"]		"/account/67890"]
	}		}
	</script>		</script>
	}
	or by inventing a mapping into RDFa [W3C.REC-rdfa-core-20120607].		or by inventing a mapping into RDFa [W3C.REC-rdfa-core-20130822].
	This specification does not make specific recommendations regarding		This specification does not make specific recommendations regarding
	embedding Problem Details in other formats; the appropriate way to		embedding Problem Details in other formats; the appropriate way to
	embed them depends both upon the format in use and application of		embed them depends both upon the format in use and application of
	that format.		that format.
	Authors' Addresses		Authors' Addresses
	Mark Nottingham		Mark Nottingham
	Akamai		Akamai
	skipping to change at page 15, line 4 ¶		skipping to change at page 16, line 12 ¶
	embed them depends both upon the format in use and application of		embed them depends both upon the format in use and application of
	that format.		that format.
	Authors' Addresses		Authors' Addresses
	Mark Nottingham		Mark Nottingham
	Akamai		Akamai
	Email: mnot@mnot.net		Email: mnot@mnot.net
	URI: http://www.mnot.net/		URI: http://www.mnot.net/
	Erik Wilde		Erik Wilde
	UC Berkeley
	Email: dret@berkeley.edu		Email: erik.wilde@dret.net
	URI: http://dret.net/netdret/		URI: http://dret.net/netdret/
End of changes. 40 change blocks.
	111 lines changed or deleted		183 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/