JSON Schema

Version： draft-07

JSON（JavaScript Object Notation）眾所皆知是一種資料交換的格式，目前也很廣泛的在使用。但問題來了，當 JSON 結構複雜起來，包含裡面的資料型態、結構定義越來越模糊時，反而最造成溝通上的困擾。

JSON Schema 就是為了解決這個問題而產生，JSON Schema 定義了 JSON 的型態，主要有幾個優點：

• 描述資料結構
• 描述資料型態
• 增加可讀性
• 可透過工具自動化驗證及測試

Basic Usage

假設以下為一般的 JSON 資料：

{
    "name": "Johnson",
    "age": "30",
    "address": "My home",
    "email": "johnsonlu@mail.com",
    "gender": "Male"
}

JSON Schema 就可以寫成：

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "number"},
        "address": {
            "type": "string",
            "minLength": 10,
            "maxLength": 50,
        },
        "email": {
            "type": "string",
            "format": "email"
        },
        "gender": {
            "type": "string",
            "enum": ["Male", "Female"]
        }
    },
    "required": ["name", "email"]
}

這邊有用到幾個 keyword：

• $schema：用來定義這是 JSON Schema 的 JSON 格式
• type：用來描述資料的型態，分別有 string、number、object、array、boolean、null
• properties：用來定義該階層的資料內容
• format： string type 中用來定義格式的 keyword
• enum：用來宣告列舉的資訊
• required: 定義必要欄位

Notice： string 的部份可能比較會常遇到較複雜的設定，可以直接參考 官方文件 使用。

Advanced Usage

JSON Schema 的操作不只這些，甚至還可以定義結構並重複使用。

假設以下為一般的 JSON 資料：

{
    "business_supervisor": {
        "name": "Johnson",
        "age": "30",
        "address": "My home",
        "email": "johnsonlu@mail.com",
        "gender": "Male"
    },
    "admin_supervisor": {
        "name": "Maple",
        "age": "35",
        "address": "Her home",
        "email": "maple@mail.com",
        "gender": "Female"
    }
}

JSON Schema 就可以寫成：

{
    "$schema": "http://json-schema.org/draft-07/schema#",

    "definitions": {
        "info": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "number"},
                "address": {
                    "type": "string",
                    "minLength": 10,
                    "maxLength": 50,
                },
                "email": {
                    "type": "string",
                    "format": "email"
                },
                "gender": {
                    "type": "string",
                    "enum": ["Male", "Female"]
                }
            },
            "required": ["name", "email"]
        }
    },

    "type": "object",
    "properties": {
        "business_supervisor": {"$ref": "#/definitions/info"},
        "admin_supervisor": {"$ref": "#/definitions/info"}
    }
}

進階用法用到的 keyword：

• $ref：可以透過 definitions 定義結構，再透過 $ref reuse

Validators

JSON Schema 官方也提供了許多不同語言的 Validators 以供驗證。

另外也有線上版 Validators 可以參考。