はじめに

初めてのスキーマの作成

JSON Schemaは、JSONドキュメントに注釈を付けたり、検証したりするために使用できるボキャブラリーです。このチュートリアルでは、JSON Schemaを作成するプロセスを説明します。

JSON Schemaを作成した後、選択した言語のバリデーターを使用して、スキーマに対してサンプルデータを検証できます。ツールにアクセスして、ニーズに合ったバリデーターを選択してください。

JSON Schemaの作成方法をすでに理解しており、スキーマ生成、コード生成、ドキュメント、UI生成、JSON Schema処理または変換など、さまざまなJSON Schemaユースケースを探している場合は、ツールにアクセスして、JSON Schemaエコシステムで利用可能な素晴らしいツールをご確認ください。

メニューアイコン目次

概要

このガイドで使用されている例は、次のようなJSONオブジェクトを使用してデータを格納する製品カタログです。

データ
```json

カタログ内の各製品には、以下の情報が含まれています。

  • productId: 製品の識別子
  • productName: 製品名
  • price: 消費者への価格
  • tags: 識別タグのオプションの配列

JSONオブジェクトは人間が読解可能ですが、コンテキストやメタデータは含まれていません。オブジェクトを見ても、キーの意味や入力可能な値が何であるかを判断することはできません。JSON Schemaは、これらの疑問に対する回答を提供するための標準です。このガイドでは、JSONデータの構造、制約、およびデータ型を記述するJSON Schemaドキュメントを作成します。

JSON Schema入門

インスタンスは検証または記述されるJSONドキュメントであり、スキーマは記述を含むドキュメントです。

最も基本的なスキーマは空のJSONオブジェクトです。これは何も制約せず、すべてを許可し、何も記述しません。

データ
{}

スキーマに検証キーワードを追加することで、インスタンスに制約を適用できます。たとえば、typeキーワードを使用して、インスタンスをオブジェクト、配列、文字列、数値、ブール値、またはnullに制約できます。

データ
```json

JSON Schemaはハイパーメディアに対応しており、既存のJSONベースのHTTP APIに注釈を付けるのに最適です。JSON SchemaドキュメントはURIによって識別されます。URIは、HTTPリンクヘッダーおよびJSON Schemaドキュメント内で使用して、再帰的な定義を可能にします。

スキーマ定義の作成

基本的なスキーマ定義を作成するには、次のキーワードを定義します。

  • $schema: スキーマが準拠するJSON Schema標準のドラフトを指定します。
  • $id: スキーマのURIを設定します。この一意のURIを使用して、同じドキュメント内または外部JSONドキュメントからスキーマの要素を参照できます。
  • titleおよびdescription: スキーマの意図を記述します。これらのキーワードは、検証されるデータに制約を追加しません。
  • type: JSONデータの最初の制約を定義します。以下の製品カタログの例では、このキーワードはデータがJSONオブジェクトでなければならないことを指定しています。

例えば

スキーマ
```json

キーワードはJSONキーを使用して定義されます。通常、検証されるデータはJSONデータドキュメントに含まれていますが、JSON Schemaは、テキストファイルやXMLファイルなど、他のコンテンツタイプに含まれるJSONデータも検証できます。

JSON Schemaの用語では、$schemaと$idはスキーマキーワード、titleとdescriptionはスキーマアノテーション、そしてtypeはバリデーションキーワードです。

プロパティを定義する

このセクションでは、propertiesキーワードを追加します。JSON Schemaの用語では、propertiesはバリデーションキーワードです。propertiesを定義すると、バリデーション対象のJSONデータの各キーを表すプロパティを持つオブジェクトを作成します。また、オブジェクトで定義されたどのプロパティが必須であるかを指定することもできます。

propertiesオブジェクトを追加する

製品カタログの例を使用すると、productIdは製品を一意に識別する数値です。これは製品の正式な識別子であるため、必須です。

スキーマにpropertiesオブジェクトを追加するには

  1. スキーマの末尾にpropertiesバリデーションキーワードを追加します

    1 ...
2   "title": "Product",
3   "description": "A product from Acme's catalog",
4   "type": "object",
5   "properties": {
6     "productId": {}
7   }

  2. 以下のスキーマアノテーションと共に、productIdキーワードを追加します

    • description: productIdが何であるかを説明します。この場合、製品の一意の識別子です。

    • type: 期待されるデータの種類を定義します。この例では、製品識別子は数値であるため、integerを使用します。

      1...
2  "properties": {
3    "productId": {
4      "description": "The unique identifier for a product",
5      "type": "integer"
6    }
7  }

新しいpropertiesバリデーションキーワードを使用すると、スキーマ全体は次のようになります

スキーマ
(JSON スキーマのコードはそのままです)

次の例では、別の必須キーであるproductNameを追加します。この値は文字列です。

スキーマ
```json

properties オブジェクトには、productId と productName の2つのキーが含まれています。JSONデータがこのスキーマに対して検証されると、これらのフィールドのいずれかに無効なデータが含まれているドキュメントは検証に失敗します。

必須プロパティの定義

このセクションでは、特定のプロパティを必須にする方法について説明します。この例では、既存の2つのキーを必須にし、price という名前の別の必須キーを追加します。price キーには、他のキーと同様に description と type がありますが、最小値も指定されています。ストアには無料のものはないため、各製品には0を超える価格値が必要です。exclusiveMinimum 検証キーワードを使用してこれを定義します。

必須プロパティを定義するには

  1. properties オブジェクトの中に、price キーを追加します。通常のスキーマアノテーションである description と type を含め、type は数値にします。

    1   "properties": {
2     ...
3     "price": {
4       "description": "The price of the product",
5       "type": "number"
6     }
7   }

  2. exclusiveMinimum 検証キーワードを追加し、値をゼロに設定します。

    1   "price": {
2     "description": "The price of the product",
3     "type": "number",
4     "exclusiveMinimum": 0
5   }

  3. required 検証キーワードを、スキーマの末尾、properties オブジェクトの後に追加します。配列に productID、productName、そして新しい price キーを追加します。

    1 ...
2   "properties": {
3     ...
4     "price": {
5       "description": "The price of the product",
6       "type": "number",
7       "exclusiveMinimum": 0
8     },
9   },
10   "required": [ "productId", "productName", "price" ]

新しい required キーワードと price キーを追加した後のスキーマ全体は、以下のようになります。

スキーマ
{ "$schema": "https://json-schema.dokyumento.jp/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "productId", "productName", "price" ]}

exclusiveMinimum 検証キーワードはゼロに設定されているため、ゼロより大きい値のみが有効とみなされます。ゼロを有効なオプションとして含めるには、代わりに minimum 検証キーワードを使用することができます。

オプションのプロパティを定義する

このセクションでは、オプションのプロパティを定義する方法について説明します。この例では、以下の基準を使用して tags という名前のキーワードを定義します。

  • tags キーワードはオプションです。
  • tags が含まれる場合、少なくとも1つのアイテムが含まれている必要があります。
  • すべてのタグは一意である必要があります。
  • すべてのタグはテキストである必要があります。

オプションのプロパティを定義するには

  1. properties オブジェクトの中に、tags キーワードを追加します。通常のスキーマアノテーションである description と type を含め、type を配列として定義します。

    1 ...
2   "properties": {
3     ...
4     "tags": {
5       "description": "Tags for the product",
6       "type": "array"
7     }
8   }

  2. 配列に何が表示されるかを定義するために、items の新しい検証キーワードを追加します。たとえば、string です。

    1 ...
2     "tags": {
3       "description": "Tags for the product",
4       "type": "array",
5       "items": {
6         "type": "string"
7       }
8     }

  3. 配列に少なくとも1つのアイテムがあることを確認するには、minItems 検証キーワードを使用します。

    1 ...
2     "tags": {
3       "description": "Tags for the product",
4       "type": "array",
5       "items": {
6         "type": "string"
7       },
8       "minItems": 1
9     }

  4. 配列内のすべてのアイテムが一意であることを確認するには、uniqueItems 検証キーワードを使用し、それを true に設定します。

    1 ...
2     "tags": {
3       "description": "Tags for the product",
4       "type": "array",
5       "items": {
6         "type": "string"
7       },
8       "minItems": 1,
9       "uniqueItems": true
10     }

新しい tags キーワードを追加した後のスキーマ全体は、以下のようになります。

スキーマ
{ "$schema": "https://json-schema.dokyumento.jp/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true } }, "required": [ "productId", "productName", "price" ]}

新しいキーワードは必須ではないため、required セクションには変更がありません。

ネストされたデータ構造を作成する

これまでの例では、1つのレベルのみを持つフラットなスキーマについて説明しました。このセクションでは、JSONスキーマでネストされたデータ構造を使用する方法について説明します。

ネストされたデータ構造を作成するには

  1. properties オブジェクトの中に、dimensions という名前の新しいキーを作成します。

    1 ...
2   "properties": {
3   ...
4     "dimensions": {}
5   }

  2. type 検証キーワードを object として定義します。

    1 ...
2   "dimensions": {
3     "type": "object"
4   }

  3. ネストされたデータ構造を格納するために、properties 検証キーワードを追加します。新しい properties キーワードの中に、すべて number タイプを使用する length、width、height のキーワードを追加します。

    1 ...
2   "dimensions": {
3     "type": "object",
4     "properties": {
5       "length": {
6         "type": "number"
7       },
8       "width": {
9         "type": "number"
10       },
11       "height": {
12         "type": "number"
13       }
14     }
15   }

  4. これらの各プロパティを必須にするには、dimensions オブジェクトの中に required 検証キーワードを追加します。

    1 ...
2   "dimensions": {
3     "type": "object",
4     "properties": {
5       "length": {
6         "type": "number"
7       },
8       "width": {
9         "type": "number"
10       },
11       "height": {
12         "type": "number"
13       }
14     },
15     "required": [ "length", "width", "height" ]
16 }

新しいネストされたデータ構造を使用したスキーマ全体は、以下のようになります。

スキーマ
{ "$schema": "https://json-schema.dokyumento.jp/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "dimensions": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] } }, "required": [ "productId", "productName", "price" ]}

新しい required 検証キーワードは、dimensions キーのスコープ内でのみ適用されます。

外部参照を追加する

このセクションでは、スキーマの外部にあるリソースを参照する方法について説明します。多くのデータ構造でスキーマを共有することは、スキーマを使いやすく、読みやすく、最新の状態に保つための一般的な方法です。これまでのところ、製品カタログスキーマは自己完結型です。このセクションでは、新しいスキーマを作成し、それを製品カタログスキーマで参照します。

以下のスキーマは、地理的な場所を検証します。

スキーマ
{ "$id": "https://example.com/geographical-location.schema.json", "$schema": "https://json-schema.dokyumento.jp/draft/2020-12/schema", "title": "Longitude and Latitude", "description": "A geographical coordinate on a planet (most commonly Earth).", "required": [ "latitude", "longitude" ], "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }}

このスキーマを製品カタログスキーマで参照するには

  1. properties オブジェクトの中に、warehouseLocation という名前のキーを追加します。

    1 ...
2   "properties": {
3   ...
4     "warehouseLocation": {}
5   }

  2. 外部の地理的位置スキーマにリンクするには、$ref スキーマキーワードとスキーマURLを追加します。

    1 ...
2   "warehouseLocation": {
3     "description": "Coordinates of the warehouse where the product is located.",
4     "$ref": "https://example.com/geographical-location.schema.json"
5   }

外部スキーマ参照を追加した後のスキーマ全体は、以下のようになります。

スキーマ
{ "$schema": "https://json-schema.dokyumento.jp/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "dimensions": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] }, "warehouseLocation": { "description": "Coordinates of the warehouse where the product is located.", "$ref": "https://example.com/geographical-location.schema.json" } }, "required": [ "productId", "productName", "price" ]}

JSONデータをスキーマに対して検証する

JSONスキーマを作成したので、JSONスキーマバリデーターを使用してJSONデータをスキーマに対して検証します。

バリデーターは、JSONスキーマ仕様を実装したツールです。すべてのバリデーターは同様の方法で動作します。JSONスキーマとJSONインスタンスを入力として受け取り、検証結果を出力として返します。

How JSON Schema works

実際に試してみるには、「ツール」にアクセスして、ニーズに合ったバリデーターを選択するか、以下のエディターを使用してさまざまなスキーマとインスタンスを探索し、さまざまな検証結果を確認してください。

JSONスキーマ

1

JSONインスタンス

1

検証結果

red cross

次にすること

JSONスキーマを作成し、それを使用してJSONデータを検証する方法がわかったので、JSONスキーマの学習を続けていきましょう。

  • リファレンスドキュメントにアクセスして、JSONスキーマの詳細をご覧ください。
  • 仕様の最新バージョン（2020-12）の詳細をご覧ください。

JSON Schemaの作成方法をすでに理解しており、スキーマ生成、コード生成、ドキュメント、UI生成、JSON Schema処理または変換など、さまざまなJSON Schemaユースケースを探している場合は、ツールにアクセスして、JSON Schemaエコシステムで利用可能な素晴らしいツールをご確認ください。

ヘルプが必要ですか？

このドキュメントは役に立ちましたか？

ドキュメントの改善にご協力ください！

JSONスキーマでは、ドキュメントへの貢献を他のあらゆる種類の貢献と同じくらい大切にしています！

Githubでこのページを編集する
貢献する方法を学ぶ

まだヘルプが必要ですか？

JSONスキーマの学習は、しばしば混乱を招きますが、心配しないでください。お手伝いします！

GitHubのコミュニティに質問する
Slackのコミュニティに質問する