メインコンテンツまでスキップ

3. The Problem Details JSON Object (問題詳細JSONオブジェクト)

問題詳細の正規モデルは JSON [RFC7159] オブジェクトです。

JSON ドキュメントとしてシリアル化される場合、その形式は application/problem+json メディアタイプで識別されます。

例えば、JSON 問題詳細を含む HTTP レスポンス:

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,
 "accounts": ["/account/12345",
              "/account/67890"]
}

ここで、クレジット不足問題(その type URI で識別される)は title で 403 の理由を示し、instance で特定の問題発生への参照を提供し、detail で発生固有の詳細を示し、2 つの拡張を追加します。balance はアカウントの残高を伝え、accounts はアカウントをチャージできるリンクを提供します。

問題固有の拡張を伝達する能力により、複数の問題を伝達できます。例えば:

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": [ {
                      "name": "age",
                      "reason": "must be a positive integer"
                    },
                    {
                      "name": "color",
                      "reason": "must be 'green', 'red' or 'blue'"}
                  ]
}

これは、各サブ問題が同じ HTTP ステータスコードを使用するのに十分類似している必要があることに注意してください。そうでない場合、207 (Multi-Status) [RFC4918] コードを使用して複数のステータスメッセージをカプセル化できます。

3.1. 問題詳細オブジェクトのメンバー (Members of a Problem Details Object)​

問題詳細オブジェクトは以下のメンバーを持つことができます:

  • type (文字列) - 問題タイプを識別する URI 参照 [RFC3986]。本仕様は、逆参照されたとき、問題タイプの人間可読なドキュメント(例えば、HTML [W3C.REC-html5-20141028] を使用)を提供することを推奨します (encourages)。このメンバーが存在しない場合、その値は about:blank であると仮定されます。

  • title (文字列) - 問題タイプの短い人間可読な要約。ローカライゼーション目的(例えば、プロアクティブコンテンツネゴシエーションを使用、[RFC7231], Section 3.4 参照)を除き、問題の発生間で変更すべきでない (SHOULD NOT)。

  • status (数値) - この問題の発生に対してオリジンサーバーが生成した HTTP ステータスコード([RFC7231], Section 6)。

  • detail (文字列) - この問題の発生に固有の人間可読な説明。

  • instance (文字列) - 問題の特定の発生を識別する URI 参照。逆参照された場合、さらなる情報をもたらすかもしれないしもたらさないかもしれません。

利用者は問題タイプの主要な識別子として type 文字列を使用しなければなりません (MUST)。title 文字列は助言的であり、URI のセマンティクスを知らず、それらを発見する能力を持たないユーザー(例えば、オフラインログ分析)のためにのみ含まれます。利用者は type URI を自動的に逆参照すべきでない (SHOULD NOT)。

status メンバーは、存在する場合、助言的なものに過ぎません。これは利用者の便宜のために使用された HTTP ステータスコードを伝達します。生成器は実際の HTTP レスポンスで同じステータスコードを使用しなければならず (MUST)、この形式を理解しない汎用 HTTP ソフトウェアが依然として正しく動作することを保証します。その使用に関するさらなる注意事項については、セクション 5 を参照してください。

利用者は status メンバーを使用して、生成器が使用した元のステータスコードが何であったかを判断できます。これは、それが変更された場合(例えば、中間装置またはキャッシュによって)、およびメッセージボディが HTTP 情報なしで永続化される場合です。汎用 HTTP ソフトウェアは依然として HTTP ステータスコードを使用します。

detail メンバーは、存在する場合、デバッグ情報を提供するのではなく、クライアントが問題を修正するのを支援することに焦点を当てるべきです。

利用者は情報を得るために detail メンバーを解析すべきでない (SHOULD NOT)。拡張は、そのような情報を取得するためのより適切でエラーが起こりにくい方法です。

type と instance の両方が相対 URI を受け入れることに注意してください。これは、[RFC3986], Section 5 に従って、それらがドキュメントのベース URI に対して解決されなければならないことを意味します。

3.2. 拡張メンバー (Extension Members)​

問題タイプ定義は追加のメンバーで問題詳細オブジェクトを拡張してもよい (MAY)。

例えば、上記の「クレジット不足」問題は 2 つのそのような拡張 -- balance と accounts を定義して、追加の問題固有の情報を伝達します。

問題詳細を消費するクライアントは、認識しないそのような拡張を無視しなければなりません (MUST)。これにより、問題タイプが進化し、将来追加情報を含めることができます。

拡張は問題タイプによって事実上名前空間に配置されるため、新しいメディアタイプを定義せずに新しい「標準」メンバーを定義することは不可能であることに注意してください。

に最終更新