JSON スキーマ (モード)

JSON スキーマは、JSON データ構造を記述および検証するための強力なツールです. JSON スキーマを仕様と見なすことができます. この仕様は、JSON データの構造、キーの命名、値の型などを指定し、次の方法で検証できます.指定された JSON データを検証して、データの正確性を確保してください。したがって、インターフェイスのデバッグのプロセスでは、多くの場合、インターフェイス データの正確性を検証するために JSON スキーマが使用されます。

JSON スキーマとは

JSON スキーマは、IETF によって作成および起草された「JSON スキーマ」に変換されます。では、JSON スキーマは何をするのでしょうか?

IETF は The Internet Engineering Task Force の略で、「International Internet Engineering Task Force」と訳されている、大規模な公的非政府国際グループです。

次のように、JSON を使用して製品の情報を保存するとします。

 
{
    "id": 1,
    "name": "JSONチュートリアル",
    "author": "IT基礎",
    "price": 99.9
} 

上記のように、非常に単純な JSON データですが、「id」は何を意味するのか、「name」フィールドは省略できるのか、「price」フィールドの値は 0 にできるのか、等

JSON Schemaは、上記の問題を解決するために生まれました.JSON Schemaでは、JSONに表示されるフィールド、フィールドの意味、フィールドのタイプなどの情報を指定し、JSONデータがJSONで定義された仕様に準拠しているかどうかをJSON Schemaを使用して検証できます.スキーマ。

スキーマの定義

次の例に示すように、JSON スキーマ自体は JSON 形式のデータです。

 
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "name":  { "type": "string" },
        "email": { "type": "string" },
        "age": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": false
        },
        "telephone": {
            "type": "string",
            "pattern": "^(\\([0-9]{3}\\))?[0-9]{3}-[0-9]{4}$"
        }
    },
    "required": ["name", "email"],
    "additionalProperties": false
} 

上記のスキーマでは、JSON データは次の要件を満たす必要があります。

• タイプはオブジェクトです。
• 次の 4 つのキーを JSON に含めることができます。
  • name: 文字列型である必要があります。
  • email: 文字列型である必要があります。
  • age: 0 より大きい整数でなければなりません。
  • 電話: 文字列型である必要があり、指定された正規表現と一致する必要があります。
• 上記の 4 つのキーのうち、名前と電子メールは定義する必要がありますが、年齢と電話番号はオプションです。
• 上記の 4 つのキーを除き、他のキーは使用できません。

以下は、上記のスキーマに準拠する JSON データです。

 
{
    "name": "IT基礎",
    "email": "admin@it-kiso.com",
    "age": 18
} 

JSON が string、number、object、array、boolean、null などのいくつかの型をサポートしていることは誰もが知っています. さまざまな型に対して、Schema は一連のキーワードを提供します. これらのキーワードとその使用法を紹介しましょう:

1) 文字列 (文字列)

JSON スキーマの文字列に関連するキーワードを次の表に示します。

キーワード	説明	オプション値
最小の長さ	文字列の最小長。負にすることはできません
最大長	文字列の最大長。負にすることはできません
パターン	正規表現
フォーマット	文字列形式	「日時」: 2018-11-13T20:20:39+00:00 などの日付と時刻 “time”: 20:20:39+00:00 などの時刻 「日付」: 2018-11-13 などの日付 「メール」：メールアドレス 「ホスト名」: ホスト名 “ipv4”: IPv4 アドレス “ipv6”: IPv6 アドレス 「uri」: ユニバーサル リソース識別子 (URI) “uri-template”: URI テンプレート (任意のレベル) “regex”: 正規表現

2) 数値型

JSON スキーマの数値に関連するキーワードを次の表に示します。

キーワード	説明	例
整数	整数	{“型”: “整数”}
番号	整数と浮動小数点数を含む数値	{“タイプ”: “番号”}
複数の	数値は、指定された数値の倍数でなければなりません (正の数値)	{“タイプ”: “数”, “multipleOf”: 3}
最小	値に許可される最小値	{“タイプ”: “数”, “最小”: 1}
最大	許容される最大値	{“タイプ”: “数”, “最大”: 9}

3) オブジェクト

プロパティ

JSON スキーマでは、次の例に示すように、properties キーワードを使用して JSON データのキーを定義できます。

 
{
    "type": "object",
    "properties": {
        "name": { "type": "string"},
        "age": {"type": "number", "multipleOf": 3},
        "date": {
            "type": "string",
            "format": "date"
        }
    }
} 

追加プロパティ (追加プロパティ)

JSON スキーマでは、次の例に示すように、 additionalPropertiesis を使用して、値が false またはスキーマ オブジェクトの追加プロパティを定義できます。

 
{
    "type": "object",
    "properties": {
        "number": { "type": "number"},
        "street_name": { "type": "string"},
        "street_type": {
            "type": "string",
            "enum": ["Street", "Avenue", "Boulevard"]
        }
    },
    "additionalProperties": { "type": "string"}
} 

必須プロパティ

In JSON Schema, you can use the required keyword to declare the keys that must be defined in JSON. required の値は配列であり、次の例に示すように、配列内の各値は一意である必要があります。

 
{
    "type": "object",
    "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" },
        "address": { "type": "string" },
        "telephone": { "type": "string" }
    },
    "required": ["name", "email"]
} 

プロパティ名

JSON スキーマでは、次の例に示すように、propertyNames を使用して JSON データ内のキーの命名規則を定義できます。

 
{
    "type": "object",
    "propertyNames": {
        "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
    }
} 

属性の数 (サイズ)

JSON スキーマでは、次の例に示すように、minProperties (最小数) および maxProperties (最大数) キーワードを使用して、JSON オブジェクト内のキーの数を制限できます。

 
{
    "type": "object",
    "minProperties": 2,
    "maxProperties": 3
} 

4) 配列

配列は順序付けられた値のコレクションであり、JSON 配列の各値は異なる型にすることができます。

要素（アイテム）

By default, the value of the array can be of any type, but in JSON Schema, you can use the items, additionalItems and contains keyword to validate the value in the array. JSON の配列の場合、通常は次の 2 つの検証方法があります。

• リスト検証: 任意の長さの配列。配列内の各値は同じスキーマに一致します。
• タプル検証: 固定長の配列。配列内の各値は異なるスキーマと一致できます。

リストの検証

配列内のすべての値を同じパターンに一致させたい場合は、items キーワードで単一のパターンを設定して、配列内のすべての値を検証できます。次の例に示すように、単一のスキーマを使用する場合、 additionalItems キーワードは無効です (配列のすべての値を数値として検証します)。

 
{
    "type": "array",
    "items": {
        "type": "number"
    }
} 

次の例のように、contains キーワードは、配列内の 1 つ以上の項目に対してのみ検証する必要があります (少なくとも 1 つの数値要素を含める必要があるだけです)。

 
{
    "type": "array",
    "contains": {
        "type": "number"
    }
} 

タプルの検証

JSON データでは、配列の各値が異なる意味を持つ場合、これらの値の型も異なる場合があります。次に例を示します。

[番号、通りの名前、通りの種類、方向]

このために、スキーマでは、次のように JSON データを検証できます。

 
{
    "type": "array",
    "items": [
        {
            "type": "number"
        },
        {
            "type": "string"
        },
        {
            "type": "string",
            "enum": ["Street", "Avenue", "Boulevard"]
        },
        {
            "type": "string",
            "enum": ["NW", "NE", "SW", "SE"]
        }
    ]
} 

配列の長さ (長さ)

配列の長さは、minItems、maxItems キーワードを使用して指定できます。次の例に示すように (指定された配列の長さの範囲は 2 ~ 3):

 
{
    "type": "array",
    "minItems": 2,
    "maxItems": 3
} 

注: 配列の長さを負にすることはできません。

独自性

次の例に示すように、uniqueItems キーワードを true に設定すると、配列内の各要素が一意になります。

 
{
    "type": "array",
    "uniqueItems": true
} 

5) ブール値

次の例に示すように、ブール型には true と false の 2 つの値しかありません。

{“タイプ”: “ブール値”}

6) 空の値 (null)

空の型は通常、値が存在しないことを示すために使用されます。値の型が null として指定されている場合、次の例に示すように、値の型が null として指定されていることを意味します。

{“タイプ”: “null”}

7) 一般的なキーワード

JSON スキーマには、緩やかな検証のためのいくつかの一般的なキーワード、タイトル、説明、デフォルト、および例が含まれています. これらのキーワードは、主にスキーマの機能と機能を説明するために使用されます.これらの注釈属性は必須ではありませんが、推奨されます。

• タイトルと説明のキーワードは文字列でなければなりません。「タイトル」は短いほうがよく、「説明」はスキーマに関する詳細な説明を提供する必要があります。
• default キーワードは、デフォルト値を定義するために使用されます。
• 例のキーワードは、スキーマに対して検証する例のリストを提供するために使用されます。

次の例に示すように:

 
{
    "title": "Match anything",
    "description": "This is a schema that matches anything.",
    "default": "Default value",
    "examples": ["Anything", 4035]
} 

コメント

$comment キーワードはコメント/注釈を追加するために使用され、その値は文字列でなければなりません。

列挙値

enum キーワードは、列挙値 (値の固定セット) を定義するために使用されます。これは、少なくとも 1 つの値を含む配列である必要があり、各値は一意である必要があります。さらに、次の例に示すように、type と enum は並列であり、同時に満たす必要があります。

 
{
    "type": "string",
    "enum": ["red", "amber", "green"]
} 

定数値

const キーワードは、次の例に示すように、定数値を定義するために使用されます。

 
{
    "properties": {
        "country": {
            "const": "United States of America"
        }
    }
} 

const は enum のシンタックス シュガーであるため、次の 2 つの定義は同等です。

 
{ "const": "United States of America" }
{ "enum": [ "United States of America" ]} 

8) $schema キーワード

$schema キーワードは、JSON スキーマのバージョンを宣言するために使用されます。次の例に示すように、すべての JSON スキーマで $schema を宣言し、スキーマの最初のキーと値のペアにすることをお勧めします。

 
{"$schema": "http://json-schema.org/draft-04/schema#"} 

特定のバージョンの JSON スキーマを宣言する必要がある場合は、$schema の値を次のように設定できます。

• http://json-schema.org/draft-07/schema#
• http://json-schema.org/draft-06/schema#
• http://json-schema.org/draft-04/schema#

9) $ref キーワード

$ref キーワードは、別の場所にあるスキーマ フラグメントを参照するために使用され、その値は URI 参照です。同じドキュメントを参照するスキーマ フラグメントの場合、$ref の値はポンド記号 (#) で始まる必要があります。次に例を示します。

{ “$ref”: “#/定義/アドレス” }

上記の例の「#/definitions/address」は、次のことを意味します。

• ドキュメントのルートに移動します。
• 「definitions」キーの値を見つけます。
• そのオブジェクトで、キー「アドレス」の値を見つけます。

別のスキーマ ファイルを参照する場合は、次のようにします。

{ “$ref”: “definitions.json#/アドレス” }

完全な例は次のようになります。

 
{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "definitions": {
        "address": {
            "type": "object",
            "properties": {
                "street_address": { "type": "string" },
                "city": { "type": "string" },
                "state": { "type": "string" }
            },
            "required": ["street_address", "city", "state"]
        }
    },
    "type": "object",
    "properties": {
        "billing_address": { "$ref": "#/definitions/address" },
        "shipping_address": { "$ref": "#/definitions/address" }
    }
} 

$ref キーワードを使用すると、現在のスキーマの一部を参照することもできます (プログラミングの再帰に似ています)。たとえば、次の例に示すように、配列 children を含む person スキーマがあり、各配列は person インスタンスでもあるとします。

 
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "definitions": {
        "person": {
            "type": "object",
            "properties": {
                "name": { "type": "string" },
                "children": {
                    "type": "array",
                    "items": { "$ref": "#/definitions/person" },
                    "default": []
                }
            }
        }
    },
    "type": "object",
    "properties": {
        "person": { "$ref": "#/definitions/person" }
    }
} 

10) $id キーワード

$id キーワードの値は URI 参照であり、次の 2 つの目的に役立ちます。

• スキーマの一意の識別子を宣言します。
• $ref を参照できるベース URI を宣言します。

たとえば、https://it-kiso.com/ ドメイン名のスキーマを参照したい場合、次のように $id を設定できます。

{ “$id”: “https://it-kiso.com/schemas/address.json” }

上記の $id を定義した後、$ref を使用して同じドメイン名の他のスキーマを参照する場合は、次のように省略できます。

{ “$ref”: “person.json” }

JSON スキーマを理解したら、それを使用して JSON データを検証できます。インターネットには多くの JSON スキーマ ライブラリがあり、 JSON スキーマの公式 Web サイトで適切なライブラリを見つけることができます。

サードパーティのライブラリを使用するだけでなく、スキーマはhttps://jsonschemaint.com/#!/version/draft-04/markup/jsonなどのオンライン ツールでも使用できます。