JSONベストプラクティス:フォーマット、検証、パース

2026年3月31日 · 12分で読む

JSONの基礎
フォーマット標準
検証テクニック
JavaScriptでのJSONパース
PythonでのJSONパース
JSONスキーマ設計パターン
避けるべき一般的なJSONミス
パフォーマンス最適化
セキュリティに関する考慮事項
JSONのテストとデバッグ
よくある質問
関連記事

JSONの基礎

JSON(JavaScript Object Notation)は、Web上で最も広く使用されているデータ交換フォーマットです。人間が読みやすく、言語に依存せず、事実上すべてのプログラミング言語でサポートされています。信頼性の高いAPI、設定ファイル、データパイプラインを構築するには、JSONのベストプラクティスを理解することが不可欠です。

JSONはもともとJavaScriptから派生しましたが、現在では普遍的な標準となっています。そのシンプルさと柔軟性により、サーバーとWebアプリケーション間のデータ送信、設定の保存、APIレスポンスの文書化に最適です。

コアデータ型

JSONは正確に6つのデータ型をサポートしています。適切なJSON設計には、これらの制限を理解することが重要です:

{
  "string": "Hello, World!",
  "number": 42,
  "decimal": 3.14,
  "boolean": true,
  "null_value": null,
  "array": [1, 2, 3],
  "object": {"nested": "value"}
}

データ型	説明	例
`string`	二重引用符で囲まれたテキスト	`"Hello"`
`number`	整数または浮動小数点数	`42`, `3.14`
`boolean`	真または偽の値	`true`, `false`
`null`	値の欠如を表す	`null`
`array`	順序付けられた値のリスト	`[1, 2, 3]`
`object`	順序なしのキーと値のペア	`{"key": "value"}`

重要: JSONはコメント、末尾のカンマ、単一引用符、undefined、関数、またはネイティブの日付オブジェクトをサポートしていません。日付は文字列として表現する必要があり、通常はISO 8601形式を使用します。

JSONを使用するタイミング

JSONは特定のシナリオで優れています:

REST API: APIリクエストとレスポンスペイロードの事実上の標準
設定ファイル: アプリケーション設定、環境変数、機能フラグ
データストレージ: MongoDBのようなNoSQLデータベースはJSON風のドキュメント構造を使用
Webアプリケーション: クライアント・サーバー間通信と状態管理
ログファイル: 解析と分析を容易にする構造化ログ

複雑なデータ検証のニーズには、JSONフォーマッターを使用して、デプロイ前にデータ構造が有効であることを確認することを検討してください。

フォーマット標準

一貫したフォーマットにより、JSONが読みやすく、保守しやすく、デバッグしやすくなります。確立された規則に従うことで、エラーが減り、チーム間のコラボレーションが向上します。

2スペースインデントを使用

2スペースインデントはJSONの業界標準です。過度な空白なしに明確な視覚的階層を提供します。

// ✅ 良い: 2スペースインデント
{
  "user": {
    "name": "Jane",
    "email": "[email protected]",
    "preferences": {
      "theme": "dark",
      "notifications": true
    }
  }
}

// ❌ 悪い: インデントなし(最小化)
{"user":{"name":"Jane","email":"[email protected]"}}

最小化されたJSONは帯域幅を削減するために本番APIに適していますが、開発とドキュメント用には常にフォーマットされたバージョンを維持してください。

キーにはcamelCaseを使用

一貫したキーの命名により混乱を防ぎ、JSONをより予測可能にします。camelCaseはJSON APIで最も一般的な規則です。

// ✅ 良い: camelCase
{
  "firstName": "Jane",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "createdAt": "2026-03-15T10:30:00Z",
  "isActive": true
}

// ❌ スタイルの混在を避ける
{
  "first_name": "Jane",      // snake_case
  "LastName": "Smith",       // PascalCase
  "email-address": "...",    // kebab-case
  "CREATED_AT": "..."        // SCREAMING_SNAKE_CASE
}

プロのヒント: Pythonバックエンドを使用している場合、snake_caseに遭遇する可能性があります。1つの規則を選択し、API全体でそれを守ってください。必要に応じて変換レイヤーを使用して規則間で変換します。

日付にはISO 8601を使用

JSONにはネイティブの日付型がないため、常にISO 8601形式の文字列を使用してください。これにより、異なるプログラミング言語とタイムゾーン間で一貫した解析が保証されます。

{
  "createdAt": "2026-03-15T10:30:00Z",           // UTC時刻
  "updatedAt": "2026-03-15T14:45:00+08:00",     // タイムゾーンオフセット付き
  "date": "2026-03-15",                          // 日付のみ
  "time": "10:30:00"                             // 時刻のみ
}

意味のあるキー名を使用

説明的なキーにより、JSONが自己文書化され、外部ドキュメントの必要性が減ります。

// ✅ 良い: 説明的なキー
{
  "totalItemCount": 42,
  "isActive": true,
  "errorMessage": "Invalid email format",
  "maxRetryAttempts": 3
}

// ❌ 悪い: 不可解な略語
{
  "cnt": 42,
  "act": true,
  "err": "Invalid email format",
  "mra": 3
}

深いネストを避ける

深くネストされた構造は読みにくく、解析が困難です。最大3〜4レベルのネストを目指してください。

// ✅ 良い: フラットな構造
{
  "userId": "123",
  "userName": "Jane",
  "userEmail": "[email protected]",
  "addressStreet": "123 Main St",
  "addressCity": "Boston"
}

// ❌ 悪い: 過度なネスト
{
  "user": {
    "details": {
      "personal": {
        "name": {
          "first": "Jane"
        }
      }
    }
  }
}

検証テクニック

JSONを検証することで、データの整合性が確保され、ランタイムエラーが防止されます。検証には複数のアプローチがあり、それぞれ異なるユースケースに適しています。

JSONスキーマ検証

JSONスキーマは、JSONドキュメントに注釈を付けて検証するための強力な語彙です。JSONデータ構造の契約を提供します。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": ["name", "email"]
}

人気のあるJSONスキーマバリデーターには以下が含まれます:

JavaScript: Ajv(最速)、joi、yup
Python: jsonschema、pydantic
Java: everit-org/json-schema、networknt/json-schema-validator
Go: gojsonschema、jsonschema

ランタイム検証

特に外部ソースやユーザー入力からデータを受信する場合は、常にランタイムでJSONデータを検証してください。

// try-catchを使用したJavaScriptの例
function validateJSON(jsonString) {
  try {
    const data = JSON.parse(jsonString);
    
    // 追加の検証
    if (!data.email || !data.email.includes('@')) {
      throw new Error('Invalid email format');
    }
    
    return { valid: true, data };
  } catch (error) {
    return { valid: false, error: error.message };
  }
}

オンライン検証ツール

開発中の迅速な検証には、即座に構文チェックとフォーマットを提供するJSONフォーマッターのようなオンラインツールを使用してください。また、差分チェッカーを使用してJSON構造を比較し、不一致を特定することもできます。

クイックヒント: プリコミットフックを設定して、バージョン管理にコミットされる前にJSONファイルを自動的に検証します。これにより、開発プロセスの早い段階でフォーマットエラーをキャッチできます。

JavaScriptでのJSONパース

JavaScriptはJSONを扱うためのネイティブメソッドを提供しています。これらのメソッドとそのエッジケースを理解することは、堅牢なアプリケーションにとって不可欠です。

JSON.parse()メソッド

JSON.parse()メソッドは、JSON文字列をJavaScriptオブジェクトに変換します。

const jsonString = '{"name":"Jane","age":30}';
const obj = JSON.parse(jsonString);

console.log(obj.name); // "Jane"
console.log(obj.age);  // 30

パースエラーの処理

不正なJSONを適切に処理するために、常にJSON.parse()をtry-catchブロックでラップしてください。

function safeJSONParse(jsonString, fallback = null) {
  try {
    return JSON.parse(jsonString);
  } catch (error) {
    console.error('JSON parse error:', error.message);
    return fallback;
  }
}

// 使用法
const data = safeJSONParse(userInput, { error: 'Invalid JSON' });

JSON.stringify()メソッド

JSON.stringify()メソッドは、JavaScriptオブジェクトをJSON文字列に変換します。

const obj = {
  name: "Jane",
  age: 30,
  hobbies: ["reading", "coding"]
};

// 基本的な使用法
const jsonString = JSON.stringify(obj);

// インデント付きの整形出力
const formatted = JSON.stringify(obj, null, 2);

// カスタムreplacer関数
const filtered = JSON.stringify(obj, ['name', 'age']); // 特定のキーのみを含める

reviver関数を使用した高度なパース

reviver関数を使用すると、パース中に値を変換できます。日付文字列をDateオブジェクトに変換する場合に便利です。

const jsonString = '{"name":"Jane","createdAt":"2026-03-15T10:30:00Z"}';

const obj = JSON.parse(jsonString, (key, value) => {
  if (key === 'createdAt') {
    return new Date(value);
  }
  return value;
});

console.log(obj.createdAt instanceof Date); // true

特殊値の処理

JSONシリアライゼーション中にJavaScriptが特殊値をどのように処理するかに注意してください:

const obj = {
  func: function() {},      // 関数は省略される
  undef: undefined,         // undefinedは省略される
  symbol: Symbol('test'),   // シンボルは省略される
  date: new Date(),         // 日付は文字列になる
  nan: NaN,                 // NaNはnullになる
  infinity: Infinity        // Infinityはnullになる
};

console.log(JSON.stringify(obj));
// {"date":"2026-03-31T10:30:00.000Z","nan":null,"infinity":null}

プロのヒント: 開発中は読みやすい出力のためにJSON.stringify()の第3パラメータを2に設定しますが、本番環境ではペイロードサイズを最小化するために省略してください。

PythonでのJSONパース

Pythonの組み込みjsonモジュールは、JSON操作の包括的なサポートを提供します。高速で信頼性が高く、外部依存関係なしでほとんどのユースケースを処理します。

JSONデータの読み込み

Pythonは、JSONを読み込むための2つの主要なメソッドを提供します:文字列用のjson.loads()とファイルオブジェクト用のjson.load()です。

import json

# JSON文字列をパース
json_string = '{"name": "Jane", "age": 30}'
data = json.loads(json_string)

# ファイルからJSONを読み込む
with open('data.json', 'r') as file:
    data = json.load(file)

print(data['name'])  # "Jane"

JSONデータのダンプ

同様に、Pythonは文字列用のjson.dumps()とファイル用のjson.dump()を提供します。

import json

data = {
    "name": "Jane",
    "age": 30,
    "hobbies": ["reading", "coding"]
}

# JSON文字列に変換
json_string = json.dumps(data, indent=2)

# ファイルに書き込む
with open('output.json', 'w') as file:
    json.dump(data, file, indent=2)

カスタムオブジェクトの処理

PythonオブジェクトはJSONに直接シリアライズできません。複雑な型にはカスタムエンコーダーを使用してください。

import json
from datetime import datetime
from decimal import Decimal

class