Skip to main content

Json-Schema

jsonやYamlのフォーマットを定義できるようなものってありますか？​

はい、JSONやYAMLのフォーマットを定義できるものとして、JSON Schemaという仕様があります。

JSON Schemaについて​

JSON Schemaは、JSONデータの構造、データ型、必須項目、値の制約などを定義するための言語です。これにより、JSONデータが期待される形式に従っているかどうかを**検証（バリデーション）**することができます。

JSON Schemaの主な特徴：​

  • 構造の定義: オブジェクトのキー、配列の要素、それらの階層構造を定義します。
  • データ型の指定: 各値が文字列（string）、数値（number）、ブーリアン（boolean）など、どの型であるべきかを指定できます。
  • 制約の定義:
    • 必須項目: 必須のキーを定義します。
    • 値の範囲: 数値の最小値・最大値や、文字列の最小文字数・最大文字数などを設定できます。
    • 正規表現: 文字列が特定のパターンに従っているかを検証できます。
  • ドキュメント: スキーマ自体に説明文（description）を追加できるため、ドキュメントとしても機能します。

JSON Schemaは、JSON自体を使ってスキーマを記述します。そのため、人間にも機械にも理解しやすい形式です。YAMLはJSONの上位互換であるため、JSON SchemaをYAMLファイルのバリデーションにも利用できます。

JSON Schemaの具体的な利用例​

JSON Schemaは、主に以下のような目的で利用されます。

  • APIの検証: APIから受け取ったJSONデータが、あらかじめ決められたフォーマットに従っているかを確認し、不正なデータを防ぎます。
  • 設定ファイルの検証: 設定ファイルが正しい形式で記述されているかを自動的にチェックします。
  • 開発支援: IDEやエディタがJSON Schemaに基づいて、コード補完やエラーチェックの機能を提供します。

JSON Schemaを利用することで、データの信頼性を高め、開発の効率を向上させることができます。

JSON Schemaの書き方例​

簡単なユーザー情報を検証するためのJSON Schemaの例を示します。

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "ユーザーの名前",
      "minLength": 1
    },
    "age": {
      "type": "integer",
      "description": "ユーザーの年齢",
      "minimum": 0
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name", "age"],
  "additionalProperties": false
}

このスキーマは、以下のルールを定義しています。

  • ルートはオブジェクトであること ("type": "object")
  • name は必須の文字列で、1文字以上であること
  • age は必須の整数で、0以上であること
  • email はメールアドレスの形式の文字列であること
  • name と age は必須項目であること ("required")
  • 上記に定義されていないプロパティは存在してはならないこと ("additionalProperties": false)

JSON SchemaはJSON限定ですか？​

いいえ、JSON SchemaはJSONに限定されません。JSON Schemaは、JSONだけでなく、YAMLのデータ検証にも広く利用されています。

なぜYAMLでも使えるのか？​

これは、YAMLがJSONの上位互換（スーパーセット）として設計されているためです。多くのYAMLファイルは、インデントや簡潔な書き方というYAML独自のシンタックスを持ちつつも、JSONとして表現できるデータ構造を持っています。

この互換性のおかげで、JSON Schemaで定義したスキーマを使って、YAMLファイルがその構造、データ型、制約を満たしているかを検証できるのです。

YAML検証での利用例​

JSON SchemaをYAMLの検証に利用する主なケースは以下の通りです。

  • 設定ファイルの検証: Docker ComposeやKubernetesなどのYAMLで書かれた設定ファイルが正しい形式かをチェックします。
  • CI/CDパイプライン: ビルドやデプロイ前に、設定ファイルが正しいことを自動で検証するステップとして組み込まれます。
  • エディタの支援: VS Codeなどのエディタでは、JSON Schemaを読み込ませることで、YAMLファイル編集時にリアルタイムで補完やエラーチェックを行うことができます。

このように、JSON SchemaはJSONとYAMLの両方のデータ検証において、非常に強力で標準的なツールとして機能しています。

JSON SchemaでJSONをチェックするライブラリはありますか？​

はい、JSON SchemaでJSONをチェック（バリデーション）するライブラリは、多くのプログラミング言語に存在します。

Python​

  • jsonschema: 最も広く使われているライブラリの一つで、標準的なJSON Schemaの仕様をサポートしています。
  • voluptuous: シンプルで使いやすいバリデーションライブラリで、JSON Schemaに似た構文でスキーマを定義できます。

JavaScript / Node.js​

  • ajv (Another JSON Schema Validator): 高速で、最新のJSON Schema仕様に準拠しています。多くのプロジェクトで利用されている定番ライブラリです。
  • jsonschema: シンプルで使いやすいバリデーションツールです。

Ruby​

  • json-schema: JSON Schemaのバリデーション機能を提供するGemです。
  • json-schemer: 最新の仕様に対応しており、よりモダンなAPIを提供しています。

PHP​

  • justinrainbow/json-schema: PHPでJSON Schemaのバリデーションを行うためのライブラリです。Composerで簡単にインストールできます。

これらのライブラリは、JSONデータをプログラムで処理する際に、データの信頼性を高めるために非常に役立ちます。受け取ったJSONデータがスキーマに準拠しているかをチェックすることで、予期せぬエラーを防ぐことができます。

C#やJavaの場合ではどうなりますか？​

C#とJavaでも、JSON Schemaを使用してJSONを検証するためのライブラリが多数提供されています。これらのライブラリを使うことで、アプリケーション内でJSONデータの妥当性を簡単にチェックできます。

C#の場合​

C#では、主に以下のライブラリが広く使われています。

  • NJsonSchema: JSON Schemaの読み込み、生成、検証を行うためのライブラリです。既存の.NETクラスからJSON Schemaを生成する機能や、逆にJSON SchemaからC#クラスを生成する機能も持っています。
  • Json.NET Schema: 有名なJSONライブラリ「Json.NET」の拡張機能です。JSON.NETと連携して、JSONデータの読み込みと同時にスキーマ検証を行うことができます。
  • Corvus.JsonSchema: 高速で、アロケーションを抑えたJSON Schema検証に特化したライブラリです。C#のソースジェネレーターを活用し、スキーマからC#のコードを直接生成することで、パフォーマンスを最適化します。

これらのライブラリは、NuGetパッケージマネージャーを使ってプロジェクトに追加できます。

Javaの場合​

Javaでは、多くのライブラリが利用できます。

  • networknt/json-schema-validator: 最新のJSON Schema仕様をサポートし、高速な検証が特徴です。多くのフレームワークやプロジェクトで採用されています。
  • everit-org/json-schema: JSON Schemaの仕様に準拠しており、安定した検証機能を提供します。
  • justinrainbow/json-schema: PHPのJSON Schemaライブラリから派生したもので、シンプルで使いやすいAPIを提供します。

これらのライブラリは、MavenやGradleといったビルドツールを通じて依存関係に追加するのが一般的です。

これらのライブラリを利用することで、C#やJavaのアプリケーションでも、データの整合性を保ち、安全な処理を実現できます。

この動画では、C#で高性能なJSONスキーマ検証を行うCorvus.JsonSchemaライブラリについて解説しています。 High-Performance JSON Schema Validation in C# with Corvus.JsonSchema http://googleusercontent.com/youtube_content/0

JSON Schemaの仕様について教えて​

JSON Schemaは、JSONドキュメントの構造を定義し、検証するための標準仕様です。仕様は、IETF (Internet Engineering Task Force) のドラフトとして開発が進められており、定期的に新しいバージョン（ドラフト）が公開されています。

主要な仕様​

JSON Schemaの仕様は、主にCoreとValidationの2つの部分に分かれています。

1. Core (コア)​

JSON Schemaの基本的な構造と、スキーマ自体を扱うための仕組みを定義します。

  • $schema: スキーマがどのドラフトの仕様に準拠しているかを宣言するためのキーワードです。バリデーションライブラリがどのルールセットを使うべきかを判断するために重要です。
  • $id: スキーマに一意の識別子（URI）を与えます。これにより、他のスキーマやドキュメントからこのスキーマを参照できるようになります。
  • $ref: 別のスキーマや、スキーマ内の特定の部分を参照するためのキーワードです。これにより、スキーマをモジュール化し、再利用することができます。
  • $defs (または以前のdefinitions): スキーマ内で再利用可能なサブスキーマを定義するためのキーワードです。

2. Validation (バリデーション)​

JSONデータの検証ルールを定義するためのキーワード集です。

  • データ型 (type): string, number, integer, boolean, array, object, null などの基本的なデータ型を指定します。
  • 数値の制約: minimum, maximum, exclusiveMinimum, exclusiveMaximum で数値の範囲を定義します。multipleOf を使うと、特定の数値で割り切れるかどうかをチェックできます。
  • 文字列の制約: minLength, maxLength で文字数を、pattern で正規表現によるパターンを定義します。format を使うと、email や uri などの一般的な形式を検証できます。
  • 配列の制約: minItems, maxItems で要素の数を定義します。uniqueItems を true にすると、配列内のすべての要素が一意である必要があります。
  • オブジェクトの制約: properties でプロパティ（キー）ごとのスキーマを定義し、required で必須のプロパティを指定します。additionalProperties: false を設定すると、定義されていないプロパティの追加を禁止できます。
  • 論理演算子: allOf, anyOf, oneOf, not といったキーワードで、複数のサブスキーマを組み合わせて複雑な検証ルールを作成できます。
  • 条件付きサブスキーマ: if, then, else を使って、特定の条件に応じて異なるスキーマを適用できます。

JSON Schemaのバージョン（ドラフト）​

JSON Schemaは、過去にいくつかのバージョンが公開されています。

  • Draft 4: 以前は広く使われていましたが、現在は古いバージョンと見なされています。
  • Draft 6, 7: より多くのキーワードや機能が追加されました。
  • 2019-09 / 2020-12: 最新の主要なバージョンです。日付ベースの命名規則に変更され、より明確なボキャブラリーと新しい機能が導入されました。

多くのバリデーションライブラリは最新のドラフトに対応していますが、古いドラフトのスキーマもサポートしている場合があります。スキーマを書く際は、どのドラフトを使うかを明確に指定することが推奨されます。

最新のバージョンは？​

JSON Schemaの最新バージョンは、2020-12です。

これは、IETF (Internet Engineering Task Force) のドラフトとして公開されており、JSON Schemaの公式ウェブサイトでも最新の安定版として推奨されています。

過去のバージョンとの主な違い​

  • 命名規則: 以前のバージョンは「Draft 4」や「Draft 7」のように通し番号で呼ばれていましたが、最新バージョンからは 2019-09 や 2020-12 のように公開された日付で呼ばれるようになりました。
  • 新キーワードの追加:
    • $vocabulary: スキーマが使用するボキャブラリー（キーワードのセット）を明示的に宣言できるようになりました。
    • prefixItems: 配列の最初の数個の要素に個別のスキーマを適用するitemsキーワードの新しい代替です。
    • unevaluatedProperties/unevaluatedItems: allOfなどで結合された複数のサブスキーマを処理する際に、評価されていないプロパティやアイテムに制約を課すためのキーワードです。これにより、より複雑なスキーマの結合が可能になりました。