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

公開ツールJSON → TypeScript 型生成

目次
  1. 配列の中のJSONを手で入力するときに起きる問題
  2. JSONサンプルだけを見て自分で型を作る方法
  3. 生成されたコードでよく迷う表記
  4. まとめ
  5. よくある質問

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サンプルだけを見て自分で型を作る方法

ツールがなくても、次の手順をそのままたどれば同じ結果を手で作れます。

  1. 最上位オブジェクトのキー一覧を書きます。
  2. 各キーの値がプリミティブ値(文字列・数値・真偽値・null)か、オブジェクトか、配列かを区別します。
  3. プリミティブ値のキーは、その型をそのまま書きます。
  4. オブジェクトの値は、キー名をパスカルケースに変えた名前を付けて、別のinterfaceとして切り出します。
  5. 配列の値は、その中の要素すべてを1つの比較対象(標本の集合)とみなし、要素ごとに各キーがあるか・値の種類は何かを比較します。
  6. 標本の一部にしかないキーには疑問符(?)を付け、存在するときの値の種類が複数ある場合は、その種類を|でつないで書きます。

実際の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 → 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 → TypeScript 型生成

ブラウザ内ですぐに変換され、入力したJSONがサーバーへ送信・保存されることはありません

よくある質問

optional(?)が付くのはどんなときですか?

配列の要素(標本)の一部にだけそのキーが存在するときに付きます。すべての要素にキーがあれば、値がnullでもoptionalは付かず、代わりに値の種類にnullが混ざっていることがユニオンで示されます。

ユニオン(|)はどんなときに付きますか?

同じキーについて、標本ごとに値の型(文字列・数値・真偽値・null・オブジェクトなど)が異なるとき、その種類を|でつないで表示します。種類が1つだけなら、ユニオンなしで単一の型だけが出ます。

ネストしたオブジェクトが1つのinterfaceにまとまらず分かれるのはなぜですか?

オブジェクトの値や配列要素のオブジェクトには、キー名をパスカルケースに変えた名前が付き、別のinterface(またはtype)として分離されます。

異なる2つの場所にあるオブジェクトがキー・型の構造まで完全に同じなら、新しく作らずに同じinterfaceを再利用します。

入力したJSONはサーバーに保存されますか?

いいえ。JSONのパースと型の推論はすべてブラウザ内で、入力のたびに即座に実行され、入力内容がサーバーに送信されたり保存されたりすることはありません。

この記事は韓国語の原文をもとに作成しています。 韓国語の原文を読む

関連記事

  1. JSONをYAMLに変換するときの配列とインデントの規則JSONの配列がハイフン(-)のリストに、ネストしたオブジェクトがインデント階層になる規則と、2スペース・4スペースの違い、KubernetesやDocker Composeに貼るときの間違いを整理します。
  2. JSONPathの使い方: 記号ごとの意味を例で確認$や.属性、[数字]、[*]、..がそれぞれ何を選ぶのかを例のJSONで一つずつ確認します。フィルタ式やスライスが使えない理由も事実関係で整理しました。
  3. JWTデコード方法|構造とexp・iatの読み解き方JWTは暗号化ではなくエンコードなので、誰でも中身を読めます。header.payload.signatureの構造とbase64urlデコードの仕組み、exp・iatの秒単位の値を日時に直す方法をまとめました。
  4. JWTの署名を検証して改ざんを確認する方法JWTはheader.payload.signatureの3部分で、payloadは暗号化ではなくエンコードのみです。HMAC-SHA256の署名計算の仕組みと、検証に失敗する2つの原因(鍵の不一致・改ざん)を解説します。
  5. line-clamp CSSの使い方、動かない原因と対処line-clampが効かない原因は、ほとんどがdisplay: -webkit-boxの指定漏れです。1行と複数行の省略で使うプロパティの組み合わせの違いをコードで解説し、行数や幅を変えながらリアルタイムで確認できます。
  6. 箇条書き変換ツールの使い方 — Markdown・HTMLリストに変換行頭の記号や番号を消して、Markdownリスト・HTMLのul/liタグ・任意の記号の箇条書きへ一度に変換する方法と、つまずきやすい点をまとめます。

関連ツール