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

表現の設計: JSON の形とメディアタイプ

リソースの設計の章で、注文の API の URL とメソッドを決めました。注文するは POST /orders、注文を確かめるは GET /orders/{orderId} です。この章では、その 2 つの操作がやり取りする本文の形 (表現) を決めます。

決めたものは、サンプルリポジトリの docs/api-design/representation.md に置きました。表現の例は examples/orders/ に置き、例が決まり (キーの表・値の形・注文明細の数と重なり) に合うことをテストで確かめます。

受け入れ条件の例から表現を決める​

表現は、受け入れ条件の具体的な値から考えます。要件の章で書いた受け入れ条件のうち、注文が受け付けられる例はこうでした。

  • 購入者が、りんごを 2 個と保存容器を 1 個、連絡先メールアドレス taro.test@example.com で注文する
  • 注文が受付の状態で作られ、注文 ID が返る
  • 注文明細は 2 つで、単価はりんごが 1,080 円、保存容器が 1,650 円
  • 合計は 3,810 円、消費税額は 310 円

購入者が送るのは、商品と数量の組と、連絡先メールアドレスです。システムが返すのは、注文 ID と、注文の状態・注文明細・合計・消費税額・連絡先メールアドレスです。この 2 つが、注文するのリクエストと、注文の表現の中身になります。

中身を並べると、要件に足りないものが 2 つ見つかりました。

  • 注文日時: 注文を確かめるストーリーの目的は、何をいくらで頼んだかを後から見ることです。後から見るなら、いつの注文かも要ります。要件には、注文を受け付けた日時がありませんでした
  • 注文明細の数と重なり: リクエストに並べられる注文明細の数に、上限がありませんでした。同じ商品の注文明細を 2 つ並べてよいかも、決まっていませんでした

どちらも、表現の形を決めるには先に決める必要があります。サンプルリポジトリの要件・モデル・用語集に足しました。

  • 用語集に、注文日時 (code は placedAt) を足した
  • ユースケースの注文するの手順 2 (確かめること) に、注文明細が 100 以下で、同じ商品の注文明細が 2 つ以上無いことを書き足した。手順 6 には注文日時を記録することを、別の流れ 2a にはこの 2 つの誤りを書き足した。注文を確かめるの手順 3 で返すものに、注文日時を足した
  • 受け入れ条件に、同じ商品の注文明細が 2 つあると受け付けない例を足した。受け付けた注文を確かめる例に、受け付けた日時と、返る注文日時を足した
  • ドメインモデルの注文の不変条件に、同じ商品の注文明細は 1 つまでの決まりを足した。作るときの決まりに注文日時を持つことを、クラス図の Order に placedAt を、コンテキストの表の語に注文日時を足した

上限と重なりを決めた理由は、注文明細の数と重なりの節に書きます。

表現は利用者のための形​

表現は、ドメインモデルの集約をそのまま写したものではありません。利用者が使う形として決めます。

ドメインモデルの注文は、合計と消費税額を、注文明細から求めるメソッド (total() と taxAmount()) として持ちます。表現では、どちらも値として返します。消費税額には、税率ごとに割り戻して 1 円未満を切り捨てる決まりがあります。クライアントに計算させると、この決まりをクライアントごとに写すことになります。

Azure の指針は、ほかのフィールドから簡単に計算できる値を、JSON に足さないよう求めています (DO NOT。Azure REST API Guidelines)。本文が大きくなるのを避けるためです。合計は、単価と数量の積の和なので、この規則に当たります。それでも、要件が返すと決めた値なので、表現に入れました。求め方が変わったときに、クライアントの計算を直さずに済みます。一方で、注文明細ごとの単価と数量の積 (小計) は、要件に無いので入れません。

表現に入れないものもあります。

  • 在庫の数量と引き当ての結果。注文の表現は、注文の中身だけを持ちます
  • 商品名と商品の今の価格。リソースの設計の章で決めたとおり、注文明細は商品を商品 ID で指し、注文した時点の単価と税率を持ちます

連絡先メールアドレスは、購入者を特定しうる情報です。1 周目の API には認証が無いので、注文 ID を知っていれば誰でも、その注文を連絡先メールアドレスを含めて読めます。サンプルリポジトリの機能でない要件 (docs/requirements/non-functional.md) に書いたとおり、注文の内容をその注文をした会員だけが読めるようにするのは、第 5 部で認証と認可を入れるときです。

キーの命名​

JSON のキーの書き方は、3 つの指針で分かれます。

指針キーの書き方強さ
Google の AIPprotocol buffers のフィールド名を lower_snake_case で書き (MUST)、JSON では lowerCamelCase に写すフィールド名は MUST。JSON への写し方は ProtoJSON の仕様が決める
Zalando の指針プロパティ名を snake_case にする。camelCase にしないMUST
Azure の指針JSON のフィールド名を camelCase にするDO

AIP-140 は、protocol buffers のフィールド名を lower_snake_case にしなければならないとし (MUST)、その名前は JSON などで、その形式に合う書き方に写されると書いています (AIP-140)。JSON のキーを lowerCamelCase にするのは、protocol buffers の JSON の写し方を定める ProtoJSON の仕様です (ProtoJSON Format)。Zalando の規則 118 は snake_case を求め (MUST)、業界の標準は無いが多くの企業が snake_case を好むこと、JSON を同じ手で書いたようにそろえることを理由に挙げています (規則 118)。Azure の指針は camelCase を求めています (DO。JSON のフィールド名)。

Zalando の指針が書くとおり、どちらかに決まった業界の標準はありません。このガイドは camelCase にし、キーの名前を用語集の code と同じにしました。ドメインを探るの章で、語の code を用語集で 1 つに決めました。リソースの設計の章では、パスの変数 (orderId) にもその code を使いました。キーにも同じ code を使えば、文書・パス・JSON・後で書くコードで、同じ語を 1 つの名前で呼べます。AIP-140 も、同じ概念には同じ名前を使うよう努めるべきとしています (SHOULD。AIP-140)。

配列のキーは、複数形にします (lines)。AIP-140 は繰り返しのフィールドを複数形にしなければならないとし (MUST。AIP-140)、Zalando の規則 120 も配列の名前を複数形にするよう勧めています (SHOULD。規則 120)。

決めたキーを、表にしました。

## キー

1 周目の、注文するのリクエストと、注文の表現に入るキー。場所は、キーが最上位にあるか、どの配列の要素にあるかを表す。

| キー | 場所 | 語 | 型 | 注文するのリクエスト | 注文の表現 |
| --- | --- | --- | --- | --- | --- |
| `orderId` | 最上位 | 注文 ID | 文字列 (UUIDv7) | 入れない | 入れる |
| `status` | 最上位 | 状態 | 文字列 (状態の code) | 入れない | 入れる |
| `placedAt` | 最上位 | 注文日時 | 文字列 (UTC の日時) | 入れない | 入れる |
| `contactEmail` | 最上位 | 連絡先メールアドレス | 文字列 (メールアドレス) | 入れる | 入れる |
| `lines` | 最上位 | 注文明細 | 配列 (1 つ以上) | 入れる | 入れる |
| `productId` | `lines` の要素 | 商品 ID | 文字列 | 入れる | 入れる |
| `quantity` | `lines` の要素 | 数量 | 整数 (1 以上) | 入れる | 入れる |
| `unitPrice` | `lines` の要素 | 単価 | 整数 (円) | 入れない | 入れる |
| `taxRate` | `lines` の要素 | 税率 | 整数 (8 か 10) | 入れない | 入れる |
| `total` | 最上位 | 合計 | 整数 (円) | 入れない | 入れる |
| `taxAmount` | 最上位 | 消費税額 | 整数 (円) | 入れない | 入れる |

- キーは camelCase にし、語の用語集 (`docs/glossary.yaml`) の code と同じ名前にする
- 配列のキーは、要素の語の複数形の英語にする (`lines`)

注文 ID のキーは、id でなく orderId にしました。パスの変数と用語集の code に、同じ名前を使うためです。

ID を文字列で持つ​

注文 ID と商品 ID は、JSON の数値でなく文字列で持ちます。

Zalando の規則 144 は、識別子にはいつも数値でなく文字列の型を使うべきとし、理由を識別子の付け方を後から変えやすいことに置いています (規則 144)。数値には、もう 1 つ問題があります。JSON の仕様は、受け付ける数値の範囲と精度を実装が制限することを許しています。そのうえで、IEEE 754 の倍精度の数を使う実装どうしなら、-(2^53)+1 から (2^53)-1 までの整数は値が正確に一致する、と書いています (RFC 8259 の 6 節)。I-JSON (RFC 7493) は、それより大きい整数を正確にやり取りするなら、文字列にすることを勧めています (RECOMMENDED。RFC 7493 の 2.2 節)。

注文 ID は UUIDv7 にする​

注文 ID は、リソースの設計の章で決めたとおりサーバーが作ります。このガイドは、注文 ID を UUIDv7 にしました。

UUID を定める今の RFC は RFC 9562 で、以前の RFC 4122 を廃止しています (RFC 9562)。UUIDv7 は、先頭の 48 ビットに Unix 時刻のミリ秒を置き、version と variant を除く残りの 74 ビットを乱数などで埋めます (RFC 9562 の 5.7 節)。RFC 9562 は、できるなら UUIDv1 や UUIDv6 の代わりに UUIDv7 を使うべきとしています (SHOULD)。

UUIDv7 を選んだ理由は 2 つです。

  • 作った順に並ぶ。RFC 9562 は、改訂の動機の 1 つに、作った順に並ばない UUID (UUIDv4 など) の索引の問題を挙げています。データベースの索引に使うと、続けて作った値が索引のばらばらの位置に入り、局所性が悪くなります (RFC 9562 の 2.1 節)
  • 連番の数で、注文の数を明かさない。Zalando の規則 144 は、連番で単調に増える数値の識別子は、注文の量のような業務の情報を権限の無いクライアントに明かしうると注意しています

Zalando の規則 144 の題は、UUID は必要なときだけ使う (SHOULD) です。UUID の利点には、調整なしに衝突せず作れることを挙げ、大規模な ID の生成に要らないなら避けるべきとしています。欠点には、人が覚えにくく消費者に見せる使い方では扱いにくいことや 36 文字と長いこと、作った順に並ばないことなどを挙げています。

このガイドの注文 ID は、大規模な生成のために UUID を選んだのではないので、規則 144 の勧めからは外れます。それでも UUIDv7 にしたのは、上の 2 つの理由からです。作った順に並ばない欠点は、UUIDv7 には当たりません。人が覚えにくいことと長さは、欠点として残ります。購入者が注文 ID を口頭で伝えたり手で打ったりする場面が要件に入ったら、人が扱う番号を別に持つかを考えます。

RFC 9562 は、UUID を推測しにくいものと仮定すべきでなく (SHOULD NOT)、持っているだけでアクセスできる印 (security capability) として使ってはならないとしています (MUST NOT。RFC 9562 の 8 節)。1 周目の API は、注文 ID を知っていれば誰でも注文を読める形なので、この使い方に当たります。8 節は、アプリケーションのセキュリティの操作に UUID を使うなら UUIDv4 を使うべきともしています (SHOULD)。UUIDv4 は乱数から作り、時刻を持たないので (RFC 9562 の 5.4 節)、ID から作った時刻や順を読み取られません。一方で、8 節は、UUID に入れた時刻が作る攻撃面はごく小さく (very small)、時刻は (カウンタと合わせて) 作った順を示すが、データそのものやアプリケーション全体 (as a whole) については何も示さないとしています。

このガイドは、注文 ID を UUIDv7 のままにしました。そのため、UUID をセキュリティの操作に使うなら UUIDv4 を使うべきという 8 節の SHOULD からは外れます。1 周目の API は、注文 ID を知っていれば注文を読める形で、注文 ID をこの用途に使っています。この使い方の問題は、UUIDv4 にしても解けません。第 5 部で、注文を読める人を認可で限ります。そのあとも、注文 ID だけを見た人は、作った時刻をミリ秒まで読めます。この小さな攻撃面と引き換えに、作った順に並ぶ利点を取りました。

RFC 9562 は、UUID の値を不必要に解析せず、中身の見えない値として扱うことも勧めています (RFC 9562 の 6.12 節)。クライアントは、注文 ID から時刻を読み取らずに、文字列のまま使います。注文の日時が要るなら、注文日時のキーを読みます。

RFC 9562 は、UUID の英字を大文字・小文字・混在のどれで書いてもよいとしています (RFC 9562 の 4 節)。このガイドは、サーバーが返す注文 ID の英字を小文字にそろえました。クライアントが注文 ID を文字列のまま比べても、同じ注文が同じ文字列になるようにするためです。

Zalando の規則 144 は、識別子に使う UUID には、スキーマの format を付けるべきでないとしています。数値でなく文字列にするのと同じく、識別子の付け方を後から変えやすくするためです。このガイドのテストは、例の注文 ID が小文字の UUIDv7 の形かを確かめます。API の仕様で注文 ID に format を付けるかは、この部の後半で OpenAPI の仕様を書くときに決めます。

商品 ID の形は、商品の API と一緒に決める​

商品 ID も文字列で持ちます。形 (UUIDv7 にするか、別の形にするか) は、商品の API を足す第 4 部で決めます。Zalando の規則 144 は、ID の数が少ないマスタデータの主キーに UUID を使うことを、とくに避けるよう勧めています。商品は注文より数が少なく、注文で UUIDv7 を選んだ理由 (連番では注文の数が分かる) も当たらないので、商品の API を設計するときに比べます。

1 周目の例では、商品 ID に UUIDv7 の形の値を仮に使います。クライアントは商品 ID の中身も読まずに文字列のまま使うので、形を後で決めても、クライアントの扱い方は変わりません。

金額を円の整数で持つ​

単価・合計・消費税額は、円の整数 (JSON の数値) で持ちます。通貨を表すキーは持ちません。

円の金額には、小数の単位がありません。SIX は、自らを ISO 4217 の通貨コードの維持管理機関としています (SIX のデータ標準)。SIX が公開する通貨の一覧では、円 (JPY) の補助単位の桁数は 0 です (List One)。円の金額は整数で正確に表せます。金額が 2 の 53 乗より小さいうちは、JSON の数値のまま正確にやり取りできます。整数の範囲を API の仕様にどう書くかは、この部の後半で OpenAPI の仕様を書くときに決めます。

ほかの指針は、金額を通貨と組にしています。

  • Zalando の規則 173 は、金額を通貨と組にした共通の Money の形を使わなければならないとしています (MUST)。金額の amount は小数を表す数で、currency は ISO 4217 の通貨コードです。浮動小数点数に変えると精度を失うので、Java の BigDecimal のような型で扱うよう求めています (規則 173)
  • Google の共通の型の Money は、通貨コード (currency_code) と、金額の整数部分 (units) と、10 億分の 1 の単位の端数 (nanos) を持ちます (money.proto)。AIP-143 は、通貨を表すフィールドには ISO 4217 の通貨コードを使わなければならないとしています (MUST。AIP-143)

このガイドの注文の API は、円だけを扱います。用語集でも、金額を「円の整数で表したお金の額」と決めています。通貨のキーを持たないので、AIP-143 の通貨のフィールドの決まりは当たりません。ほかの通貨を扱うことになったら、金額の形を通貨と組にするかを見直します。

税率は、百分率の整数 (8 か 10) で持ちます。ドメインモデルの章の消費税額の計算例と同じ書き方です。

日時を RFC 3339 の UTC で持つ​

注文日時 (placedAt) は、RFC 3339 の形の UTC の文字列で持ちます。末尾を Z にし、秒の小数を 3 桁 (ミリ秒) にそろえます (2026-11-01T01:23:45.678Z)。

RFC 3339 は、インターネットのプロトコルで使う日時の形を定めています。T と Z は小文字でも読めますが、生成する側は大文字を使うべきとしています (SHOULD。RFC 3339 の 5.6 節)。I-JSON は、日時を RFC 3339 の文字列で表すことを勧め (RECOMMENDED)、大文字を使うこと、タイムゾーンを省かないこと、秒が 0 でも省かないことを加えています (RFC 7493 の 4.3 節)。Zalando の規則 169 は RFC 3339 の形を求め (MUST)、+00:00 のようなオフセットを付けずに Z で書くことを勧めています (規則 169)。Azure の指針も、日時に RFC 3339 を使うよう求めています (DO。日時)。

Z の意味は、RFC 9557 で改められました。今の Z は、UTC の時刻は分かるが、現地の時刻へのオフセットは分からない、という意味です (RFC 9557 の 2.2 節)。サーバーは購入者がどのタイムゾーンにいるかを知らないので、この意味に合います。購入者の地域の時刻で表示するのは、クライアントの仕事です。

秒の小数の桁をそろえるのは、文字列のまま並べ替えられるようにするためです。RFC 3339 は、同じタイムゾーンで同じ形に書き、秒の小数の桁数がそろっていれば、文字列として並べた順が時刻の順になるとしています (RFC 3339 の 5.1 節)。

日時のキーの名前の付け方も、指針で分かれます。

  • AIP-142 は、時点を表すフィールドの名前を _time で終え (SHOULD)、出来事の時刻は publish_time のように動詞の原形から作り、published_time のような過去形にしないよう求めています (SHOULD NOT。AIP-142)
  • Zalando の規則 235 は、日付と日時のプロパティの名前に date・time などの語を含めるか、_at で終えるよう勧めています (SHOULD。規則 235)

このガイドは、注文するの code (place) の過去分詞と At を組み合わせた placedAt にしました。Zalando の規則 235 の _at の形を camelCase で書いたものです。AIP-142 の形なら placeTime になり、placedAt は AIP-142 の勧めから外れます。注文が受け付けられた時点を指すことは、過去分詞と At の組のほうが読み取りやすいと判断しました。

状態を文字列の列挙で持つ​

状態 (status) は、用語集の状態の code の文字列で持ちます。1 周目の状態は受付 (PENDING) だけです。

Zalando の規則 240 は、列挙の値を YET_ANOTHER_VALUE のような大文字のスネークケースで書くよう勧めています (SHOULD。規則 240)。AIP-126 は、protocol buffers の列挙の値を大文字のスネークケースで書かなければならないとしています (MUST。AIP-126)。ただし、値がよく変わる列挙的な値には、列挙の代わりに文字列のフィールドを使うよう勧めています (SHOULD)。そのうえで、列挙的な値を持つ文字列のフィールドは、値を kebab-case で書くよう勧めています (SHOULD。AIP-126)。このガイドは、状態の値を用語集の code と同じ文字列 (PENDING) にしました。状態を文字列のフィールドで持つので、列挙的な値を持つ文字列のフィールドの値は kebab-case にするという AIP-126 の勧めからは外れます。

状態の値は、後の周回で増えます。第 4 部で、注文の取り消しを足すと、取消の状態が加わります。Zalando の規則 112 は、JSON Schema の enum は定義のうえで閉じた集合なので、値を足すと互換性の無い変更になると書いています (規則 112)。そのうえで、値を足しうる列挙は開いた値の並びとして書くよう勧め (SHOULD)、クライアントは一覧に無い値に備えなければならないとしています (MUST)。Azure の指針も、値が将来変わらないと確信できる場合を除き、拡張できる列挙を使うよう勧めています (YOU SHOULD。拡張できる列挙)。

このガイドは、状態の値が増えることを表現の決まりに書き、クライアントは知らない値を受け取っても止まらないようにすることを、利用者への約束にしました。API の仕様の中で、状態の値をどう書くか (閉じた enum にするか、開いた並びにするか) は、この部の後半で OpenAPI の仕様を書くときに決めます。

null と省略​

値が無いことを表す書き方は 2 つあります。キーを省くことと、値を null にすることです。このガイドは、1 周目の表現とリクエストで null を使わず、値が無いことはキーを省いて表します。

  • Zalando の規則 123 は、必須でなく null を許すプロパティについて、キーが無い場合と null の場合をまったく同じに扱わなければならないとしています (MUST)。2 つに別の意味を持たせると、クライアントが違いを誤って実装するおそれが大きいからです (規則 123)
  • Azure の指針は、サービスからクライアントへ、値が null のフィールドを送らず、フィールドごと送らないよう求めています (DO NOT。null の値)
  • Zalando の規則 124 は、空の配列を null でなく [] で表すよう勧めています (SHOULD。規則 124)

1 周目の注文の表現は、どのキーもいつも持つので、省くキーはありません。注文明細の配列は、1 つ以上の要素をいつも持ちます。

Zalando の規則 123 には、唯一の例外があります。JSON Merge Patch (RFC 7396) では、null がプロパティを消すことを、プロパティが無いことが変えないことを表します。注文を変える操作を足す第 4 部で、更新の形を比べるときに、null に意味を持たせるかを一緒に決めます。

既定値​

1 周目の注文するのリクエストには、省いてよいキーがありません。そのため、省いたときに使う値 (既定値) もありません。

後の周回で省いてよいキーを足すときは、省いたときの値をサーバーが補い、補った値を応答に入れます。Azure の指針は、作成や取得の後に、リソースの状態を応答で返すよう求めています (DO。リソースの状態を返す)。補った値が応答にあれば、クライアントはサーバーが何を補ったかを読めます。

API の仕様のスキーマに既定値を書くことと、値を補うことは別のことです。JSON Schema は、キーワードのふるまいをいくつかの種類に分けています。その中に、インスタンスが制約を満たすかの真偽を出す表明 (assertion) と、アプリケーションが自由に使える情報を付ける注釈 (annotation) があります (JSON Schema Core 2020-12 の 7 節)。default は、文書化と画面の表示のための注釈のキーワードの 1 つです (JSON Schema Validation 2020-12 の 9 節)。仕様は、検証の実装がアプリケーションに代わって注釈を使うことを期待していません (JSON Schema Core 2020-12 の 7.7 節)。このガイドは、スキーマの既定値に頼らず、値を補うことをサーバーのコードに書きます。

エンベロープで包むか​

応答の本文を {"data": {...}} のような入れ物 (エンベロープ) で包むかを決めます。このガイドは、1 つのリソースを返す 1 周目の応答を包まず、最上位を注文の表現のオブジェクトにしました。

  • AIP-131 は、取得のメソッドの応答をリソースそのものにしなければならないとしています (MUST。AIP-131)
  • Zalando の規則 110 は、応答の本文の最上位を、配列でなく JSON のオブジェクトにしなければならないとしています (MUST)。オブジェクトなら、後から属性を足しても互換を保てるからです (規則 110)
  • I-JSON は、プロトコルの設計者に、オブジェクトと配列のほかの値を最上位に使わないよう求めています (SHOULD NOT。RFC 7493 の 4.1 節)

1 周目の応答には、リソースの横に並べて返すもの (一覧の続きの位置など) がありません。最上位がオブジェクトなら、後からキーを足せます。一覧を返す操作の形は、一覧を足す第 4 部で決めます。

注文するの応答 (201) と、注文を確かめるの応答 (200) は、どちらも注文の表現を本文で返します。Zalando の規則 148 は、1 つのリソースを作る POST の応答で、201 と、識別子を含む新しいリソースを本文で返すよう勧めています (SHOULD。規則 148)。

リクエストとレスポンスで形を分ける​

注文するのリクエストは、注文の表現と別の形にしました。リクエストに入るのは、連絡先メールアドレスと、商品 ID と数量の組だけです。単価・税率・合計・消費税額・注文 ID・状態・注文日時は、サーバーが決めます。単価は、注文を受け付けた時点の商品の価格を、サーバーが写します。

読みと書きで 1 つの形を使う考え方もあります。

  • Zalando の規則 252 は、同じリソースの読みと書きに共通の形を使い、応答にだけあるプロパティに readOnly を付けるよう勧めています (SHOULD。規則 252)。readOnly のプロパティがリクエストで来たときは、サーバーが無視することも断ることも認めています
  • Azure の指針は、同じパスの POST のリクエストと応答に、同じ JSON の形を使うよう求めています (DO。同じ形を使う)。読み取り専用のフィールドが送られたときの扱いは、2 つの表で書き方が違います。フィールドの可変性の表は、値が今の値と一致しない限り失敗させなければならないとしています (MUST。フィールドの可変性)。PATCH と PUT の処理の表は、例外なく 400 にするとしています (ステータスコード)
  • AIP-203 は、応答にだけ入るフィールド (OUTPUT_ONLY) の値がリクエストに入っていたら、サーバーはその値を消さなければならず、そのためにエラーを返してはならないとしています (MUST・MUST NOT。AIP-203)

指針によって、リクエストに入った単価を無視するか断るかが分かれます。このガイドは形を分け、リクエストの形に無いキーは受け付けないことにしました。購入者のクライアントが単価を送ると、サーバーは注文を受け付けずに誤りを返します。

Zalando の規則 109 も、ペイロードの知らない入力のフィールドを無視せず、400 で誤りを返すよう勧めています (SHOULD。規則 109)。Azure の指針も、その版が理解しない JSON のフィールド名があれば 400 で失敗させるよう求めています (DO。400 で失敗させる)。誤りの応答の形とステータスコードは、次の章で決めます。

応答の向きは逆です。クライアントは、応答に知らないキーがあっても無視します。Zalando の規則 111 は、データを受け取るクライアントは、処理できないフィールドを無視しなければならないとしています (MUST。規則 111)。I-JSON も、知らない要素を無視する方針 (Must-Ignore) が、新しい要素を既存のソフトウェアを乱さずに足せる点で有利だったと書いています (RFC 7493 の 4.2 節)。サーバーは、後の周回で応答にキーを足します。

同じ規則 111 は、API の形式で additionalProperties を false にしてはならないともしています (MUST NOT)。オブジェクトを後から広げられなくなるからです。Zalando の指針は、知らない入力をサーバーが断ること (規則 109) と、API の形式を閉じないこと (規則 111) を並べています。このガイドの「知らないキーを受け付けない」も、サーバーの確かめとして決めたものです。API の仕様のスキーマにどう書くか (オブジェクトを閉じるか、閉じずにサーバーが確かめるか) は、この部の後半で OpenAPI の仕様を書くときに決めます。

決めた形を、表現の決まりに書きました。

## 形

1 周目の 2 つの操作 (注文する・注文を確かめる) に当てた決まり。一覧を返す操作の形は、一覧を足す周回で決める。

- 1 つのリソースを返す応答は、最上位を JSON のオブジェクトにし、包まずにそのまま返す
- 注文するの成功の応答 (201) と、注文を確かめるの成功の応答 (200) は、どちらも注文の表現を返す
- 注文するのリクエストは、注文の表現と別の形にする。サーバーが決める値 (注文 ID・状態・注文日時・単価・税率・合計・消費税額) は、リクエストに入れない
- リクエストに、上の表で注文するのリクエストに「入れる」としたキーのほかのキー (表の場所と違う場所にあるキーを含む) があれば、注文を受け付けない
- クライアントは、応答に知らないキーがあっても無視する。サーバーは、後の周回で応答にキーを足す
- 1 周目のリクエストには、省いてよいキーが無い。後の周回で省いてよいキーを足すときは、省いたときの値をサーバーが補い、補った値を応答に入れる
- 注文明細は 100 以下で、同じ商品の注文明細は 1 つまで (要件は `docs/requirements/use-cases.md` の注文する)

注文明細の数と重なり​

注文明細の数は、1 つ以上 100 以下にしました。

AIP-144 は、配列のフィールドに、リソースの中身が大きくなりすぎない上限を設けるよう勧め、目安を 100 要素としています (SHOULD。AIP-144)。上限を超えたときにどう返すかは、AIP-144 には書かれていません。Zalando の規則 109 は、入力の形式・範囲・長さの制約を正確に定め、違反には誤りを返すよう勧めています (SHOULD)。上限の 100 は AIP-144 の目安に合わせました。1 回の注文で 100 種類を超える商品を頼む要件は、1 周目にはありません。

この上限は、リソースの大きさを抑えるための決まりです。業務の決まりではないので、ドメインモデルの不変条件には入れず、ユースケースの手順 2 と表現の決まりに書きました。受け入れ条件の例にもしていません。受け入れ条件の前提の商品は 2 つなので、100 個と 101 個の境目を、登録された商品で書けないためです。境目は、この部の後半で書く API の仕様 (配列の要素の数の上限) と、第 2 部の実装のテストで確かめます。

同じ商品の注文明細は、1 つまでにしました。同じ商品を 2 つの注文明細に分けて頼まれると、ユースケースの手順 4 (どの商品も在庫が数量以上あることを確かめる) が明細ごとの確かめになり、足りるように見えてしまいます。在庫が 10 のりんごを、6 個と 6 個の 2 つの注文明細で頼むと、どちらの明細も 10 以下なので手順 4 を通り、引き当てで合わせた 12 個が足りなくなります。同じ商品をまとめて 1 つの注文明細にすれば、手順 4 の確かめのままで足ります。この決まりは注文の不変条件にし、受け入れ条件の例も足しました。

JSON Schema の uniqueItems は、true にすると、配列の要素がどの 2 つも等しくないときに通るキーワードです (JSON Schema Validation 2020-12 の 6.4.3 節)。オブジェクトどうしは、すべてのプロパティのキーと値が等しいときに等しいとされます (JSON Schema Core 2020-12 の 4.2.2 節)。そのため、商品 ID だけが同じで数量が違う 2 つの注文明細は、uniqueItems では断れません。この決まりを API の仕様とモックでどこまで確かめられるかは、この部の後半の仕様とモックの章で扱います。

メディアタイプ​

HTTP のメッセージの章で、Content-Type は本文の形式を、Accept はクライアントが受け取れる形式を伝えると書きました。1 周目の 2 つの操作での扱いを決めます。後で比べて決める 3 つ (下の決まりの冒頭) は、それぞれ商品の画像を受け取る第 6 部、注文を変える第 4 部、API の版を扱う第 7 部で決めます。

## メディアタイプ

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 を返す。`Accept` が無ければ、`application/json` で返す
- 誤りの応答のメディアタイプと `Accept` の関係は、誤りの返し方と一緒に決める

HTTP の仕様は、415 (Unsupported Media Type) を、リクエストの本文がそのメソッドで扱えない形式なので処理を断ることを示すステータスコードとしています。原因がメディアタイプなら、応答の Accept ヘッダで、どのメディアタイプなら受け付けたかを示せます (RFC 9110 の 15.5.16)。メディアタイプの type と subtype は大文字小文字を区別しないので (RFC 9110 の 8.3.1)、Application/JSON も application/json として受け付けます。パラメータを見ずに比べるのは、このガイドの決めです。application/json には charset のパラメータが定められていないので (下の RFC 8259 の 11 節)、application/json; charset=utf-8 も受け付けます。

Accept に合う表現が無いとき、オリジンサーバーが取れる道は 2 つです。406 (Not Acceptable) を返してヘッダに従うか、ヘッダを無視して交渉の対象でないかのように応答するかです (RFC 9110 の 12.4.1)。このガイドは 406 を返すことにしました。JSON を受け取れないと伝えたクライアントに JSON を返しても、クライアントは読めません。406 なら、形式が合わないことをステータスコードで伝えられます。Zalando の規則 150 も、406 と 415 を、使うステータスコードの一覧に入れています (規則 150)。Accept が無いリクエストは、形式に希望が無いことを意味します (RFC 9110 の 12.4.1)。

application/json のメディアタイプには、charset のパラメータが定められておらず、付けても、仕様に従う受け手には何の効果もありません (RFC 8259 の 11 節)。JSON は UTF-8 で符号化します。

誤りの応答は、問題の詳細の形 (application/problem+json) で返す予定です。Accept: application/json だけを送ったクライアントに誤りを返すときの扱いは、次の章で誤りの返し方と一緒に決めます。モックがこの決まりのとおりに振る舞うかは、モックの章で確かめます。

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

決めた形を、受け入れ条件の注文を例にして、JSON のファイルに残しました。注文するのリクエストの例です。

{
"contactEmail": "taro.test@example.com",
"lines": [
{ "productId": "01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34", "quantity": 2 },
{ "productId": "01a0f4c2-c7e8-7b22-a963-4dae1f203b45", "quantity": 1 }
]
}

1 つ目の注文明細がりんご、2 つ目が保存容器です。注文の表現の例は、注文するの応答と、注文を確かめるの応答の両方の本文です。

{
"orderId": "01a194b4-978e-7c3a-9f21-6d4b8e2a1c05",
"status": "PENDING",
"placedAt": "2026-11-01T01:23:45.678Z",
"contactEmail": "taro.test@example.com",
"lines": [
{ "productId": "01a0f4c2-c400-7a11-8b52-3c9d0e1f2a34", "quantity": 2, "unitPrice": 1080, "taxRate": 8 },
{ "productId": "01a0f4c2-c7e8-7b22-a963-4dae1f203b45", "quantity": 1, "unitPrice": 1650, "taxRate": 10 }
],
"total": 3810,
"taxAmount": 310
}

例の注文 ID は、注文日時のミリ秒の Unix 時刻を 16 進数で書いた 12 桁 (01a194b4978e) から始めて作りました。3 つ目の組の先頭の 7 が version です。4 つ目の組の先頭の 9 は 2 進数で 1001 で、上の 2 ビット (10) が variant です。商品 ID も、同じ作り方で、2026 年 10 月 1 日の時刻から作りました。

この例は、この部の後半で OpenAPI の仕様の例に入れ、モックが返す応答にも使います。この章で足したテスト (test/representation.test.ts) は、次のことを確かめます。

  • examples/orders/ の例は、どれも JSON として読め、最上位がオブジェクト
  • 表現の決まりのキーの表の行はどれも決めた形で書かれ、語は用語集にあり、配列でないキーは、その語の用語集の code と同じ。場所は、最上位か、最上位の配列のキーの要素
  • 例は、キーの表でその例の列に「入れる」としたキーを、その場所ごとにちょうど持つ (注文明細なら、要素の 1 つずつが同じキーを持つ)
  • 例の値は、キーの表の型に合う (注文 ID は小文字の UUIDv7、日時は末尾が Z で秒の小数が 3 桁、金額は 0 以上の整数、税率は 8 か 10 など)
  • 例に null が無い (配列の要素も含めて)
  • 例の注文明細は 100 以下で、同じ商品の注文明細が 2 つ以上無い
  • 注文の例は、リクエストの例と同じ注文を表し、金額はドメインモデルの計算例と同じ

キーの表に新しい型を書いたのに、テストにその型の確かめ方を足し忘れると、4 つ目のテストで落ちます。注文の例の金額を、ドメインモデルの計算例と違う値に書き換えると、7 つ目のテストで落ちます。7 つ目のテストは、注文明細の商品 ID・単価・数量・税率も、計算例の 1 つ目の例と比べます。計算例の商品 ID は、ここで注文の例の商品 ID と結ばれます。キーの表の行は、書いた形のまま正規表現で拾います。区切りの | の前後の空白を詰めたり、場所を「lines の中」のように書いたりすると、その行は拾われません。そういう行は、2 つ目のテストが形の合わない行として落とします。ただし、6 つ目のテストは、注文明細の配列のキー (lines)・商品 ID のキー (productId)・上限の 100 を、表や文書から読まずにコードに書いています。7 つ目のテストも、比べるキーをコードに書いています。コードは章末の「この章のテストのコード」にあります。

見直しの観点​

表現を決めたら、次の観点で見直します。

  • 受け入れ条件の値を、表現の例で表せるか
  • キーの名前は、用語集の code と同じか。配列のキーは複数形か
  • キーが、表に書いた場所 (最上位か配列の要素か) にあるか
  • ID は文字列か。クライアントが ID の中身を読む前提になっていないか
  • 金額は、正確に表せる型か (円なら整数)
  • 日時は、RFC 3339 の UTC で、同じ形にそろっているか
  • 状態の値が増えることを、利用者に伝えているか
  • 1 周目の表現とリクエストで、null を使っていないか
  • サーバーが決める値を、リクエストで受け取る形になっていないか
  • 表現に、ドメインモデルの中身や、ほかの集約の中身をそのまま写していないか

選ばなかった案​

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

## 選ばなかった案

| 案 | 選ばなかった理由 |
| --- | --- |
| キーを snake_case にする (`unit_price`) | 文書・パスの変数・テスト・後で書くコードで、同じ語を用語集の code の 1 つの名前で呼ぶ |
| 注文のキーを `id` にする | パスの変数 (`orderId`) と用語集の code に、同じ名前を使う |
| 注文日時のキーを `placeTime` にする | 受け付けた時点を指すことは、過去分詞と `At` の組 (`placedAt`) のほうが読み取りやすい |
| 状態の値を小文字の kebab-case にする (`pending`) | 用語集の code (`PENDING`) と同じ文字列にする |
| 注文 ID を、連番の整数にする | 権限の無いクライアントにも、注文の数が分かる。数値の ID は、形を後から変えにくい |
| 注文 ID を UUIDv4 にする | 時刻を持たないので、ID から作った時刻を読み取られない利点はある。作った順に並ばないので、データベースの索引に足す位置がばらばらになる |
| 金額を、通貨のコードと金額の組にする | 1 周目は円だけを扱う。円は補助単位が無いので、整数で正確に表せる。通貨が増えたら見直す |
| 金額を、小数か文字列にする | 円は整数で足りる。2 の 53 乗より小さい整数は、JSON の数値のまま正確に運べる |
| 日時に `+09:00` のようなオフセットを付ける | すべて UTC で同じ形に書けば、文字列のまま並べ替えても時刻の順になる |
| 応答を `{"data": ...}` のように包む | 1 周目の応答には、リソースの横に置くものが無い。最上位をオブジェクトにしておけば、後からキーを足せる |
| リクエストと表現を 1 つの形にし、サーバーが決めるキーに読み取り専用の印を付ける | リクエストに入った単価を、無視するか断るかが分かれる。別の形にして、知らないキーとして断る |
| 1 周目の表現とリクエストで、null で値が無いことを表す | 値が無いことの書き方が 2 通りになり、クライアントが別の意味に取りうる |

実務で効く注意点​

JavaScript のクライアントは、大きな整数を正確に読めない​

JavaScript の JSON.parse は、JSON の数値を Number にします (ECMAScript の JSON.parse)。Number は IEEE 754 の倍精度の数です。ECMAScript の仕様は、Number の値がほかのどの整数とも重ならない整数を安全な整数と呼びます。その最大が Number.MAX_SAFE_INTEGER (9007199254740991、2 の 53 乗から 1 を引いた数) です (Number.MAX_SAFE_INTEGER)。これより大きい整数の Number の値は、少なくとも 1 つの別の整数と同じになり、2 つを区別できません。

64 ビットの整数の ID を JSON の数値で返すと、JavaScript のクライアントでは下の桁が変わることがあります。I-JSON が、大きな整数を文字列で運ぶよう勧める例に挙げているのも、64 ビットの整数です。ID を文字列にしておけば、この問題は起きません。

状態の知らない値で、クライアントを止めない​

状態の値を、クライアントのコードで閉じた列挙型 (TypeScript の文字列リテラルの合併型や Java の enum など) に写したとします。サーバーが値を足すと、クライアントは知らない値を受け取って失敗します。Zalando の規則 108 は、クライアントが知らない列挙の値に頼らないか、既定の振る舞いを用意しなければならないとしています (MUST。規則 108)。知らない状態を受け取ったら、「その他」として表示するなどの扱いを、クライアントの側で決めておきます。

まとめ​

  • 表現は、受け入れ条件の値から決めます。要件に足りなかった注文日時と、注文明細の数 (100 以下) と重なり (同じ商品は 1 つまで) の決まりを足しました
  • キーは camelCase にし、用語集の code と同じ名前にします。配列のキーは複数形にします
  • ID は文字列で持ちます。注文 ID は、作った順に並ぶ UUIDv7 にしました。商品 ID の形は、商品の API と一緒に決めます
  • 金額は円の整数、税率は百分率の整数で持ちます。日時は RFC 3339 の UTC で、末尾を Z、秒の小数を 3 桁にそろえます
  • 状態は、用語集の code の文字列で持ちます。値が増えるので、クライアントは知らない値で止まらないようにします
  • 1 周目は null を使わず、値が無いことはキーを省いて表します。1 つのリソースを返す応答は包まず、最上位を注文のオブジェクトにします
  • 注文するのリクエストは、注文の表現と別の形にし、知らないキーは受け付けません。クライアントは、応答の知らないキーを無視します
  • 1 周目のリクエストと成功の応答の本文は application/json です。ほかの形式の本文には 415、JSON を受け取れないクライアントには 406 を返します。JSON でない本文や差分のメディアタイプは、それを扱う部で決めます

次に読む​

前の章は リソースの設計 です。

次章 エラーの設計 では、注文の作成と取得で起きる失敗を並べ、ステータスコードと、誤りの応答の形 (問題の詳細) を決めます。

練習問題​

1 周目の注文の表現に、商品名を入れてほしいという要望が来ました。どう考えますか

解答例

注文明細に商品名を入れると、どの時点の商品名かを決める必要があります。

単価と同じように、注文した時点の商品名を注文明細に写すなら、それは今の商品名 (用語集の商品名、code は name) とは別の語になります。用語集に新しい語と code を足し、ドメインモデルの注文明細と要件にも書きます。そのうえで、表現のキーの表に、lines の要素のキーとして行を足します。例の注文明細のどれかにそのキーが無いか、キーの名前が用語集の code と違えば、テストが落ちます。

今の商品名を読ませたいなら、注文の表現には足さず、第 4 部で足す商品の API で読ませます。クライアントは、注文明細の商品 ID から商品を引きます。

注文の合計を、ドルでも返したいという要望が来ました。金額の形はどう変わりますか

解答例

金額に通貨を持たせる必要が出ます。今の total は円の整数で、通貨のキーがありません。ドルにはセントの補助単位 (2 桁) があるので、整数のまま「ドル」で持つと端数を表せません。

金額の形には、通貨コードと組にする形があります。Zalando の Money (小数の amount と currency) や、Google の Money (currency_code・units・nanos) が例です。補助単位の整数 (セントなど) と通貨コードを組にする形もあります。

変え方は 2 通りです。今の total を円の整数のまま残し、ドルの合計を通貨と組にした別のキーで足すなら、クライアントは知らないキーを無視するので、今のクライアントは壊れません。total の形そのものを通貨と組にした形に変えるなら、total を読む今のクライアントが壊れます。どちらにするかは、互換な変更と互換でない変更を扱う第 7 部の事柄です。

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

注文の表現の例が、表現の決まりのキーの表と値の形と注文明細の決まりに合い、ドメインモデルの計算例と同じ金額を持つことを確かめるテストのコードです。読まなくても本文は追えます。

/*
* 注文の表現の例 (examples/orders/) が、表現の決まり (docs/api-design/representation.md) のキーの表と値の形と注文明細の決まりに合い、
* ドメインモデルの計算例と同じ金額を持つことを確かめる。例は API の仕様の例やモックの応答に写すので、決まりに合わない例を写すと、
* その形が API の形として伝わるため。
*/
import { readdirSync, readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { expect, it } from 'vitest';
import { parse } from 'yaml';

interface KeyRow {
key: string;
place: string;
term: string;
type: string;
inRequest: boolean;
inOrder: boolean;
}

type Column = 'inRequest' | 'inOrder';

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);
}

/** 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 representation = read('docs/api-design/representation.md');
const glossary: unknown = parse(read('docs/glossary.yaml'));
const taxCalculation: unknown = JSON.parse(read('examples/domain/tax-calculation.json'));
const exampleFiles = readdirSync(fileURLToPath(new URL('../examples/orders/', import.meta.url))).filter((name) => name.endsWith('.json'));
const parsed = new Map(exampleFiles.map((name) => [name, parseJson(read(`examples/orders/${name}`))]));
const examples = new Map([...parsed].map(([name, result]) => [name, result.value]));

/** 例のファイルと、キーの表でその例に入るキーを決める列。examples/orders/ に例を足したら、ここにも足す。 */
const columns: Record<string, Column> = {
'place-order-request.json': 'inRequest',
'order.json': 'inOrder',
};

const header = '| キー | 場所 | 語 | 型 | 注文するのリクエスト | 注文の表現 |';
/** キーの表の 1 行。場所の列は「最上位」か「`配列のキー` の要素」で、配列のキーを 2 つ目の組で拾う。 */
const rowPattern = /^\| `([^`]+)` \| (?:最上位|`([^`]+)` の要素) \| ([^|]+) \| ([^|]+) \| (入れる|入れない) \| (入れる|入れない) \|$/;

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

/** キーの表の行。place には、最上位のキーなら空文字列を、配列の要素のキーならその配列のキーを入れる。 */
const rows: KeyRow[] = keyTableLines().flatMap((line) => {
const match = rowPattern.exec(line);
if (match === null) return [];
return [{ key: match[1], place: match[2] ?? '', term: match[3], type: match[4], inRequest: match[5] === '入れる', inOrder: match[6] === '入れる' }];
});

const terms = isRecord(glossary) && Array.isArray(glossary.terms) ? glossary.terms.filter(isRecord) : [];
const codeByName = new Map(terms.map((term) => [term.name, term.code]));
const codes = terms.flatMap((term) => (typeof term.code === 'string' ? [term.code] : []));

/**
* キーの表の型ごとの確かめ方。表に、ここに無い型を書いたら、確かめ方が無いことを誤りとして返す
* (型を足したのに確かめ方を足し忘れると、その型の値が何も確かめずに通るため)。
*/
const typeChecks: Record<string, (value: unknown) => boolean> = {
'文字列': (value) => typeof value === 'string' && value !== '',
'文字列 (UUIDv7)': (value) => typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value),
'文字列 (UTC の日時)': (value) =>
typeof value === 'string' &&
/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value) &&
!Number.isNaN(Date.parse(value)) &&
new Date(value).toISOString() === value,
'文字列 (状態の code)': (value) => typeof value === 'string' && /^[A-Z][A-Z0-9_]*$/.test(value) && codes.includes(value),
'文字列 (メールアドレス)': (value) => typeof value === 'string' && /^[^\s@]+@[^\s@]+$/.test(value),
'配列 (1 つ以上)': (value) => Array.isArray(value) && value.length > 0,
'整数 (1 以上)': (value) => Number.isSafeInteger(value) && (value as number) >= 1,
'整数 (円)': (value) => Number.isSafeInteger(value) && (value as number) >= 0,
'整数 (8 か 10)': (value) => value === 8 || value === 10,
};

/** 例の中の、キーの表のある場所のオブジェクトを、配列の要素の中までたどって、その場所と見出しの文とともに返す。 */
function objectsIn(value: unknown, place: string, where: string): { place: string; where: string; value: unknown }[] {
const result = [{ place, where, value }];
if (!isRecord(value)) return result;
for (const row of rows.filter((candidate) => candidate.place === place && candidate.type.startsWith('配列'))) {
const items = value[row.key];
if (Array.isArray(items)) items.forEach((item, index) => result.push(...objectsIn(item, row.key, `${where} の ${row.key}[${index}]`)));
}
return result;
}

/** 値の中で null になっている位置を、配列の要素も含めて返す。 */
function nullsIn(value: unknown, where: string): string[] {
if (value === null) return [where];
if (Array.isArray(value)) return value.flatMap((item, index) => nullsIn(item, `${where}[${index}]`));
if (isRecord(value)) return Object.entries(value).flatMap(([key, field]) => nullsIn(field, `${where}.${key}`));
return [];
}

it('examples/orders の例は、どれも JSON として読め、最上位がオブジェクト', () => {
expect(exampleFiles.length).toBeGreaterThan(0);
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('キーの表の行はどれも形が合い、語は用語集にあり、配列でないキーは、その語の用語集の code と同じ。場所は、最上位か配列のキーの要素', () => {
expect(representation.split(/\r?\n/)).toContain(header);
expect(rows.length).toBeGreaterThan(0);
const arrays = rows.filter((row) => row.place === '' && row.type.startsWith('配列')).map((row) => row.key);
const problems = keyTableLines()
.filter((line) => !rowPattern.test(line))
.map((line) => `形の合わない行: ${line}`);
for (const row of rows) {
if (!codeByName.has(row.term)) problems.push(`${row.key}: 語「${row.term}」が用語集に無い`);
else if (!row.type.startsWith('配列') && codeByName.get(row.term) !== row.key) problems.push(`${row.key}: 語「${row.term}」の code と違う`);
if (row.place !== '' && !arrays.includes(row.place)) problems.push(`${row.key}: 場所の ${row.place} が、最上位の配列のキーでない`);
}
expect(problems).toEqual([]);
});

it('例は、キーの表でその例の列に「入れる」としたキーを、その場所ごとにちょうど持つ', () => {
const problems: string[] = [];
for (const [name, example] of examples) {
const column = columns[name];
if (column === undefined) {
problems.push(`${name}: 例の列が決まっていない`);
continue;
}
for (const { place, where, value } of objectsIn(example, '', name)) {
const expected = rows.filter((row) => row.place === place && row[column]).map((row) => row.key).sort();
const actual = isRecord(value) ? Object.keys(value).sort() : [];
if (!isRecord(value)) problems.push(`${where}: オブジェクトでない`);
else if (actual.join() !== expected.join()) problems.push(`${where}: キーが ${actual.join(',')} で、表の ${expected.join(',')} と違う`);
}
}
expect(problems).toEqual([]);
});

it('例の値は、キーの表の型に合う', () => {
const problems: string[] = [];
for (const row of rows) {
if (typeChecks[row.type] === undefined) problems.push(`${row.key}: 型「${row.type}」の確かめ方が無い`);
}
for (const [name, example] of examples) {
for (const { place, where, value } of objectsIn(example, '', name)) {
if (!isRecord(value)) continue;
for (const row of rows.filter((candidate) => candidate.place === place && candidate.key in value)) {
const check = typeChecks[row.type];
if (check !== undefined && !check(value[row.key])) problems.push(`${where} の ${row.key}: ${JSON.stringify(value[row.key])} が「${row.type}」でない`);
}
}
}
expect(problems).toEqual([]);
});

it('例に null が無い (配列の要素も含めて)', () => {
expect([...examples].flatMap(([name, example]) => nullsIn(example, name))).toEqual([]);
});

it('例の注文明細は 100 以下で、同じ商品の注文明細が 2 つ以上無い', () => {
const problems: string[] = [];
for (const [name, example] of examples) {
const lines = isRecord(example) && Array.isArray(example.lines) ? example.lines : [];
if (lines.length > 100) problems.push(`${name}: 注文明細が ${lines.length} 個`);
const productIds = lines.flatMap((line: unknown) => (isRecord(line) && typeof line.productId === 'string' ? [line.productId] : []));
if (new Set(productIds).size !== productIds.length) problems.push(`${name}: 同じ商品の注文明細が 2 つ以上ある`);
}
expect(problems).toEqual([]);
});

it('注文の例は、リクエストの例と同じ注文を表し、金額はドメインモデルの計算例と同じ', () => {
const request = examples.get('place-order-request.json') as { contactEmail: string; lines: { productId: string; quantity: number }[] };
const order = examples.get('order.json') as {
contactEmail: string;
lines: { productId: string; quantity: number; unitPrice: number; taxRate: number }[];
total: number;
taxAmount: number;
};
expect(request, 'place-order-request.json が無いか、JSON として読めない').toBeDefined();
expect(order, 'order.json が無いか、JSON として読めない').toBeDefined();
expect(order.contactEmail).toBe(request.contactEmail);
expect(order.lines.map(({ productId, quantity }) => ({ productId, quantity }))).toStrictEqual(request.lines);

const calculations = isRecord(taxCalculation) && Array.isArray(taxCalculation.examples) ? taxCalculation.examples.filter(isRecord) : [];
const calculation = calculations.find((example) => example.title === '税率ごとに注文明細が 1 つずつで、端数が出ない') as
| { lines: { productId: string; unitPrice: number; quantity: number; taxRate: number }[]; total: number; taxAmount: number }
| undefined;
expect(calculation).toBeDefined();
expect(order.lines.map(({ productId, unitPrice, quantity, taxRate }) => ({ productId, unitPrice, quantity, taxRate }))).toStrictEqual(
calculation?.lines.map(({ productId, unitPrice, quantity, taxRate }) => ({ productId, unitPrice, quantity, taxRate })),
);
expect({ total: order.total, taxAmount: order.taxAmount }).toStrictEqual({ total: calculation?.total, taxAmount: calculation?.taxAmount });
});