Skip to main content

エラーの設計: ステータスコードと Problem Details

表現の設計の章で、注文するのリクエストと注文の表現の JSON を決めました。この章では、うまくいかなかったときに何を返すかを決めます。決めるのは、失敗ごとのステータスコードと、誤りの応答の本文の形です。

決めたものは、サンプルリポジトリの docs/api-design/problems.md に置きました。誤りの応答の例は examples/problems/ に置き、例が決まりに合うことと、ユースケースの失敗がどれも決まりに載っていることをテストで確かめます。第 2 部の実装は、この決まりを写して失敗を HTTP の応答にします。

失敗を並べる​

失敗の出どころは 3 つあります。

1 つ目は、要件の整理の章で書いたユースケースの別の流れです。注文するには 2a (入力の誤り)・3a (登録されていない商品)・4a (在庫が足りない) が、注文を確かめるには 2a (注文が無い) があります。2 つ目は、表現の設計の章で決めた形の決まりです。本文が JSON として読めない、知らないキーがある、値が null のような失敗は、ユースケースには書いていません。3 つ目は、HTTP の層の失敗です。エンドポイントの一覧に無いパス (404)、そのパスで受け付けないメソッド (405)、Accept に合う表現が無い (406)、本文のメディアタイプを受け付けない (415) は、どの操作にも起きます。これに、サーバーの予期しない誤り (500) を足します。

並べた結果を、誤りの応答の決まりの最初の節にしました。

## 失敗の一覧

1 周目の 2 つの操作 (注文する・注文を確かめる) と、操作の外の HTTP の層で起きる失敗。ユースケースの列は、`docs/requirements/use-cases.md` の別の流れを指す。

| 操作 | 失敗 | ユースケース | 問題の型 | ステータスコード |
| --- | --- | --- | --- | --- |
| 注文する | 注文明細が無いか 100 を超える、同じ商品の注文明細が 2 つ以上ある、数量が 1 より小さい、連絡先メールアドレスが無いか形が正しくない | 注文する 2a | `/problems/invalid-request` | 400 |
| 注文する | 本文が JSON として読めない、表現の決まりのキーの表で「入れる」としていないキーがある、値が `null` か型が合わない | なし | `/problems/invalid-request` | 400 |
| 注文する | 登録されていない商品がある | 注文する 3a | `/problems/unknown-product` | 400 |
| 注文する | 在庫が数量より少ない商品がある | 注文する 4a | `/problems/insufficient-inventory` | 400 |
| 注文する | 本文のメディアタイプが `application/json` でない | なし | `about:blank` | 415 |
| 注文を確かめる | その注文 ID の注文が無い | 注文を確かめる 2a | `/problems/order-not-found` | 404 |
| 両方 | `Accept` が `application/json` を受け入れない | なし | `about:blank` | 406 |
| 両方 | サーバーの予期しない誤り | なし | `/problems/internal-error` | 500 |
| 操作の外 | エンドポイントの一覧に無いパス | なし | `about:blank` | 404 |
| 操作の外 | パスは一覧にあるが、そのパスで受け付けないメソッド | なし | `about:blank` | 405 |

- 4xx は、リクエストの中身か、リクエストを送った時点の状態が原因で、クライアントが直すか待つかすれば通りうる失敗に使う。5xx は、サーバーの側が原因の失敗に使う
- 400 は、リクエストの中身の誤り (登録されていない商品を含む) と、注文を受け付けるのに要る在庫が足りない失敗に使う。どちらの失敗かは `type` で伝える
- 1 周目の 2 つの操作では 409 を使わない。対象のリソースの今の状態と衝突する失敗が無いため
- 1 つのリクエストに複数の失敗があるときは、パス・メソッド・`Accept`・`Content-Type`・本文の形 (ユースケースの手順 2)・商品 (手順 3)・在庫 (手順 4) の順に確かめ、最初に当たった失敗だけを返す。本文の形の誤りも、最初に見つけた 1 つだけを `errors` に入れる
- 登録されていない商品と在庫が足りない商品は、当たった商品をすべて `productIds` に並べる
- パスの注文 ID は、サーバーが返した注文 ID と、文字列のまま比べる。大文字を含む注文 ID や、UUID の形でない注文 ID は、その注文 ID の注文が無いものとして扱う

表の「問題の型」の列は、この章の後半で決める誤りの種類の名前です。ここからは、ステータスコードの列をどう決めたかを順に書きます。

ステータスコードは分類、誤りの種類は本文で伝える​

メソッドとステータスコードの章で、4xx はクライアントの側に誤りがあること、5xx はサーバーの側で処理できなかったことを表すと書きました。注文の API では、4xx を「クライアントが何かを変えれば通りうる」失敗に、5xx を「クライアントには直せない」失敗に使います。クライアントが変えるのは、リクエストの中身か、送る時点 (在庫が増えるのを待つなど) です。

ステータスコードの数は、誤りの種類の数より少なく抑えます。RFC 9205 は、誤りには最も当てはまるステータスコードを使い、ステータスコードとアプリケーションの誤りを 1 対 1 に対応させるべきでないと勧めています。同じステータスコードの誤りを区別するには、本文かヘッダで細かい情報を伝えるべきだとし、その方法の 1 つに問題の詳細 (Problem Details) を挙げています (RFC 9205 の 4.6 節)。この章では、入力の誤り・登録されていない商品・在庫不足を、どれも 400 にしました。クライアントは、3 つを本文の type で見分けます。

入力の誤りは 400 にする​

入力の誤りには、ユースケースの手順 2 の確かめ (注文明細の数と重なり・数量・連絡先メールアドレス) と、表現の決まりの確かめ (JSON の構文・知らないキー・null・型) があります。メソッドとステータスコードの章で、400 と 422 のどちらにするかはこの章で決めると書きました。

HTTP の仕様の定義では、400 (Bad Request) は、不正な構文などクライアントの誤りと受け取れる何かのために、サーバーがリクエストを処理できないか処理しないことを示します (RFC 9110 の 15.5.1)。422 (Unprocessable Content) は、本文のメディアタイプを理解でき構文も正しいが、含まれる指示を処理できないことを示します (RFC 9110 の 15.5.21)。定義のとおりに分けるなら、JSON として読めない本文は 400 で、数量が 0 の注文明細は 422 です。

3 つの指針は、入力の誤りをどれも 400 にそろえています。

  • Zalando の指針は、400 を汎用のクライアントの誤りとし、本文が業務の決まりや意味の確かめに通らないときも、422 でなく 400 を返すべきだとしています。422 には do not use の印を付け、400 でほとんどの場合を扱え、2 つを区別する明確な利点が無さそうだとしています (400・422)
  • Google の AIP は、誤りの応答で google.rpc.Code の正準のコードを使わなければならないとしています (AIP-193)。システムの状態に関係なく引数に問題があることを示す INVALID_ARGUMENT は、HTTP の 400 に対応します (code.proto)
  • Azure の指針は、リクエストの形が不正なときや、JSON のフィールドの名前や値をそのサービスの版が理解できないときに、400 で失敗させるよう求めています (DO。知らないフィールド)

外れる例もあります。RFC 9457 (問題の詳細の仕様) は、入力の確かめの誤りを 422 で返す応答を例に載せています (RFC 9457 の 3 節)。

注文の API は、入力の誤りをすべて 400 にしました。400 と 422 のどちらを受け取っても、クライアントのすることは同じで、リクエストを直して送り直します。どこをどう直すかは、ステータスコードでなく本文の errors (この章の後半) で伝えます。構文の誤りと意味の誤りを 2 つのコードに分けても、クライアントがコードだけで取れる行動は増えません。

在庫不足も 400 にする​

在庫が数量より少ない商品があるとき (ユースケースの 4a) のステータスコードは、409 と 422 に 400 を加えた 3 つを比べ、400 にしました。登録されていない商品 (3a) も 400 です。

409 と 422 の定義​

409 (Conflict) は、対象のリソースの今の状態との衝突のために、リクエストを完了できなかったことを示します。利用者が衝突を解いてリクエストを送り直せそうな状況で使い、サーバーは衝突の原因が分かるだけの情報を含めるべきだとしています (SHOULD。RFC 9110 の 15.5.10)。仕様は、409 が最も起きやすいのは PUT への応答だとし、版を管理しているときに、PUT した表現が先に処理された別のリクエストの変更と衝突する場合を例に挙げています。

422 は、上で引いたとおり、含まれる指示を処理できないことを示します。在庫不足のリクエストは、指示としては処理できます。りんごを 2 個という注文は、在庫が 10 なら受け付けられる指示です。断る理由は、指示の中身でなく、今の在庫にあります。

在庫不足は、409 の定義の「対象のリソース」にも当たりません。POST /orders の対象のリソースは注文のコレクションです。在庫は、ドメインモデルの章で注文と別の集約にし、リソースの設計の章で 1 周目の API のリソースに出さないと決めたもので、注文のコレクションの状態ではありません。

3 つの候補を比べる​

候補支える材料反する材料
409衝突を解いて送り直せる状況で使う、という定義の後半は在庫不足にも読める衝突は対象のリソースの今の状態とのもので、在庫は注文のコレクションの状態でない。一次ソースの 409 の例 (版の衝突・作ろうとした実体が既にある・作成時だけ指定できるフィールドの食い違い・先に取られた予約) は、どれも対象のリソースの状態との衝突
422構文が正しい本文の、意味の誤りに使える指示そのものは処理できる。Zalando は 422 を使わない (do not use)
400AIP は、システムの状態が明示的に直されるまで送り直すべきでない失敗を FAILED_PRECONDITION とし、400 に対応させる。RFC 9205 は、迷ったら 200・400・500 の汎用のコードを多めに使うよう勧める400 の定義の「クライアントの誤りと受け取れる何か」に、在庫不足はそのままは当たらない。本文を直す入力の誤りと、在庫が増えれば通る在庫不足が、同じコードになる

AIP の google.rpc.Code は、FAILED_PRECONDITION・ABORTED・UNAVAILABLE の選び方を、クライアントがどこから送り直すかで分けています。失敗した呼び出しだけを送り直せるなら UNAVAILABLE です。test-and-set の失敗のように、上の段 (読み・変え・書くの一連) の初めに戻ってやり直すべきなら ABORTED (409) です。空でないディレクトリの削除のように、システムの状態が明示的に直されるまで送り直すべきでないなら FAILED_PRECONDITION (400) です (code.proto の FAILED_PRECONDITION の注釈)。在庫不足は、入荷や取り消しで在庫が増えるまで送り直しても通らないので、3 つ目に当たります。409 に対応するコードは、並行性の問題などによる中断を示す ABORTED と、作ろうとした実体が既にあることを示す ALREADY_EXISTS です。Martin Fowler の Richardson 成熟度モデルの記事も、予約の枠を他の人が先に取った失敗に 409 を選び、リソースが両立しない形で先に更新されたことを示すとしています (Level 2)。

Zalando の指針は、409 を使うなら文書化しなければならないとし、If-* ヘッダによる衝突には 412 を使うとしています (409)。Azure の指針は、既存のリソースへの PATCH で、作成時だけ指定できるフィールドが今の値と食い違うときに 409 を使うとし、この行に「allows retries」(送り直しを許す) と注記しています (作成と更新の処理の規則)。どれも、対象のリソースの状態との衝突です。RFC 9205 は、迷ったら汎用のコードを多めに使うよう勧めています (RFC 9205 の 4.6 節)。

注文の API は、在庫不足を 400 にしました。入力の誤りと同じコードになりますが、type (/problems/insufficient-inventory) で見分けられます。上の「ステータスコードは分類、誤りの種類は本文で伝える」の決めと同じ扱いで、AIP も、同じ 400 の中の INVALID_ARGUMENT と FAILED_PRECONDITION を、本文の正準のコードで分けています。400 の定義の「クライアントの誤り」から外れる点は、type で在庫不足と分かるので、クライアントが入力を直そうとして迷うことはありません。409 は、対象のリソースの今の状態との衝突に取っておきます。1 周目の 2 つの操作には、この失敗がありません。

登録されていない商品​

登録されていない商品 (3a) も 400 にしました。商品 ID が、どの商品も指していないので、クライアントがリクエストを直す誤りです。404 にはしません。404 は対象のリソースが見つからないことを示し (RFC 9110 の 15.5.5)、POST /orders の対象の注文のコレクションはあるからです。type は /problems/unknown-product にし、在庫不足と同じく、当たった商品の商品 ID を返します。

後の部で 409 を使いうる場面​

409 は、後の部で使いうるコードです。1 周目に 409 を使わないので、後の部の決めを縛りません。

1 つは、冪等性キーの処理中の送り直しです。第 4 部で扱う冪等性キーのヘッダは、IETF の httpapi WG の Internet-Draft (draft-ietf-httpapi-idempotency-key-header) で、まだ RFC ではありません (datatracker)。08 版 (2026 年 10 月 22 日) は、同じキーの元のリクエストがまだ処理中のうちに送り直されたら、409 を返すべきだとしています (SHOULD)。同じキーを別の本文に使い回したら 422、キーが要る操作でキーが無ければ 400 を返すべきだとしています。クライアントは送り直す前にリクエストを直さなければならないが、409 だけは直さなくてよい、とも書いています (08 版の 2.7 節)。Internet-Draft は作業中の文書なので、ここでは作業中の版として引きます。

もう 1 つは、注文の取り消しの送り直しです。すでに取り消した注文をもう一度取り消すリクエストに、409 を返すか成功を返すかは、取り消しの URL と一緒に第 4 部で決めます。

誤りの応答の形: 問題の詳細​

誤りの応答の本文には、問題の詳細 (Problem Details for HTTP APIs) の形を使います。RFC 9457 が定める、HTTP API の誤りの共通の形です。RFC 9457 は RFC 7807 を廃止 (obsolete) しました (RFC 9457)。本文の冒頭の日付は 2023 年 7 月、RFC Editor の発行の記録は 2023 年 8 月です (RFC 9457 の記録)。

RFC 9457 のねらいは、誤りの形が要るアプリケーションに共通の形を与え、それぞれが形を決めたり、既存のステータスコードの意味を定め直したりしなくて済むようにすることです (RFC 9457 の 1 節)。JSON で書くときのメディアタイプは application/problem+json です。メンバーは 5 つ定められています。

メンバー中身
type問題の型を識別する URI 参照。受け手は、この URI (相対 URI なら解決した後の URI) を問題の型の主な識別子として使わなければならない (MUST)。無ければ about:blank とみなす
title問題の型の、人が読める短い要約。発生ごとに変えるべきでない (SHOULD NOT。翻訳は除く)
statusサーバーが作ったステータスコード。参考の値で、実際の応答のステータスコードと同じにしなければならない (MUST)
detailその発生に固有の、人が読める説明。クライアントが問題を直す助けになることを重んじる。受け手は、これを読み取って情報を取り出すべきでない (SHOULD NOT)
instance問題の個々の発生を識別する URI 参照。参照できない URI なら、サーバーにとって意味を持ちうるが、クライアントには中身の分からない、発生ごとの一意な識別子になる

出典は RFC 9457 の 3.1 節 です。問題の型ごとに、メンバーを足せます (拡張メンバー)。クライアントは、知らない拡張メンバーを無視しなければなりません (MUST。3.2 節)。

決めた問題の型の表です。

## 問題の型

| 型 | ステータスコード | 題 | 使う場面 | 拡張メンバー | 例 |
| --- | --- | --- | --- | --- | --- |
| `/problems/invalid-request` | 400 | `Invalid request` | 本文が JSON として読めないか、形や値が表現の決まりとユースケースの手順 2 に合わない | `errors` | `invalid-request.json` |
| `/problems/unknown-product` | 400 | `Unknown product` | 登録されていない商品がある | `productIds` | `unknown-product.json` |
| `/problems/insufficient-inventory` | 400 | `Insufficient inventory` | 在庫が数量より少ない商品がある | `productIds` | `insufficient-inventory.json` |
| `/problems/order-not-found` | 404 | `Order not found` | その注文 ID の注文が無い | なし | `order-not-found.json` |
| `/problems/internal-error` | 500 | `Unexpected error` | サーバーの予期しない誤り | `trackingId` | `internal-error.json` |
| `about:blank` | 404 | `Not Found` | エンドポイントの一覧に無いパス | なし | `not-found.json` |
| `about:blank` | 405 | `Method Not Allowed` | パスは一覧にあるが、そのパスで受け付けないメソッド | なし | `method-not-allowed.json` |
| `about:blank` | 406 | `Not Acceptable` | `Accept` が `application/json` を受け入れない | なし | `not-acceptable.json` |
| `about:blank` | 415 | `Unsupported Media Type` | 本文のメディアタイプが `application/json` でない | なし | `unsupported-media-type.json` |

- 誤りの応答の本文は、`Content-Type: application/problem+json` で返す。リクエストの `Accept` に `application/problem+json` が無くても、この形で返す。クライアントには、`Accept: application/json, application/problem+json` を送ることを勧める
- 本文には、`type`・`title`・`status` をいつも入れる。`type` が `about:blank` でも省かない。`status` は応答のステータスコードと同じ値にする
- `detail` は、題より詳しく言えることがあるときだけ入れる。クライアントは `detail` を読み取って処理を分けない。分けるときは `type` と拡張メンバーを使う
- `instance` は、1 周目は使わない
- 題と `detail` は英語で書く。`type` が `about:blank` の題は、RFC 9110 のステータスコードの名前と同じにする
- 自前の型は、`/problems/` に小文字の英語の kebab-case をつないだ相対 URI にする。型の識別子は、相対 URI を応答の文書の基準の URI (base URI) に対して解決した URI になる (RFC 9457 の 3.1.1)。1 周目のサーバーは、この URI に文書を置かない。問題の型の文書は、この表と、1 周目の API の仕様 (OpenAPI) に置く
- 汎用の失敗 (エンドポイントの一覧に無いパス・メソッド・`Accept`・`Content-Type`) には `about:blank` を使う。注文が無いことは、ユースケースの別の流れなので、自前の型にする
- 405 の応答には、そのパスで受け付けるメソッドを並べた `Allow` ヘッダを付ける。415 の応答には、`Accept: application/json` を付ける

RFC 9457 は、新しい問題の型を定めるときに、型の URI・短い題・使うステータスコードの 3 つを文書にしなければならないとしています (MUST。RFC 9457 の 4 節)。表の最初の 3 列が、この 3 つです。在庫の型の名前は、Zalando の例 (/problems/out-of-stock) と違い、用語集の在庫の code (Inventory) から取りました。

問題の型の URI​

自前の型の URI は、/problems/insufficient-inventory のような、完全なパスの相対 URI にしました。

RFC 9457 は、type が相対 URI なら、文書の基準の URI (base URI) に対して解決するとしています。そのうえで、相対 URI は混乱を招きうるうえ、すべての実装が正しく扱うとは限らないので、type にはできるかぎり絶対 URI を使うことを推奨しています (RECOMMENDED)。相対 URI を使うなら、/types/123 のように完全なパスにします。type の URI が https のような所在を示す URI なら、参照したときに人が読める説明を返すべきだとしています (SHOULD)。参照できない URI (tag URI など) も使えますが、後から参照できる URI に変えると型の識別子が変わり、互換でない変更になります (RFC 9457 の 3.1.1 節)。

Zalando の指針は、type と instance に /problems/out-of-stock のような相対 URI を使うことを提案し、絶対 URI は禁止しないが強く勧めない、としています。識別子を参照できるものにしないことも、意図して決めています。API の重要な部分はどのみち OpenAPI で文書化しなければならないうえ、URL は組織や文書の変更で壊れやすく、長くはあまり安定しない傾向があるためです (規則 176)。

注文の API は、Zalando と同じく相対 URI にしました。受け手が識別子に使うのは、相対 URI を応答の文書の基準の URI に対して解決した URI です。完全なパスの相対 URI は、基準の URI のスキームと authority (ホストとポートの部分) に、そのパスをつないだ URI に解決されます (RFC 3986 の 5.2.2 節)。同じスキームと authority で呼んだ応答なら、操作が違っても (POST /orders と GET /orders/{orderId} など)、識別子は同じです。スキームか authority が違えば (モックとサーバーを別のポートで動かすときなど)、同じ型でも解決した後の識別子が違います。絶対 URI にしなかったのは、型の URI を置けるホスト名 (API の持ち主が持つもの) がまだ無いためです。ホスト名を持って絶対 URI に切り替えると、識別子も変わります。

1 周目のサーバーはこの URL に文書を置かないので、RFC 9457 の「参照したら説明を返すべき」(SHOULD) には従いません。問題の型の説明は、上の表と、この部の後半で書く API の仕様 (OpenAPI) に置きます。相対 URI を正しく解決しない実装がありうることも、RFC 9457 の但し書きのとおりです。

汎用の失敗は about:blank にする​

about:blank は、問題の型がステータスコードの意味のほかに何の意味も持たないことを示します。about:blank を使うときの題は、そのステータスコードの名前 (404 なら Not Found) と同じにすべきです (SHOULD。RFC 9457 の 4.2.1 節)。RFC 9457 は、どのリソースにも当てはまる汎用の問題は、ふつうはステータスコードだけで表すほうがよいともしています (4 節)。

エンドポイントの一覧に無いパス・メソッド・Accept・Content-Type の失敗は、どのリソースにも起きるので、about:blank にしました。405 には、受け付けるメソッドを並べた Allow ヘッダが必須です (MUST。RFC 9110 の 15.5.6)。415 の原因がメディアタイプなら、応答の Accept ヘッダで受け付けるメディアタイプを示せます (RFC 9110 の 15.5.16)。

注文が無いことは、同じ 404 でも自前の型 (/problems/order-not-found) にしました。汎用の問題はステータスコードだけで、という RFC 9457 の勧めとは違う選択です。理由は、404 を返すのがアプリケーションだけではないためです。Zalando の規則 256 は、サイドカー・プロキシ・ゲートウェイのような中継の部品が、経路の設定が無いか誤っているときに 404 を返してはならないとしています (MUST。規則 256)。規則 257 は、その裏返しとして、クライアントは 404 がいつもバックエンドのリソースの状態を表すとは当てにできないとしています。ネットワークの環境によっては、404 を慎重に解釈し、急いで確定的な結論を出さないよう求めています (SHOULD。規則 257)。type が /problems/order-not-found なら、クライアントは、アプリケーションが注文を探して見つからなかったと分かります。about:blank の 404 は、パスの綴り違いか、中継の部品の設定の誤りかもしれません。

パスの注文 ID は、サーバーが返した注文 ID と文字列のまま比べます。表現の設計の章で、注文 ID の英字を小文字にそろえたのは、クライアントが注文 ID を文字列のまま扱えるようにするためでした。RFC 9562 は UUID の英字を大文字で書くことも認めていますが (RFC 9562 の 4 節)、大文字にした注文 ID は、サーバーが返したどの注文 ID とも違う文字列なので、注文が無いものとして 404 を返します。大文字も受け付けると、1 つの注文を指す URL が 2 つ以上になります。UUID の形でない注文 ID も、形の誤り (400) にはせず、同じく注文が無いものとして扱います。クライアントは注文 ID の中身を読まない前提なので、形の誤りを分けて伝えても、クライアントの取る行動は変わりません。

拡張メンバー​

誤りの種類ごとに、クライアントが次の行動を決めるのに要る値を、拡張メンバーで返します。

## 拡張メンバー

| メンバー | 語 | 型 | 中身 |
| --- | --- | --- | --- |
| `errors` | なし | 配列 (要素は 1 つ) | 最初に見つけた本文の誤り。要素は `pointer` と `detail` を持つ |
| `productIds` | 商品 ID | 配列 (1 つ以上) | 当たった商品の商品 ID。同じ商品 ID を 2 度入れない |
| `trackingId` | 追跡 ID | 文字列 | その 500 の応答の追跡 ID。同じ値をサーバーのログにも残す |

- ドメインの値を運ぶメンバーの名前は、表現の決まり (`representation.md`) のキーの節の箇条に従う
- ドメインの語でないメンバー (`errors` と、その要素の `pointer`・`detail`) は、RFC 9457 の例と同じ名前にする
- `pointer` は、リクエストの本文の中の誤りの位置を、JSON Pointer (RFC 6901) の文字列で表す。先頭に `#` を付けない。本文が JSON として読めないときは、本文全体を指す `""` にする。無いキーは、あるはずの位置を指す (`/contactEmail`)。注文明細が無いか 100 を超えるときは `/lines` を指す。同じ商品の注文明細が 2 つ以上あるときは、前から読んで、前の注文明細と商品が重なった最初の注文明細の `productId` を指す (りんごの注文明細が 0・1・2 番目にあれば `/lines/1/productId`)
- 在庫が足りない商品の、在庫の数は返さない
- クライアントは、知らない拡張メンバーを無視する

名前は、表現の設計の章で決めたキーの決まり (用語集の code と同じ名前、配列は要素の語の複数形の英語) を、ドメインの値を運ぶメンバーに当てました。表現の決まりのキーの節を API 全体に当てるかは、この部の後半で設計の決まりをまとめるときに決めます。問題の詳細の status は、用語集の状態 (注文の状態、code は status) と同じ名前で、別の意味です。RFC 9457 が定めた名前なので、変えられません。RFC 9457 は、拡張メンバーの名前を英字で始め、英字・数字・_ だけで 3 文字以上にすべきだとしています (SHOULD。4 節)。camelCase の名前は、これに合います。

errors の要素の pointer は、誤りの位置を JSON Pointer で表します。JSON Pointer は、/ の後ろに参照のトークンを続けて並べた文字列で、トークンの中の ~ は ~0 に、/ は ~1 に書き換えます (RFC 6901 の 3 節)。/lines/0/quantity は、lines の 0 番目の要素の quantity を指します。RFC 9457 の例は #/age のように先頭に # を付けた、URI のフラグメントの形で書いています (RFC 9457 の 3 節)。このガイドは # を付けません。JSON Pointer をフラグメントとして使えるのは、メディアタイプがフラグメントの書き方を JSON Pointer と定めた場合に限られ、application/json はそう定めていないためです (RFC 6901 の 6 節)。

在庫が足りない商品は、商品 ID だけを返します。表現の設計の章で同じ商品の注文明細を 1 つまでにしたので、商品 ID で注文明細が 1 つに決まります。在庫の数は返しません。1 周目は誰でも注文するを呼べるので、数を返すと、在庫の数を誰にでも見せることになります。数は、返した直後に別の注文で変わりえます。

instance は 1 周目は使いません。参照できない URI の instance は、発生ごとの中身の分からない識別子になるので、追跡 ID の役目にも使えます。ただし instance は URI 参照なので、追跡 ID を URI の形に包む必要があります。追跡 ID は用語集の語なので、code の名前の拡張メンバー (trackingId) で返すことにしました。

誤りの応答のメディアタイプ​

表現の設計の章で、Accept: application/json だけを送ったクライアントに誤りを返すときの扱いを、この章に送りました。注文の API は、Accept に関わらず、誤りの応答を application/problem+json で返します。

RFC 9457 の 3 節の 2 つ目の例は、Accept: application/json だけを送ったクライアントに、application/problem+json で応答しています。続く文は、クライアントが application/problem+json を Accept に挙げていなくても、API がこの形で応答するのは HTTP が許していることだとしています (RFC 9457 の 3 節)。HTTP の仕様は、Accept などで送った好みは、誤りの表現を含む応答の内容すべてに当てはまるとしています。一方で、ユーザーエージェントは好みがいつも守られることを当てにできず、サーバーは 406 を送るより好みに合わない応答を送るほうがよいと判断することもある、としています (RFC 9110 の 12.1)。誤りの応答は、成功の表現と別の形なので、クライアントが成功の形として読まないよう、メディアタイプで区別します。

Zalando の指針は、application/problem+json は application/json の一部として実装されていないことが多いと書いています。そのため、拡張した誤りの情報を受け取るには、クライアントが Accept に application/problem+json を含める必要があるとしています (Hint)。同じ規則は、クライアントは問題の詳細が返ることに頼ってはならないとも注記しています。誤りの応答は、この指針を知らない基盤の部品が作ることがあるためです (規則 176)。注文の API のクライアントは、RFC 9457 の 1 つ目の例と同じく、Accept: application/json, application/problem+json を送ることを勧めます。

406 の判定のしかたも、ここで決めました。表現の決まりのメディアタイプの節を、この章で書き換えています。

## メディアタイプ

1 周目の 2 つの操作に当てた決まり。JSON でない本文 (画像など)、JSON の差分を表すメディアタイプ (JSON Merge Patch など)、メディアタイプで API の版を表すかは、後の周回で比べて決める。

- リクエストの本文は、`Content-Type: application/json` で送る。メディアタイプ (パラメータを除いた type と subtype を、大文字小文字を区別せずに比べる) が `application/json` でなければ 415 を返し、応答の `Accept` ヘッダに `application/json` を書く
- 成功の応答の本文は、`application/json` で返す。`charset` のパラメータは付けない
- リクエストの `Accept` が `application/json` を受け入れないなら、406 を返す。`application/json` に当たるメディア範囲のうち最も具体的なもの (`application/json`・`application/*`・`*/*` の順) の `q` が 0 か、当たる範囲が無ければ、受け入れないとみなす。メディア範囲の type と subtype は大文字小文字を区別せずに比べ、`q` のほかのパラメータは見ない。`Accept` が無ければ、`application/json` で返す
- 誤りの応答は、`Accept` に関わらず `application/problem+json` で返す (`problems.md`)

HTTP の仕様は、ある型に複数のメディア範囲が当てはまるときは最も具体的なものが優先するとし (RFC 9110 の 12.5.1)、重み q の 0 は「受け入れられない」を意味するとしています (12.4.2)。Accept: application/json; q=0, */* は、application/json を受け入れません。

charset=utf-8 のような q のほかのパラメータを見ないのは、このガイドの決めです。12.5.1 は、メディア範囲にパラメータを付けられるとしていますが、パラメータ付きの範囲がどの型に当たるかを定める文はありません。application/json には charset のパラメータが定められておらず、付けても仕様に従う受け手には何の効果もないので (RFC 8259 の 11 節)、Accept: application/json; charset=utf-8 を、パラメータを理由に断ることはしません。

500 と追跡 ID​

機能でない要件には、予期しない誤りの応答に内部の情報 (スタックトレースや SQL の文) を載せないと書きました。代わりに追跡 ID を載せ、同じ追跡 ID をログにも残します。500 の応答の trackingId が、その追跡 ID です。

RFC 9457 は、発生の情報へのリンクを出すときに、スタックダンプのような実装の詳細を HTTP のインターフェースから見えるようにしないよう勧めています。サーバーの実装やデータの機微な詳細を晒しうるためです (RFC 9457 の 5 節)。Zalando の指針は、スタックトレースを外に出してはならないとしています (MUST。規則 177)。

{
"type": "/problems/internal-error",
"title": "Unexpected error",
"status": 500,
"detail": "Include the trackingId when you contact us.",
"trackingId": "4f3a9c2e-7b1d-4e8a-9c05-2d6b8f1e3a70"
}

追跡 ID は、1 つのリクエストを通して付ける相関 ID とは別の語です (用語集の定義)。追跡 ID の作り方と、ログへの残し方は第 2 部の実装で、相関 ID は第 8 部で扱います。クライアントは、追跡 ID の形を読み取りません。利用者が問い合わせに書き写す値として扱います。

スタイルガイドの誤りの形を比べる​

誤りの本文の形は、指針によって違います。

指針誤りの本文の形誤りの種類を機械が見分ける値入力の誤り
Zalando問題の詳細 (RFC 9457)。すべてのエンドポイントが 4xx と 5xx で返せなければならない (MUST)type (相対 URI を提案)400
Google の AIP-193google.rpc.Status を HTTP/1.1 の JSON に写した形 (最上位の error の中に code・message・status・details)details の ErrorInfo の reason と domain の組400 (INVALID_ARGUMENT)
Azure最上位の error オブジェクト (code と message が必須)error.code と、同じ値の x-ms-error-code ヘッダ400

Zalando は 規則 176 です。AIP-193 は、HTTP/1.1 の JSON の形は後方互換のために google.rpc.Status とそのまま対応しないが、同じ中核の情報を持つとしています。code には、google.rpc.Code の数値でなく HTTP のステータスコードを入れます (AIP-193 の HTTP/1.1+JSON の節)。すべての誤りの応答は details に ErrorInfo を含めなければならず (Status.details)、reason と domain の組が誤りを機械的に識別します (ErrorInfo)。Azure は、誤りのコードの文字列を x-ms-error-code ヘッダで返し (誤りのコードのヘッダ)、本文の最上位の error.code と同じ値にするよう求めています (DO。ヘッダと本文の一致・本文の形)。

AIP と Azure は、問題の詳細でない独自の形です。注文の API は、IETF の標準の形で、Zalando も採る問題の詳細を選びました。RFC 9457 は、問題の詳細が誤りを伝える唯一の方法ではなく、応答がなおリソースの表現なら、そのアプリケーションの形で詳細を書くほうが好ましいことも多いとしています (RFC 9457 の 1 節)。注文の API の誤りの応答は、注文の表現ではないので、問題の詳細で返します。

旧来の Microsoft REST API Guidelines は、非推奨になっています。github.com/microsoft/api-guidelines の直下の Guidelines.md は、冒頭の注記で、この文書は非推奨になり graph/Guidelines-deprecated.md へ移したと書いています。移した先の冒頭の注記は、Microsoft Graph の指針へ統合中で、削除の予定日は 2024 年 7 月 1 日だと書いています。予定日より後の 2026 年 10 月 30 日の版にも、このファイルは残っています (vNext の 1c58ca7 の版)。今の Azure のサービスには、上の表の Azure REST API Guidelines を参照するよう、同じリポジトリの README が案内しています。

例を JSON ファイルにして残す​

問題の型の表の行ごとに、誤りの応答の本文の例を 1 つずつ examples/problems/ に置きました。在庫が足りない例は、受け入れ条件の「一部の商品の在庫が足りないと、注文全体が受け付けられない」(りんご 2 個と保存容器 4 個、連絡先メールアドレスあり) の応答です。

{
"type": "/problems/insufficient-inventory",
"title": "Insufficient inventory",
"status": 400,
"detail": "1 product in the order does not have enough inventory.",
"productIds": ["01a0f4c2-c7e8-7b22-a963-4dae1f203b45"]
}

商品 ID は、表現の設計の章の例の保存容器です。入力の誤りの例は、1 つ目の注文明細の数量が 0 のリクエストへの応答です。

{
"type": "/problems/invalid-request",
"title": "Invalid request",
"status": 400,
"detail": "The request body has an error.",
"errors": [
{ "pointer": "/lines/0/quantity", "detail": "Must be an integer of 1 or more." }
]
}

本文の形の誤りが 2 つ以上あっても、errors には最初に見つけた 1 つだけを入れます。誤りをすべて集めるには、最初の誤りの後も検証を続けます。JSON Schema の検証器 Ajv の文書は、それでは遅い検証を防ぐ手立てが効かなくなるとして、誤りをすべて集める設定 (allErrors) を本番で使わないよう勧めています (Ajv の Security considerations)。クライアントは、誤りを 1 つずつ直して送り直します。題と detail は英語にしています。購入者に見せる文は、クライアントが type と拡張メンバーから組み立てます。人が読む文の言語は Accept-Language で交渉できますが (RFC 9457 の 1 節)、1 周目は英語だけにしました。

この章で足したテスト (test/problems.test.ts) は、次のことを確かめます。

  • examples/problems/ の例は、どれも JSON として読め、最上位がオブジェクト
  • 問題の型の表の行はどれも決めた形で書かれ、例のファイルと 1 対 1 で、自前の型は /problems/ と kebab-case の相対 URI で重ならず、about:blank の題はステータスコードの名前
  • 例の type・title・status は表の行と同じで、detail は空でない文字列で、例は行の拡張メンバーをすべて持ち、ほかには RFC 9457 の type・title・status・detail だけを持ち (instance は 1 周目は使わない)、null が無い
  • 拡張メンバーの表の行はどれも決めた形で書かれ、問題の型の表の拡張メンバーはこの表にあり、語は用語集にあり、配列でないメンバーの名前は語の code と同じ
  • 例の拡張メンバーの値は、そのメンバーの決まりに合い (errors は要素が 1 つで、pointer は # の無い JSON Pointer、productIds は重なりの無い文字列の配列など)、拡張メンバーの表の行にはどれも値の確かめ方がある
  • 失敗の一覧の行とユースケースの別の流れの行はどれも決めた形で書かれ、別の流れは use-cases.md に 1 回ずつある。別の流れはどれも一覧にちょうど 1 回あり、一覧の型とステータスコードの組は問題の型の表にあり、表の型はどれも一覧で使う

ユースケースに別の流れ (たとえば 4b) を足したのに、失敗の一覧に行を足し忘れると、6 つ目のテストで落ちます。別の流れの行を、- **4b**: … のように決めた形と違う書き方で足しても、拾えない行として同じテストで落ちます。拡張メンバーの表に行を足したのに、テストに値の確かめ方を足し忘れると、5 つ目のテストで落ちます。about:blank の題と比べるステータスコードの名前の表と、拡張メンバーの値の確かめ方は、文書から読まずにテストのコードに書いています。コードは章末の「この章のテストのコード」にあります。

見直しの観点​

誤りの返し方を決めたら、次の観点で見直します。

  • ユースケースの別の流れが、どれも失敗の一覧にあるか
  • 同じステータスコードの誤りを、本文の type で見分けられるか
  • 409 を、対象のリソースの今の状態との衝突のほかに使っていないか
  • 誤りの応答に、スタックトレースや SQL の文のような実装の詳細が無いか
  • クライアントが次の行動を決めるのに要る値 (誤りの位置・商品 ID) を、拡張メンバーで返しているか
  • 拡張メンバーで、在庫の数のような、見せなくてよい情報を返していないか
  • 中継の部品が返しうる 404 と、アプリケーションの 404 を見分けられるか

選ばなかった案​

ここまでで比べた案を、サンプルリポジトリにも残しました。

## 選ばなかった案

| 案 | 選ばなかった理由 |
| --- | --- |
| 入力の誤りを 422 にする | 400 と 422 のどちらでも、クライアントはリクエストを直す。誤りの種類は `type` と `errors` で伝える |
| 本文の形の誤りを、見つけたものをすべて `errors` に並べる | 誤りをすべて集めるには、最初の誤りの後も検証を続ける。JSON Schema の検証器 Ajv の文書は、それでは遅い検証を防ぐ手立てが効かなくなるとして、誤りをすべて集める設定を本番で使わないよう勧めている。クライアントは誤りを 1 つずつ直して送り直す |
| 在庫不足を 409 にする | 409 は、対象のリソースの今の状態との衝突を示す。在庫は 1 周目の API のリソースでなく、注文するの対象 (注文のコレクション) の状態でもない。状態が明示的に直されるまで送り直すべきでない失敗は、AIP も 400 に対応させている |
| 在庫不足を 422 にする | 本文の指示そのものは処理できる。Zalando の指針は 422 を使わない |
| 登録されていない商品を 404 にする | 注文するの対象のリソース (注文のコレクション) はある |
| 在庫不足の型を `/problems/out-of-stock` にする | 在庫の英語は、用語集の code (`Inventory`) にそろえる |
| 問題の型を絶対 URI にする | 型の URI を置けるホスト名 (API の持ち主が持つもの) がまだ無い。代償として、スキームか authority (ホストとポート) が違う応答 (モックとサーバーを別のポートで動かすときなど) では、同じ相対 URI でも解決した識別子が違う (完全なパスの相対 URI は、基準の URI のスキームと authority だけを使って解決される。RFC 3986 の 5.2.2)。RFC 9457 は絶対 URI を勧め、相対なら完全なパスにするよう勧めている。ホスト名を持って絶対 URI に切り替えると、識別子も変わる |
| 注文が無いことを `about:blank` の 404 にする | エンドポイントの一覧に無いパスの 404 や、中継の部品が返す 404 と区別できない |
| `pointer` を `#/lines/0/quantity` のように URI のフラグメントの形にする | `application/json` は、フラグメントの書き方を JSON Pointer と定めていない |
| 追跡 ID を `instance` に入れる | 参照できない URI の `instance` は、発生ごとの、クライアントには中身の分からない識別子として使える。ただし URI 参照なので、追跡 ID を URI の形に包む必要がある。追跡 ID は用語集の語なので、code の名前の拡張メンバーにする |
| 在庫不足で、在庫の数も返す | 1 周目は、誰でも注文するを呼べるので、在庫の数を誰にでも見せることになる。数は返した直後に変わりうる |

実務で効く注意点​

クライアントは、問題の詳細が返らない誤りも扱う​

API のサーバーが問題の詳細を返すと決めても、クライアントに届く誤りがすべてその形になるとは限りません。Zalando の規則 176 の注記のとおり、ロードバランサやプロキシのような基盤の部品は、API の決まりを知らずに誤りの応答を作ります。クライアントは、Content-Type が application/problem+json でない誤りの応答 (HTML の 502 など) を受け取っても止まらないよう、ステータスコードの分類 (4xx と 5xx) だけで扱う道を用意しておきます。

404 を「無い」と決めつけない​

Zalando の規則 257 が注意するとおり、404 はリソースが無いことだけを意味するとは限りません。経路の設定の誤りで中継の部品が 404 を返すと、クライアントは注文が消えたと誤解しえます。注文の API では、アプリケーションが注文を探して見つからなかったときだけ type を /problems/order-not-found にしています。クライアントは、type を見てから「注文が無い」と判断します。

まとめ​

  • 失敗は、ユースケースの別の流れ・表現の決まり・HTTP の層の 3 つから並べ、サーバーの予期しない誤りを足します
  • ステータスコードは誤りの分類を表し、誤りの種類は本文の type で伝えます。ステータスコードと誤りの種類を 1 対 1 にしません
  • 入力の誤りは 400 にしました。Zalando・AIP・Azure がそろって入力の誤りに 400 を使い、422 と分けてもクライアントの行動は変わりません
  • 在庫不足と登録されていない商品も 400 にし、type で見分けます。在庫は注文のコレクションの状態でないので、409 の「対象のリソースの今の状態との衝突」に当たりません。AIP も、状態が明示的に直されるまで送り直すべきでない失敗を 400 に対応させています。409 は、対象のリソースの今の状態との衝突に取っておきます
  • 誤りの応答は、Accept に関わらず問題の詳細 (application/problem+json) で返します。自前の型は完全なパスの相対 URI に、汎用の失敗は about:blank にします。相対 URI の型は、応答の文書の基準の URI に対して解決した URI が識別子になります
  • 誤りの位置は # の無い JSON Pointer で、在庫が足りない商品は商品 ID で返します。在庫の数は返しません。500 には追跡 ID を付け、実装の詳細を載せません

次に読む​

前の章は 表現の設計 です。

次章 OpenAPI では、ここまでに決めたエンドポイント・表現・誤りの応答を、OpenAPI 3.1 の仕様に書きます。

練習問題​

在庫が足りないときに、何個までなら注文できるかを購入者に見せたいという要望が来ました。どう考えますか

解答例

在庫の数を誤りの応答で返すと、注文するを呼べる人なら誰でも、数量を大きくして注文するだけで在庫の数を知れます。1 周目は認証が無いので、この API を呼べる人に制限がありません。返した数は、返した直後に別の注文で変わりえます。

見せるなら、まず要件として決めます。購入者が在庫の数を知る必要があるか、「残りわずか」のような表示で足りるかを、ストーリーと受け入れ条件に書きます。そのうえで、在庫の数を、誤りの応答の拡張メンバーで返すのか、第 4 部で足す商品の API で読ませるのかを比べます。誤りの応答で返すなら、用語集に語を足し、表現の決まりのキーの節の箇条で名前を決めて、拡張メンバーの表に行を足します。認証の後に、在庫の数を見せる相手を絞るかは、第 5 部の事柄です。

注文するに、同じ商品の注文明細を 2 つ並べたリクエストが来ました。どの問題の型で、どんな本文を返しますか

解答例

同じ商品の注文明細が 2 つ以上あるのは、ユースケースの手順 2 の誤り (2a) なので、/problems/invalid-request の 400 です。拡張メンバーの決まりで、pointer は、前の注文明細と商品が重なった最初の注文明細の productId を指します。りんごの注文明細を 0 番目と 1 番目に並べたなら、次の本文になります。

{
"type": "/problems/invalid-request",
"title": "Invalid request",
"status": 400,
"errors": [
{ "pointer": "/lines/1/productId", "detail": "Must not repeat a product of another line." }
]
}

在庫不足の型 (/problems/insufficient-inventory) でもありません。同じ商品の注文明細は、在庫がいくつあっても受け付けないので、リクエストを直さなければ通らない誤りです。

この章のテストのコード​

誤りの応答の例が、問題の型の表と 1 対 1 で、表と拡張メンバーの決まりに合うことと、ユースケースの別の流れがどれも失敗の一覧にあることを確かめるテストのコードです。読まなくても本文は追えます。

/*
* 誤りの応答の例 (examples/problems/) が、誤りの応答の決まり (docs/api-design/problems.md) の問題の型の表と 1 対 1 で、
* 表と拡張メンバーの決まりに合うことと、ユースケースの別の流れがどれも失敗の一覧にあることを確かめる。
* 第 2 部の実装は問題の型の表を写すので、表と例が食い違うと、どちらを写すかで応答が変わるため。
*/
import { readdirSync, readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { expect, it } from 'vitest';
import { parse } from 'yaml';

interface TypeRow {
type: string;
status: number;
title: string;
members: string[];
example: string;
}

interface MemberRow {
member: string;
term: string;
type: string;
}

interface FailureRow {
useCase: string;
type: string;
status: number;
}

function read(path: string): string {
return readFileSync(fileURLToPath(new URL(`../${path}`, import.meta.url)), 'utf8');
}

function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}

function isText(value: unknown): value is string {
return typeof value === 'string' && value !== '';
}

/** JSON として読めなければ、理由の文を返す。読めない例は、ほかのテストを止めずに、1 つ目のテストで落とす。 */
function parseJson(text: string): { value?: unknown; error?: string } {
try {
return { value: JSON.parse(text) as unknown };
} catch (error) {
return { error: error instanceof Error ? error.message : String(error) };
}
}

const problemsDoc = read('docs/api-design/problems.md');
const useCases = read('docs/requirements/use-cases.md');
const glossary: unknown = parse(read('docs/glossary.yaml'));
const exampleFiles = readdirSync(fileURLToPath(new URL('../examples/problems/', import.meta.url))).filter((name) => name.endsWith('.json'));
const parsed = new Map(exampleFiles.map((name) => [name, parseJson(read(`examples/problems/${name}`))]));
const examples = new Map([...parsed].map(([name, result]) => [name, result.value]));

/** RFC 9457 が定めるメンバーのうち、例に入れてよいもの (instance は 1 周目は使わない)。これ以外は、問題の型の表に書いた拡張メンバー。 */
const standardMembers = ['type', 'title', 'status', 'detail'];

/** RFC 9110 のステータスコードの名前。about:blank の題はこれと同じにする。表に about:blank の行を足したら、ここにも足す。 */
const statusNames: Record<number, string> = {
404: 'Not Found',
405: 'Method Not Allowed',
406: 'Not Acceptable',
415: 'Unsupported Media Type',
};

/** RFC 6901 の 3 節の ABNF を写した、JSON Pointer の文字列の形。空文字列は本文全体を指す。 */
const jsonPointer = /^(\/([^/~]|~[01])*)*$/;

/** 拡張メンバーの値の確かめ方。拡張メンバーの表にメンバーを足したら、ここにも足す (足し忘れると 5 つ目のテストで落ちる)。 */
const memberChecks: Record<string, (value: unknown) => boolean> = {
errors: (value) =>
Array.isArray(value) &&
value.length === 1 &&
value.every((error) => isRecord(error) && Object.keys(error).sort().join() === 'detail,pointer' && typeof error.pointer === 'string' && jsonPointer.test(error.pointer) && isText(error.detail)),
productIds: (value) => Array.isArray(value) && value.length > 0 && value.every(isText) && new Set(value).size === value.length,
trackingId: isText,
};

/** header の行の表の本体 (見出しと区切りの行の次から、空行の前まで)。形の合わない行を数えられるよう、正規表現で拾う前の行を返す。 */
function tableLines(header: string): string[] {
const lines = problemsDoc.split(/\r?\n/);
const start = lines.indexOf(header);
if (start < 0) return [];
const end = lines.indexOf('', start);
return lines.slice(start + 2, end < 0 ? undefined : end);
}

/** 行を pattern で拾い、拾えない行は problems に足す。拾えない行が黙って抜けないよう、形の確かめと一緒に行う。 */
function rows<T>(header: string, pattern: RegExp, toRow: (match: RegExpExecArray) => T, problems: string[]): T[] {
const lines = tableLines(header);
if (lines.length === 0) problems.push(`表 ${header} が無いか、行が無い`);
return lines.flatMap((line) => {
const match = pattern.exec(line);
if (match === null) problems.push(`形の合わない行: ${line}`);
return match === null ? [] : [toRow(match)];
});
}

const typeHeader = '| 型 | ステータスコード | 題 | 使う場面 | 拡張メンバー | 例 |';
const typePattern = /^\| `([^`]+)` \| (\d{3}) \| `([^`]+)` \| [^|]+ \| (なし|`[a-zA-Z]+`(?:・`[a-zA-Z]+`)*) \| `([a-z-]+\.json)` \|$/;
const memberHeader = '| メンバー | 語 | 型 | 中身 |';
const memberPattern = /^\| `([a-zA-Z]+)` \| ([^|]+) \| ([^|]+) \| [^|]+ \|$/;
const failureHeader = '| 操作 | 失敗 | ユースケース | 問題の型 | ステータスコード |';
const failurePattern = /^\| [^|]+ \| [^|]+ \| ([^|]+) \| `([^`]+)` \| (\d{3}) \|$/;

/** 表ごとの形の崩れ。その表を使うテストで落とす。 */
const typeShape: string[] = [];
const memberShape: string[] = [];
const failureShape: string[] = [];
const typeRows = rows<TypeRow>(
typeHeader,
typePattern,
(m) => ({ type: m[1], status: Number(m[2]), title: m[3], members: m[4] === 'なし' ? [] : m[4].replaceAll('`', '').split('・'), example: m[5] }),
typeShape,
);
const memberRows = rows<MemberRow>(memberHeader, memberPattern, (m) => ({ member: m[1], term: m[2], type: m[3] }), memberShape);
const failureRows = rows<FailureRow>(failureHeader, failurePattern, (m) => ({ useCase: m[1], type: m[2], status: Number(m[3]) }), failureShape);

/**
* use-cases.md の別の流れを、「注文する 2a」のようにユースケースの名前と手順の番号で返す。
* 決めた形 (「## ユースケース: 」の下の「### 別の流れ」の節の「- **2a** …」の行) で拾えない行と見出しは、problems に足す。
* 書き方の違う 1 行が黙って抜けると、その流れが失敗の一覧に無くても 6 本目が通るため。
* 同じ別の流れが 2 回あるかは、返した一覧で 6 本目が確かめる。
*/
function alternateFlows(problems: string[]): string[] {
let name = '';
let inFlows = false;
return useCases.split(/\r?\n/).flatMap((line) => {
if (line.startsWith('#')) {
if (line.startsWith('## ')) name = /^## ユースケース: (.+)$/.exec(line)?.[1] ?? '';
inFlows = line === '### 別の流れ';
if (inFlows && name === '') problems.push(`ユースケースの見出しの下に無い別の流れの節: ${line}`);
if (!inFlows && line.includes('別の流れ')) problems.push(`形の合わない別の流れの見出し: ${line}`);
return [];
}
if (!inFlows) {
// 箇条の印は -・*・+ と番号 (1. や 1))。印の後の空白の数は問わない。
if (/^\s*([-*+]|\d+[.)])\s+\*\*\d+[a-z]\*\*/.test(line)) problems.push(`別の流れの節の外にある別の流れの行: ${line}`);
return [];
}
if (line === '') return [];
const flow = /^- \*\*(\d+[a-z])\*\* /.exec(line);
if (flow === null) problems.push(`形の合わない別の流れの行: ${line}`);
return flow === null || name === '' ? [] : [`${name} ${flow[1]}`];
});
}

/** 値の中の null の位置を、JSON Pointer で返す。どこを直せばよいかを、落ちたときの文に出すため。 */
function nullPointers(value: unknown, pointer = ''): string[] {
if (value === null) return [pointer];
if (Array.isArray(value)) return value.flatMap((item, index) => nullPointers(item, `${pointer}/${index}`));
if (!isRecord(value)) return [];
return Object.entries(value).flatMap(([key, item]) => nullPointers(item, `${pointer}/${key.replaceAll('~', '~0').replaceAll('/', '~1')}`));
}

/** 用語集の語の名前から code を引く表。 */
function codesByName(): Map<string, string | undefined> {
const terms = isRecord(glossary) && Array.isArray(glossary.terms) ? glossary.terms : [];
return new Map(terms.filter(isRecord).map((term) => [String(term.name), typeof term.code === 'string' ? term.code : undefined]));
}

it('examples/problems/ の例は、どれも JSON として読め、最上位がオブジェクト', () => {
const problems: string[] = [];
for (const [name, result] of parsed) {
if (result.error !== undefined) problems.push(`${name}: JSON として読めない (${result.error})`);
else if (!isRecord(result.value)) problems.push(`${name}: 最上位がオブジェクトでない`);
}
expect(problems).toEqual([]);
});

it('問題の型の表の行はどれも決めた形で書かれ、例のファイルと 1 対 1 で、自前の型は /problems/ と kebab-case の相対 URI で重ならず、about:blank の題はステータスコードの名前', () => {
const problems = [...typeShape];
const listed = typeRows.map((row) => row.example);
for (const name of listed.filter((name, index) => listed.indexOf(name) !== index)) problems.push(`例 ${name} が表に 2 回以上ある`);
for (const name of listed.filter((name) => !exampleFiles.includes(name))) problems.push(`例 ${name} が examples/problems/ に無い`);
for (const name of exampleFiles.filter((name) => !listed.includes(name))) problems.push(`examples/problems/${name} が表に無い`);
const ownTypes = typeRows.filter((row) => row.type !== 'about:blank').map((row) => row.type);
for (const type of ownTypes.filter((type, index) => ownTypes.indexOf(type) !== index)) problems.push(`型 ${type} が 2 回以上ある`);
for (const type of ownTypes.filter((type) => !/^\/problems\/[a-z]+(-[a-z]+)*$/.test(type))) problems.push(`型 ${type} が /problems/ と kebab-case の相対 URI でない`);
for (const row of typeRows.filter((row) => row.type === 'about:blank')) {
if (statusNames[row.status] === undefined) problems.push(`about:blank の ${row.status}: ステータスコードの名前がテストの表に無い`);
else if (row.title !== statusNames[row.status]) problems.push(`about:blank の ${row.status}: 題 ${row.title} が ${statusNames[row.status]} でない`);
}
expect(problems).toEqual([]);
});

it('例の type・title・status は表の行と同じで、detail は空でない文字列で、例は行の拡張メンバーをすべて持ち、ほかには RFC 9457 の type・title・status・detail だけを持ち、null が無い', () => {
const problems: string[] = [];
for (const row of typeRows) {
const example = examples.get(row.example);
if (!isRecord(example)) continue;
const where = row.example;
if (example.type !== row.type) problems.push(`${where}: type が ${JSON.stringify(example.type)} で、表の ${row.type} と違う`);
if (example.title !== row.title) problems.push(`${where}: title が ${JSON.stringify(example.title)} で、表の ${row.title} と違う`);
if (example.status !== row.status) problems.push(`${where}: status が ${JSON.stringify(example.status)} で、表の ${row.status} と違う`);
if ('detail' in example && !isText(example.detail)) problems.push(`${where}: detail が ${JSON.stringify(example.detail)} で、空でない文字列でない`);
const keys = Object.keys(example);
for (const key of keys.filter((key) => !standardMembers.includes(key) && !row.members.includes(key))) problems.push(`${where}: 表に無いメンバー ${key}`);
for (const member of row.members.filter((member) => !keys.includes(member))) problems.push(`${where}: 拡張メンバー ${member} が無い`);
for (const pointer of nullPointers(example)) problems.push(`${where}: ${pointer} が null`);
}
expect(problems).toEqual([]);
});

/*
* 語のある拡張メンバーの名前は、表現の決まりのキーの節の箇条に従う。配列のメンバーは要素の語の複数形の英語にするので、
* test/representation.test.ts と同じく code とは照らさず、語が用語集にあることだけを確かめる。
*/
it('拡張メンバーの表の行はどれも決めた形で書かれ、問題の型の表の拡張メンバーはこの表にあり、語は用語集にあり、配列でないメンバーの名前は語の code と同じ', () => {
const problems = [...memberShape];
const members = memberRows.map((row) => row.member);
for (const member of new Set(typeRows.flatMap((row) => row.members))) {
if (!members.includes(member)) problems.push(`${member}: 拡張メンバーの表に無い`);
}
const codes = codesByName();
for (const row of memberRows.filter((row) => row.term !== 'なし')) {
const code = codes.get(row.term);
if (!codes.has(row.term)) problems.push(`${row.member}: 語「${row.term}」が用語集に無い`);
else if (row.type.startsWith('配列')) continue;
else if (code === undefined) problems.push(`${row.member}: 語「${row.term}」に code が無い`);
else if (row.member !== code) problems.push(`${row.member}: 語「${row.term}」の code ${code} と違う`);
}
expect(problems).toEqual([]);
});

it('例の拡張メンバーの値は、そのメンバーの決まりに合い、拡張メンバーの表の行にはどれも値の確かめ方がある', () => {
const problems: string[] = [];
for (const row of memberRows) {
if (memberChecks[row.member] === undefined) problems.push(`${row.member}: 値の確かめ方が無い`);
}
for (const row of typeRows) {
const example = examples.get(row.example);
if (!isRecord(example)) continue;
for (const member of row.members) {
const check = memberChecks[member];
if (check !== undefined && member in example && !check(example[member])) problems.push(`${row.example} の ${member}: ${JSON.stringify(example[member])} が決まりに合わない`);
}
}
expect(problems).toEqual([]);
});

it('失敗の一覧の行とユースケースの別の流れの行はどれも決めた形で書かれ、別の流れは use-cases.md に 1 回ずつで、どれも失敗の一覧にちょうど 1 回あり、一覧の型とステータスコードの組は問題の型の表にあり、表の型はどれも一覧で使う', () => {
const problems = [...failureShape];
const flows = alternateFlows(problems);
if (flows.length === 0) problems.push('use-cases.md に別の流れが無い');
for (const flow of flows.filter((flow, index) => flows.indexOf(flow) !== index)) problems.push(`${flow}: use-cases.md に 2 回以上ある`);
const listed = failureRows.map((row) => row.useCase).filter((useCase) => useCase !== 'なし');
for (const flow of flows) {
const count = listed.filter((useCase) => useCase === flow).length;
if (count !== 1) problems.push(`${flow}: 失敗の一覧に ${count} 回ある`);
}
for (const useCase of listed.filter((useCase) => !flows.includes(useCase))) problems.push(`${useCase}: use-cases.md の別の流れに無い`);
const pairs = typeRows.map((row) => `${row.type} ${row.status}`);
const used = failureRows.map((row) => `${row.type} ${row.status}`);
for (const pair of used.filter((pair) => !pairs.includes(pair))) problems.push(`失敗の一覧の ${pair}: 問題の型の表に無い`);
for (const pair of pairs.filter((pair) => !used.includes(pair))) problems.push(`問題の型の表の ${pair}: 失敗の一覧で使っていない`);
expect(problems).toEqual([]);
});