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:用來描述資料的型態,分別有 stringnumberobjectarraybooleannull
  • properties:用來定義該階層的資料內容
  • formatstring 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 可以參考。

Categories: DataStructure