3. The Problem Details JSON Object #

The canonical model for problem details is a JSON object.

For example, an HTTP response carrying JSON problem details

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
"type": "https://example.com/probs/out-of-credit",
"title": "You do not have enough credit.",
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/msgs/abc",
"balance": 30, // extensions
"accounts": ["/account/12345",
                "/account/67890"] // extensions
}

The ability to convey problem-specific extensions allows more than one problem to be conveyed.

extensions 기능을 통해 둘 이상의 problem(정보)를 전달할 수 있다. (3.2 내용 참고)

For example,

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
"type": "https://example.net/validation-error",
"title": "Your request parameters didn't validate.",
"invalid-params": [ {	// extensions
						"name": "age",
						"reason": "must be a positive integer"
					},
					{
						"name": "color",
						"reason": "must be 'green', 'red' or 'blue'"}
					]
}

Note that this requires each of the subproblems to be similar enough to use the same HTTP status code. If they do not, the 207 (Multi-Status) [RFC4918] code could be used to encapsulate multiple status messages.

3.1 Members of a Problem Details Object #

A problem details object can have the following members

아래 항목 외에도 extensions(key-value 형태) 자유롭게 추가 가능해보인다.

항목	타입	설명
type	string	A URI reference that identified the problem type.
title	string	A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to accurrence of the problem, except for purposes of localization.
status	number	The HTTP status code generated by the origin server.
detail	string	A human-readable explanation specific to this occurrence of the problem.
instance	string	A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

Consumers SHOULD NOT automatically dereference the type URI.

type

It MUST use the “type” as the primiary identifier for the problem.

title

It is advisory and included only for users who are not aware of the semantics of the URI and do not have the ability to discover them (e.g., offline log analysis).

status The “status” member, if present, is only advisory.

It conveys the HTTP status code used for the convenience of the consumer.

Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly.

Consumers can use the status member to determine what the original status code used by the generator was, in cases where it has been changed (e.g., by an intermediary or cache), and when message bodies persist without HTTP information.

Generic HTTP software will still use the HTTP status code.

detail

The “detail” member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information.

Consumers SHOULD NOT parse the “detail” member for information.

Spring 6 의 ProblemDetail 클래스에서는 nullable/non-nullable 항목이 다음과 같다.

public class ProblemDetail {

	private static final URI BLANK_TYPE = URI.create("about:blank");


	private URI type = BLANK_TYPE;

	@Nullable
	private String title;

	private int status;

	@Nullable
	private String detail;

	@Nullable
	private URI instance;

	@Nullable
	private Map<String, Object> properties;

    ...

3.2 Extension Members #

Problem type definitions MAY extend the problem details object with additional members.

Clients consuming problem details MUST ignore any such extensions that they don’t recognize; this allows problem types to evolve and include additional information in the future.

Note that because extensions are effectively put into a namespace by the problem type, it is not possible to define new “standard” members without defining a new media type.