このメモの位置付け

これはインターネット標準化過程の文書です。¶

この文書は、インターネット技術タスクフォース （IETF）の成果物です。これはIETFコミュニティの合意を表します。これは 公開レビューを受けており、Internet Engineering Steering Group （IESG）によって公開が承認されています。インターネット標準に関する さらなる情報は、RFC 7841のセクション2で入手できます。¶

この文書の現在の状態、正誤表、および この文書に関するフィードバックの提供方法についての情報は、 https://www.rfc-editor.org/info/rfc9457で入手できます。¶

Copyright Notice

Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

目次

1. はじめに

HTTPステータスコード（[HTTP]のセクション15）は、 エラーについて有用であるのに十分な情報を常に伝達できるとは限りません。Webブラウザーを使用する人間は、多くの場合、 HTML [HTML5] レスポンス内容を理解できますが、 HTTP APIの非人間の利用者がそうするのは困難です。¶

その欠点に対処するために、この仕様は、遭遇した問題の詳細――「問題詳細」――を記述するための 単純なJSON [JSON] および XML [XML] 文書形式を定義します。¶

たとえば、クライアントのアカウントに十分なクレジットがないことを示すレスポンスを考えます。 APIの設計者は、汎用HTTPソフトウェア（クライアントライブラリ、キャッシュ、プロキシなど）にレスポンスの一般的な意味を通知するために、 403 Forbiddenステータスコードを使用することを決定するかもしれません。 API固有の問題詳細（サーバーがリクエストを拒否した理由や該当するアカウント残高など）は、 クライアントがそれらに適切に対処できるように（たとえば、アカウントへの追加クレジットの移転をトリガーするなど）、 レスポンス内容で伝達できます。¶

この仕様は、特定の「問題型」（例:「クレジット不足」）を URI [URI]で識別します。HTTP APIは、 自身に固有の問題を識別するために自身の管理下にあるURIを使用できます。または、相互運用性を促進し、 共通の意味を活用するために既存のものを再利用できます（セクション4.2を参照）。¶

問題詳細には、問題の特定の発生を識別するURIなど、他の情報を含めることができます （実質的に「先週の木曜日にJoeに十分なクレジットがなかった時」という概念に識別子を与えるものです）。これはサポートや フォレンジックの目的に役立つことがあります。¶

問題詳細のデータモデルはJSON [JSON]オブジェクトです。JSON文書としてシリアライズされる場合、 これは"application/problem+json"メディア型を使用します。付録Bは、 "application/problem+xml"メディア型を使用する同等のXML形式を定義します。¶

問題詳細がHTTPレスポンスで伝達される場合、その内容はプロアクティブネゴシエーションを使用して ネゴシエートできます。[HTTP]のセクション12.1を参照してください。特に、 人間可読な文字列（titleやdescription内のものなど）で使用される言語は、 Accept-Languageリクエストヘッダーフィールド（[HTTP]のセクション12.5.4）を使用して ネゴシエートできますが、そのネゴシエーションによっても、優先されないデフォルト表現が返されることがあります。¶

問題詳細は任意のHTTPステータスコードで使用できますが、4xxおよび5xxレスポンスの意味に最も自然に適合します。 問題詳細は、HTTPで問題の詳細を伝達する唯一の方法では（当然ながら）ないことに注意してください。 たとえば、レスポンスが依然としてリソースの表現である場合、そのアプリケーションの形式で関連する詳細を記述することが しばしば望ましいです。同様に、定義済みのHTTPステータスコードは、追加の詳細を伝達する必要なしに多くの状況をカバーします。¶

この仕様の目的は、共通のエラー形式を必要とするアプリケーションのためにそれを定義し、 アプリケーションが独自のものを定義する必要がないようにすること、またはさらに悪いことに、 既存のHTTPステータスコードの意味を再定義しようと誘惑されないようにすることです。アプリケーションがエラーを伝達するためにこれを使用しないことを選択した場合でも、 その設計を検討することは、既存形式でエラーを伝達するときに直面する設計上の判断を導くのに役立ちます。¶

[RFC7807]からの変更点の一覧については、 付録Dを参照してください。¶

2. 要件言語

この文書におけるキーワード「MUST」、「MUST NOT」、 「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、 「RECOMMENDED」、「NOT RECOMMENDED」、 「MAY」、および「OPTIONAL」は、 ここに示すようにすべて大文字で現れる場合に限り、 BCP 14 [RFC2119] [RFC8174]で説明されているように解釈されます。¶

3. 問題詳細JSONオブジェクト

問題詳細の正規モデルはJSON [JSON]オブジェクトです。JSON文書でシリアライズされる場合、 その形式は"application/problem+json"メディア型で識別されます。¶

例:¶

POST /purchase HTTP/1.1
Host: store.example.com
Content-Type: application/json
Accept: application/json, application/problem+json

{
  "item": 123456,
  "quantity": 2
}

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によって識別される）クレジット不足の問題が、 "title"で403の理由を示し、"instance"で特定の問題発生を識別し、 "detail"で発生固有の詳細を与え、さらに2つの拡張を追加しています。"balance"はアカウントの残高を伝達し、 "accounts"はアカウントにチャージできるリンクを一覧表示します。¶

それを受け入れるように設計されている場合、問題固有の拡張は同じ問題型の複数のインスタンスを伝達できます。 例:¶

POST /details HTTP/1.1
Host: account.example.com
Accept: application/json

{
  "age": 42.3,
  "profile": {
    "color": "yellow"
  }
}

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: en

{
 "type": "https://example.net/validation-error",
 "title": "Your request is not valid.",
 "errors": [
             {
               "detail": "must be a positive integer",
               "pointer": "#/age"
             },
             {
               "detail": "must be 'green', 'red' or 'blue'",
               "pointer": "#/profile/color"
             }
          ]
}

ここでの架空の問題型は"errors"拡張を定義します。これは各検証エラーの詳細を記述する配列です。 各メンバーは、問題を記述する"detail"と、JSON Pointer [JSON-POINTER]を使用してリクエスト内容内の問題の位置を示す "pointer"を含むオブジェクトです。¶

APIが同じ型を共有しない複数の問題に遭遇した場合、最も関連性が高い、または緊急度の高い問題を レスポンスで表現することがRECOMMENDEDです。複数の異なる型を伝達する汎用的な「バッチ」問題型を作成することは可能ですが、 それらはHTTPの意味にうまく対応しません。¶

また、クライアントがAcceptでそれを列挙していなかったにもかかわらず、APIが "application/problem+json"型で応答していることにも注意してください。これはHTTPで許可されています （[HTTP]のセクション12.5.1を参照）。¶

tag:example@example.org,2021-09-17:OutOfLuck

4. 新しい問題型の定義

HTTP APIがエラー状態を示すレスポンスを定義する必要がある場合、新しい問題型を定義することが 適切であるかもしれません。¶

そうする前に、それらが何に適しており、何を他の仕組みに任せる方がよいかを理解することが重要です。¶

問題詳細は基盤実装のためのデバッグツールではありません。むしろ、HTTPインターフェイス自体について より詳しい詳細を公開する方法です。新しい問題型の設計者は、 セキュリティ上の考慮事項 （セクション5）、 特に、エラーメッセージを通じて実装内部を公開することで攻撃ベクトルを露出するリスクを慎重に考慮する必要があります。¶

同様に、真に汎用的な問題――すなわち、Web上の任意のリソースに適用されうる条件――は、 通常、単純なステータスコードとして表現する方がよいです。たとえば、PUTリクエストに対する403 Forbiddenステータスコードは 自明であるため、「書き込みアクセスが許可されていない」問題はおそらく不要です。¶

最後に、アプリケーションには、すでに定義している形式でエラーを伝達する、より適切な方法があるかもしれません。 問題詳細は、新しい「fault」または「error」文書形式を確立する必要性を避けることを意図しており、 既存のドメイン固有形式を置き換えることを意図していません。¶

とはいえ、HTTPコンテンツネゴシエーションを使用して既存のHTTP APIに問題詳細のサポートを追加することは可能です （たとえば、この形式への優先を示すためにAcceptリクエストヘッダーを使用するなど。 [HTTP]のセクション 12.5.1を参照）。¶

新しい問題型定義は、次を文書化MUSTします。¶

1. type URI（通常は"http"または"https"スキームを持つ）¶
2. それを適切に説明するtitle（短く考えること）¶
3. それとともに使用されるHTTPステータスコード¶

問題型定義は、適切な状況でRetry-Afterレスポンスヘッダー （[HTTP]のセクション 10.2.3）の使用を指定MAYできます。¶

問題型URIは、問題を解決する方法を説明するHTML [HTML5]文書に解決 SHOULDします。¶

問題型定義は、問題詳細オブジェクト上の追加メンバーを指定 MAYできます。 たとえば、拡張は、機械が問題を解決するために使用できる別のリソースへの型付きリンク [WEB-LINKING]を使用するかもしれません。¶

そのような追加メンバーが定義される場合、その名前は文字（ALPHA、[ABNF]の付録 B.1に従う）で始まる SHOULDであり、ALPHA、DIGIT （[ABNF]の付録 B.1）および"_"の文字で構成される SHOULDであり（JSON以外の形式でもシリアライズできるようにするため）、 3文字以上であるSHOULDです。¶

5. セキュリティ上の考慮事項

新しい問題型を定義する際、含められる情報は慎重に検証されなければなりません。 同様に、実際に問題を生成する際には――どのようにシリアライズされるかにかかわらず――与えられる詳細も精査されなければなりません。¶

リスクには、システム、システムへのアクセス、またはシステムのユーザーのプライバシーを侵害するために悪用されうる情報の漏えいが含まれます。¶

発生情報へのリンクを提供する生成者は、スタックダンプのような実装詳細をHTTPインターフェイスを通じて利用可能にしないことが推奨されます。 これはサーバー実装、そのデータなどの機微な詳細を露出する可能性があるためです。¶

"status"メンバーはHTTPステータスコード自体で利用可能な情報を重複させ、 両者の不一致の可能性を生じさせます。不一致が、たとえば仲介者が転送中にHTTPステータスコードを変更したこと （プロキシやキャッシュなどによって）を示している可能性があるため、両者の相対的な優先順位は明確ではありません。 汎用HTTPソフトウェア（プロキシ、ロードバランサー、ファイアウォール、ウイルススキャナーなど）は、 このメンバーで伝達されるステータスコードを知っている、または尊重する可能性が低いです。¶

6. IANAに関する考慮事項

IANAは、"Media Types"レジストリ配下の"application"レジストリにおいて、 "application/problem+json"および"application/problem+xml"の登録をこの文書を参照するよう更新しました。¶

IANAは、セクション4.2で規定される"HTTP Problem Types"レジストリを作成し、 セクション4.2.1に従って"about:blank"を登録しました。¶

付録A. HTTP問題用のJSON Schema

このセクションは、HTTP問題詳細のための非規範的なJSON Schema [JSON-SCHEMA]を示します。 これと仕様本文の間に不一致がある場合、後者が優先します。¶

# NOTE: '\' line wrapping per RFC 8792
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "An RFC 7807 problem object",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri-reference",
      "description": "A URI reference that identifies the \
problem type."
    },
    "title": {
      "type": "string",
      "description": "A short, human-readable summary of the \
problem type."
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code \
generated by the origin server for this occurrence of the problem.",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string",
      "description": "A human-readable explanation specific to \
this occurrence of the problem."
    },
    "instance": {
      "type": "string",
      "format": "uri-reference",
      "description": "A URI reference that identifies the \
specific occurrence of the problem. It may or may not yield \
further information if dereferenced."
    }
  }
}

付録B. HTTP問題とXML

XML [XML]を使用するHTTPベースのAPIは、 この付録で定義される形式を使用して問題詳細を表現できます。¶

XML形式のためのRELAX NGスキーマ [ISO-19757-2] は次のとおりです。¶

   default namespace ns = "urn:ietf:rfc:7807"

   start = problem

   problem =
     element problem {
       (  element  type            { xsd:anyURI }?
        & element  title           { xsd:string }?
        & element  detail          { xsd:string }?
        & element  status          { xsd:positiveInteger }?
        & element  instance        { xsd:anyURI }? ),
       anyNsElement
     }

   anyNsElement =
     (  element    ns:*  { anyNsElement | text }
      | attribute  *     { text })*

このスキーマは文書化のみを意図しており、XML形式のすべての制約を捉える規範的スキーマではないことに注意してください。 選択したスキーマ言語の機能に応じて、他のXMLスキーマ言語を使用して同様の制約の集合を定義することが可能です。¶

この形式のメディア型は"application/problem+xml"です。¶

拡張の配列およびオブジェクトは、1つ以上の子を含む要素をオブジェクトとして表すものと見なすことで、 XML形式へシリアライズされます。ただし、"i"という名前の子要素のみを1つ以上含む要素は、配列と見なされます。 たとえば、上記の例はXMLでは次のように表されます。¶

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

<?xml version="1.0" encoding="UTF-8"?>
<problem xmlns="urn:ietf:rfc:7807">
  <type>https://example.com/probs/out-of-credit</type>
  <title>You do not have enough credit.</title>
  <detail>Your current balance is 30, but that costs 50.</detail>
  <instance>https://example.net/account/12345/msgs/abc</instance>
  <balance>30</balance>
  <accounts>
    <i>https://example.net/account/12345</i>
    <i>https://example.net/account/67890</i>
  </accounts>
</problem>

この形式はXML名前空間を使用します。これは主に、他のXMLベース形式へ埋め込むことを可能にするためであり、 他の名前空間の要素または属性で拡張できる、または拡張すべきであることを意味しません。 RELAX NGスキーマは、XML形式で使用される1つの名前空間からの要素のみを明示的に許可します。 すべての拡張配列およびオブジェクトは、その名前空間のみを使用してXMLマークアップに MUSTシリアライズされます。¶

XML形式を使用する場合、参照されるXSL Transformations（XSLT）コード [XSLT]を使用してXMLを変換するようクライアントに指示するXML処理命令を、 XMLに埋め込むことが可能です。このコードがXMLを(X)HTMLへ変換する場合、XML形式を提供しつつ、 変換を実行できるクライアントに、人間にわかりやすい(X)HTMLをレンダリングして表示させることが可能です。 この方法を使用する場合、XSLTコードを実行できるクライアントの数を最大化するために、XSLT 1.0を使用することが望ましいことに注意してください。¶

付録C. 問題詳細を他の形式で 使用する

場合によっては、ここで説明されている形式以外の形式に問題詳細を埋め込むことが有利なことがあります。 たとえば、HTML [HTML5]を使用するAPIは、 その問題詳細を表現するためにもHTMLを使用したいかもしれません。¶

問題詳細は、既存のシリアライゼーション（JSONまたはXML）のいずれかをその形式にカプセル化するか、 問題詳細のモデル（セクション3で規定）を その形式の慣例へ変換することによって、他の形式に埋め込むことができます。¶

たとえば、HTMLでは、scriptタグ内にJSONをカプセル化することで問題を埋め込むことができます。¶

<script type="application/problem+json">
  {
   "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"]
  }
</script>

または、Resource Description Framework in Attributes（RDFa）[RDFA]へのマッピングを定義することもできます。¶

この仕様は、問題詳細を他の形式に埋め込むことについて具体的な推奨を行いません。 それらを埋め込む適切な方法は、使用される形式と、その形式の適用の両方に依存します。¶

付録D. RFC 7807からの変更点

この改訂では次の変更が行われました。¶

• セクション4.2は、共通の問題 型URIのレジストリを導入します¶
• セクション3は、複数の問題を どのように扱うべきかを明確化します¶
• セクション3.1.1は、逆参照できないtype URIを使用するための 指針を提供します¶

謝辞

著者らは、 Jan Algermissen、 Subbu Allamaraju、 Mike Amundsen、 Roy Fielding、 Eran Hammer、 Sam Johnston、 Mike McCall、 Julian Reschke、および James Snell のコメントと提案に感謝します。¶

著者の連絡先