UtilityBox

PRACTICAL GUIDE / JSON・API開発

JSONからC#クラスを作るときのnullable設計

サンプルJSONだけでは判断できないnullable、数値型、日時、配列の型設計を解説します。

最終確認日：2026年8月22日　確認者：UtilityBox運営者

このガイドで防ぐ問題

生成されたC#クラスをそのまま使い、別パターンのAPIレスポンスでデシリアライズに失敗する問題を防ぎます。

JSONからC#クラスを生成すると、最初の型定義は数秒で作れます。しかし、サンプル1件からrequired、nullable、数値の最大桁、日時のタイムゾーンまで正確に推測することはできません。生成結果は「コンパイル可能な雛形」として扱うのが安全です。

特に外部APIでは、通常時に存在する項目がエラー時だけ欠落したり、空配列・nullへ変わったりします。複数のレスポンス例を比較し、System.Text.Jsonや利用中のシリアライザー設定に合わせて調整します。

WORKED EXAMPLE

1件のサンプルだけではnullableを判断できない例

通常レスポンスではdisplayNameが必ず入っているように見えても、退会済みユーザーではnullになるAPIを想定します。

処理・確認前

{
  "id": "9007199254740993",
  "displayName": "Yamada",
  "lastLogin": "2026-08-17T08:00:00+09:00"
}

処理・確認後

public sealed class UserResponse
{
    public string Id { get; init; } = string.Empty;
    public string? DisplayName { get; init; }
    public DateTimeOffset? LastLogin { get; init; }
}

この例で確認するポイント

  • 計算しないIDは桁数事故を避けるためstringが適することがあります。
  • nullになり得る文字列はstring?を検討します。
  • オフセット付き日時を保持したい場合はDateTimeOffsetが候補です。

必須・任意はAPI仕様から決める

JSONに値が入っていることと、その項目が常に必須であることは同じではありません。正常、空データ、エラー、旧バージョンなど複数レスポンスを確認します。

nullable reference typesを有効にしている場合、生成後にstringとstring?を明示的に見直すと、欠損をコンパイル時の設計へ反映できます。

数値に見えるIDを数値型へ固定しない

ID、郵便番号、注文番号などは数字だけでも算術計算しません。先頭ゼロや将来の桁数増加を維持する必要があるため、API仕様が文字列ならstringを維持します。

金額や比率はdoubleではなくdecimalが適する場合があります。用途によって型を選び、生成結果を自動的な正解と扱わないことが重要です。

日時はタイムゾーン情報を落とさない

ISO 8601文字列にZや+09:00が含まれる場合、タイムゾーン情報を保持する必要があるか確認します。サーバー時刻、画面表示時刻、保存時刻のどこで変換するかを決めます。

DateTimeとDateTimeOffsetの選択はシステム設計に依存するため、単一サンプルから自動決定せず既存コードの方針へ合わせます。

問題が起きる主な原因

  • 1件のサンプルだけで必須・任意を判断している。
  • 整数値からintを選び、将来の桁数増加を考慮していない。
  • 日付らしい文字列を自動的にDateTimeへ決めている。

安全に作業する手順

  1. 1

    複数レスポンス例とAPI仕様書を用意します。

  2. 2

    生成クラスを雛形として、nullableと型を手動調整します。

  3. 3

    欠損、null、空配列、大きな数値のテストを追加します。

結果を利用する前の確認項目

  • 欠損項目とnull項目の両方を処理できる。
  • IDを数値計算しない場合はstringを検討する。
  • 日時のタイムゾーンが維持される。

作業完了前のチェックリスト

  • 複数レスポンス例を確認した
  • 必須・任意を仕様書と照合した
  • IDを不要に数値化していない
  • 金額や精度が必要な値の型を見直した
  • 日時のオフセットを維持するか決めた
  • 生成クラスで欠損・null・空配列をテストした

この方法の限界と注意点

  • 自動生成は完全なドメインモデル設計を行いません。
  • プロパティ名の変換規則はシリアライザー設定と合わせる必要があります。

関連する無料ツール

UtilityBoxのガイド方針

ツールの操作方法だけでなく、結果を誤用しないための具体例、確認項目、処理の限界、元データを保管すべき場面まで記載します。原因・手順・完了判定・限界を運営者が確認したガイドだけを一覧と検索対象へ掲載します。

品質確認の方法と更新方針を確認する →