JSON to TypeScript変換 ?と|が付く規則

APIレスポンスで受け取ったJSONサンプルを見ながらTypeScriptのinterfaceを手で入力していると、どのキーに疑問符(?)を付けるべきか、判断に迷う瞬間がやってきます。
この疑問符とユニオン(|)の表記は勘ではなく、決まったルールで計算される値です。ルールさえ分かれば、自動生成されたコードを目で検証できます。
この記事では、そのルールと、ネストしたオブジェクトがなぜ1つの大きなinterfaceではなく複数に分かれるのかを、実際のJSONを使って見ていきます。
まとめ ① 配列の要素の一部にしかないキーにはoptional(
?)が付き、すべての要素にあれば付きません。 ② 同じキーでも要素ごとに値の種類(型)が違えば、ユニオン(|)にまとめられます。 ③ ネストしたオブジェクトと配列要素のオブジェクトは、キー名に基づく名前が付いて別々のinterfaceに分かれます。
配列の中のJSONを手で入力するときに起きる問題
APIドキュメントの代わりに、実際のレスポンスJSONのサンプルを1つだけ受け取って型を作らないといけない、という場面はよくあります。注文一覧APIのレスポンスなら、items配列の中に商品ごとに異なる項目が入っていることがあります。
ある商品には割引率(discountRate)があり、ある商品にはない、といった具合です。
手で書くときによくある判断ミス
このときinterfaceを手で書くと、よく2つのミスが起きます。
すべてのフィールドをoptional(?)にしてしまい型の安全性が失われるか、逆に実際には一部の要素にしかないフィールドを必須で書いてしまい、別のレスポンスサンプルを入れたときにコンパイルエラーになるかです。
ネストした顧客情報(customer)や配列要素(items)をどこまで1つのinterfaceに押し込み、どこから別に切り出すかも、手で判断するのは曖昧です。
この3つ——optionalかどうか、ユニオンかどうか、分離するかどうか——は、実はJSONの構造を見るだけで機械的に決まる値です。
JSONサンプルだけを見て自分で型を作る方法
ツールがなくても、次の手順をそのままたどれば同じ結果を手で作れます。
- 最上位オブジェクトのキー一覧を書きます。
- 各キーの値がプリミティブ値(文字列・数値・真偽値・null)か、オブジェクトか、配列かを区別します。
- プリミティブ値のキーは、その型をそのまま書きます。
- オブジェクトの値は、キー名をパスカルケースに変えた名前を付けて、別のinterfaceとして切り出します。
- 配列の値は、その中の要素すべてを1つの比較対象(標本の集合)とみなし、要素ごとに各キーがあるか・値の種類は何かを比較します。
- 標本の一部にしかないキーには疑問符(
?)を付け、存在するときの値の種類が複数ある場合は、その種類を|でつないで書きます。
実際のJSONでやってみましょう。
{
"orderId": 1024,
"customer": { "name": "田中太郎", "email": "taro@example.com" },
"couponCode": "WELCOME10",
"items": [
{ "productId": "A1", "price": 12000, "discountRate": 0.1 },
{ "productId": "A2", "price": 8000, "discountRate": null },
{ "productId": "A3", "price": 15000 }
]
}
orderIdは数値が1つだけなのでnumber、couponCodeは文字列が1つだけなのでstringです。customerはオブジェクトなので、名前を付けて切り出します。
キー名customerをパスカルケースに変えるとCustomerで、中のname・emailはどちらも文字列なので{ name: string; email: string }です。
items配列の要素を標本として比較する
itemsは配列なので、3つの要素を標本として比較します。productIdとpriceは3つの要素すべてにあり、値の種類もそれぞれ文字列・数値の1つだけなので、そのままstring、numberです。
discountRateは要素1では数値、要素2ではnull、要素3にはキー自体がありません。
存在するかどうかが分かれるので疑問符が付き、存在するときの値の種類が数値とnullの2つなので、ユニオンでまとめてdiscountRate?: number | nullになります。
配列要素のオブジェクトにも名前が必要です。itemsを単数形にしたitemに名前を付けるとItemです。ここまでまとめると、手で作った結果は次のようになります。
interface Customer {
name: string;
email: string;
}
interface Item {
productId: string;
price: number;
discountRate?: number | null;
}
interface Root {
orderId: number;
customer: Customer;
couponCode: string;
items: Item[];
}
配列の要素が3つだけの小さな例だったので手でも比較できましたが、実際のAPIレスポンスは要素が数十・数百個あり、キーもはるかに多いです。その分、目で1つずつ比べるうちに見落とすキーが増えていきます。
無料ツール「JSON → TypeScript 型生成」で確認する。
ブラウザ内ですぐに変換され、入力したJSONがサーバーへ送信・保存されることはありません

生成されたコードでよく迷う表記
| 状況 | 結果の表記 | 理由 |
|---|---|---|
| 配列要素の一部にだけキーがある | key?: T | 標本の一部にしか存在しない → optional |
| 同じキーなのに値の種類が違う | key: A | B | 標本ごとに値の型が違う → ユニオン |
| 一部にだけあり、値の種類も違う | key?: A | B | 存在の有無と値の種類が同時に分かれる |
| 異なる2つのオブジェクトのキー・型の構造が完全に同じ | 同じinterfaceを再利用 | 同一の構造は1つの名前にまとめられる |
| ネストしたオブジェクト / 配列要素のオブジェクト | 別名を付けたinterfaceに分離 | キー名に基づく名前(パスカルケース)が付く |
1つ注意点があります。疑問符とユニオンは、比較する標本が複数あるときだけ計算されます。JSONに配列が1つもない単一のオブジェクトだけを貼り付けると、比較対象が1つしかないため、疑問符もユニオンも現れません。
複数のレスポンス例をまとめて確認したい場合は、最上位のJSON自体を配列で囲んで、複数件を一度に入れれば済みます。
最上位の型名は入力欄(デフォルトはRoot)で変更でき、interfaceで宣言するかtypeで宣言するか、exportキーワードを付けるか(デフォルトはオン)もオプションで選べます。
どの宣言方式を選んでも、上で説明したoptional・ユニオン・分離のルールは同じように適用されます。
まとめ
- optional(
?)は「標本の一部にだけそのキーがあるか」で決まります。 - ユニオン(
|)は「そのキーの値の種類が標本ごとに違うか」で決まります。 - 2つの条件が重なると、
key?: A | Bのように一緒に表示されます。 - ネストしたオブジェクトと配列要素のオブジェクトは、キー名に基づく名前で別のinterfaceになり、構造が同じなら再利用されます。
- 配列のない単一のオブジェクトだけを入れると、比較対象が1つしかないため、疑問符・ユニオンは現れません。
ブラウザ内ですぐに変換され、入力したJSONがサーバーへ送信・保存されることはありません
よくある質問
optional(?)が付くのはどんなときですか?
配列の要素(標本)の一部にだけそのキーが存在するときに付きます。すべての要素にキーがあれば、値がnullでもoptionalは付かず、代わりに値の種類にnullが混ざっていることがユニオンで示されます。
ユニオン(|)はどんなときに付きますか?
同じキーについて、標本ごとに値の型(文字列・数値・真偽値・null・オブジェクトなど)が異なるとき、その種類を|でつないで表示します。種類が1つだけなら、ユニオンなしで単一の型だけが出ます。
ネストしたオブジェクトが1つのinterfaceにまとまらず分かれるのはなぜですか?
オブジェクトの値や配列要素のオブジェクトには、キー名をパスカルケースに変えた名前が付き、別のinterface(またはtype)として分離されます。
異なる2つの場所にあるオブジェクトがキー・型の構造まで完全に同じなら、新しく作らずに同じinterfaceを再利用します。
入力したJSONはサーバーに保存されますか?
いいえ。JSONのパースと型の推論はすべてブラウザ内で、入力のたびに即座に実行され、入力内容がサーバーに送信されたり保存されたりすることはありません。
この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む