JSON Schema 検証ガイド：検証するあなたのデータ構造

各から外部ソース受信するデータのアプリケーションすべて面临同一つの根本问题：私できる信頼これらのデータか？にかかわらずは API リクエストする体、設定ファイル、キューメッセージそれともデータインポート，できない信のデータで入入系统前にすべて必須を経て検証する。JSON Schema 提供するた一種の標準化の、と言語非依存の方式来定義する有効データの样子，かつ検証する传入データはいいえ適合する该定義する。このガイドではたから编写第一つの Schema まで複雑検証するの高级パターンのすべての内容，かつ提供するたできる直ちに適用するの実用的な例。

とは JSON Schema？

JSON Schema は一つの説明する其彼 JSON ドキュメント结构と制約の JSON ドキュメント。それは一種の許可するあなた注解と検証する JSON データの词汇表，由互联网工程任务组（IETF）標準化。JSON Schema 定義するたについて必須存でどの字段、それ们必須とは何かタイプ、どの值は可受け取るのならびにオブジェクトと配列应どのように结构の规すなわち。

を JSON Schema したい象成あなたのデータ契約。すぐにのようなデータベース Schema 定義するた表の列、タイプと制約一样，JSON Schema 定義するた JSON ドキュメントの属性、タイプと制約。任意の満たす Schema 中すべての制約の JSON データと呼ばれる有効インスタンス，そして違反する任意の制約のデータすなわちは無効の。

JSON Schema とは異なるもの

• データフォーマットではない：JSON Schema 不定義するデータどのようにシリアル化するまたは転送する。それだけ説明する有効データの样子。
• ビジネスロジックの代替ではない：Schema 検証する確認する结构正しく性（タイプ、フォーマット、範囲）。複雑の业务规すなわち（如「用户できない转账超たことがある其残高」）属于アプリケーションコード。
• データベースSchemaではない：だが概念相似，しかし JSON Schema 検証のは JSON ドキュメント，そしていいえデータベース表。ただし，あなたできるする JSON Schema とデータベース制約組み合わせる使用，実装する纵深防御。

JSON Schema バージョン

JSON Schema 经历た多个草案の演入，各草案すべて追加するた機能かつ完善た词汇表。理解するこれらのバージョンに役立つあなたのために项目選択する適切のバージョンかつ避ける互換性问题。

初めてのSchema作成

させる私たちから一つの簡単の例子開始する：一つのを含む姓名、メールと年龄の用户オブジェクトの Schema。

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/schemas/user.json",
    "title": "User",
    "description": "A user account in the system",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "The user's full name"
        },
        "email": {
            "type": "string",
            "format": "email",
            "description": "The user's email address"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150,
            "description": "The user's age in years"
        }
    },
    "required": ["name", "email"],
    "additionalProperties": false
}

此 Schema 声明た一つの有効用户必須は一つのオブジェクト，其中 name と email は必需の文字列属性。age 属性は可选の，しかしもし存ですなわち必須は 0 まで 150 の間の全体数。additionalProperties: false 制約阻止た任意の未で Schema 中定義するの属性，これできる捕获拼写間違いと意外字段。

コアキーワードリファレンス

JSON Schema 提供するた丰富の閉键字词汇表来定義する制約。もって下按カテゴリ组织の最も重要の閉键字。

型キーワード

数値制約

文字列制約

オブジェクト制約

配列制約

よくあるSchemaパターン

现实世界中の Schema 通常必要とする超越簡単型チェックのパターン。もって下は最も常用のパターン。

if/then/else による条件付き検証

使用条件逻辑に基づいて属性值適用する異なるの制約。例えば，支付オブジェクトに基づいて支付方式必要とする異なるの字段。

{
    "type": "object",
    "properties": {
        "method": { "enum": ["credit_card", "bank_transfer"] },
        "card_number": { "type": "string" },
        "routing_number": { "type": "string" }
    },
    "required": ["method"],
    "if": {
        "properties": { "method": { "const": "credit_card" } }
    },
    "then": {
        "required": ["card_number"]
    },
    "else": {
        "required": ["routing_number"]
    }
}

allOf、anyOf、oneOf による組み合わせ

コンポジット閉键字許可するあなたもって強力の方式コンポジット Schema：

• allOf：データ必須満たすすべての子 Schema。に使用されるコンポジット多个制約またはミックスイン可复用の Schema 片段。
• anyOf：データ必須少なくとも満たす一つの子 Schema。に使用される多種類形状すべて可受け取るのユニオン型。
• oneOf：データ必須恰良満たす一つの子 Schema。に使用される互斥の备オプション。

{
    "oneOf": [
        {
            "type": "object",
            "properties": {
                "type": { "const": "email" },
                "address": { "type": "string", "format": "email" }
            },
            "required": ["type", "address"]
        },
        {
            "type": "object",
            "properties": {
                "type": { "const": "phone" },
                "number": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$" }
            },
            "required": ["type", "number"]
        }
    ]
}

$ref によるSchemaの再利用

$ref 閉键字許可するあなた引用すると复用 Schema，消除重复かつ保持 Schema のメンテナンス可能性。あなたできる引用する同一ドキュメント内または外部ファイル中の Schema。

{
    "$id": "https://example.com/schemas/order.json",
    "type": "object",
    "properties": {
        "customer": { "$ref": "#/$defs/address" },
        "shipping": { "$ref": "#/$defs/address" },
        "billing": { "$ref": "#/$defs/address" },
        "items": {
            "type": "array",
            "items": { "$ref": "#/$defs/lineItem" },
            "minItems": 1
        }
    },
    "required": ["customer", "items"],
    "$defs": {
        "address": {
            "type": "object",
            "properties": {
                "street": { "type": "string" },
                "city": { "type": "string" },
                "zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" },
                "country": { "type": "string", "minLength": 2, "maxLength": 2 }
            },
            "required": ["street", "city", "zip", "country"]
        },
        "lineItem": {
            "type": "object",
            "properties": {
                "product": { "type": "string" },
                "quantity": { "type": "integer", "minimum": 1 },
                "price": { "type": "number", "exclusiveMinimum": 0 }
            },
            "required": ["product", "quantity", "price"]
        }
    }
}

nullable型

で JSON Schema Draft 2020-12 中，nullable型使用を含む "null" のタイプ配列来表示：

{
    "type": ["string", "null"],
    "description": "An optional display name, or null if not set"
}

で较早の草案中，OpenAPI 仕様使用た nullable: true 閉键字。に対して標準 JSON Schema，请常に使用タイプ配列方法。

フォーマット検証

format 閉键字提供するた超越结构確認するの语义検証する。それ指定文字列必須適合する一種の众所周知のフォーマット。常用支持するのフォーマットを含む：

プログラムによる検証 JSON データ

Schema 検証するで統合するまでアプリケーションコード中时最ものためにあり用。もって下は使用異なる言語中ストリーム行ライブラリの例。

JavaScript で Ajv を使用

Ajv は JavaScript 中使用最も広くの JSON Schema バリデーター。それ支持するすべての草案バージョン，かつを通じて Schema の JIT コンパイル提供する出色のパフォーマンス。

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv);

const schema = {
    type: 'object',
    properties: {
        name: { type: 'string', minLength: 1 },
        email: { type: 'string', format: 'email' },
        age: { type: 'integer', minimum: 0 }
    },
    required: ['name', 'email'],
    additionalProperties: false
};

const validate = ajv.compile(schema);
const valid = validate({ name: 'Alice', email: 'alice@example.com', age: 30 });

if (!valid) {
    console.log(validate.errors);
    // [{ keyword: 'required', params: { missingProperty: 'email' }, ... }]
}

Python で jsonschema を使用

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name", "email"],
    "additionalProperties": False
}

try:
    validate(instance={"name": "Alice", "email": "alice@example.com"}, schema=schema)
except ValidationError as e:
    print(f"Validation failed: {e.message}")

使用 JSON Schema 入行 API データ検証

JSON Schema 最も価値があるの適用するの一つは検証する API リクエストすると対応データ。これは以下を保証しますたあなたの API 受信するフォーマット良良の入力するかつもって预期フォーマット戻るデータ，できるおよび早捕获間違いかつへクライアント明確なエラーメッセージを提供。

Express.js ミドルウェア

import Ajv from 'ajv';

const ajv = new Ajv({ allErrors: true });

function validateBody(schema) {
    const validate = ajv.compile(schema);
    return (req, res, next) => {
        if (!validate(req.body)) {
            return res.status(400).json({
                error: 'Validation failed',
                details: validate.errors
            });
        }
        next();
    };
}

app.post('/api/users',
    validateBody({
        type: 'object',
        properties: {
            name: { type: 'string', minLength: 1, maxLength: 100 },
            email: { type: 'string', format: 'email' },
            role: { enum: ['admin', 'editor', 'viewer'] }
        },
        required: ['name', 'email'],
        additionalProperties: false
    }),
    (req, res) => {
        // req.body is guaranteed valid here
        createUser(req.body);
    }
);

OpenAPI と JSON Schema

OpenAPI（前身のために Swagger）使用 JSON Schema の一つの子集来定義する API リクエストすると対応 Schema。もしあなたすでにで使用 OpenAPI，できるから API 仕様中提取 Schema かつする其に使用される実行する时検証する。のような openapi-schema-validator と express-openapi-validator これ样のツールできる自動化するこのたことがある程，確保するあなたの API ドキュメントと検証する逻辑常に保持同期する。

ベストプラクティス

• 常に $schema を設定：を含む $schema 閉键字もって声明あなたの Schema 使用の草案バージョン。これできる防止する歧义かつ確保する検証する器正しく説明するあなたの Schema。
• $id をSchema識別子として使用：$id 閉键字のためにあなたの Schema 提供する唯一标识符，かつとして解析する $ref 引用するのベース URI。たとえ〜でもは本に Schema，も请常に設定するそれ。
• additionalProperties: false を設定：默认情况下，JSON Schema 許可するオブジェクト中あり任意の额外属性。additionalProperties: false を設定 できる捕获拼写間違いと意外字段，させるあなたの Schema より严格，API より予測可能。
• $defs で再利用可能なコンポーネントを格納：で $defs 中定義する通用 Schema，かつ使用 $ref 引用するそれ们。これは以下を減らしますた重复かつさせる Schema より易于維持する。
• 説明の追加：各属性と Schema すべて应あり description 字段。これ既としてドキュメント，もヘルプ其彼開発者理解する各字段の用途と制約。
• システム境界での検証：で系统の边缘適用する Schema 検証する：API エンドポイント、メッセージ消费者、データインポートパイプラインと設定するローダー。不する必要がある検証するあなた自己のコードすでに生み出すかつ信頼のデータ。
• バリデーターで厳格モードを有効化：設定する検証する器拒否する未知閉键字、強制フォーマット検証かつ報告すべての間違いそして非で第一つの間違い处停止する。これできるで単次検証する中捕获より多问题。
• Schemaのバージョン管理：で $id URI 中を含む Schema バージョン（例えば https://example.com/schemas/user/v2.json）。这允许你在不破坏现有消费者的情况下演进 Schema。
• Schemaのテスト：のためにあなたの Schema 编写を含む有効と無効例のユニットテスト。これは以下を保証しますあなたの Schema 実行するあなた意图の制約，かつで Schema 変更する时捕获回归。
• format によるセマンティック検証：优先使用 format: "email" そしていいえ複雑の正規表現パターン。フォーマットより具可読性、より易維持する，かつ受益于検証する器ライブラリ中を経て十分にテストするの検証する逻辑。