Python module - jsonschema Part 3

Posted on  Mar 28, 2018  in  Python 模組/套件推薦  by  Amo Chen  ‐ 3 min read

本文為 Python module - jsonchema 一系列教學文:

Python module - jsonschema Part 2 中介紹了 number , string , array , object 等型別的複雜用法,不過絕大多數仍是單一型別資料驗證的用法,然而實際上 JSON 資料的格式可能會由多種資料型別混合而成,例如 array 裡的元素是 objectobject 裡又有可能是 object 的情況,例如以下的 JSON 資料:

[
    {
        "user_id": 1,
        "preference": {
            "cooking": True,
            "fishing": False,
        }
    },
    {
        "user_id": 1,
        "preference": {
            "cooking": True,
            "fishing": False,
        }
    },
]

本篇將介紹如何撰寫符合實際使用以及更好維護的 JSON Schema 。

definitions$ref

不同的 JSON 資料格式中常會出現一些共用的結構,JSON Schema 也提供 definitions 關鍵字供我們把這些共用的 JSON 格式集中管理,所有需要該格式的 JSON Schema 只要透過 $ref 關鍵字引用即可。

例如以下範例把 preference 的定義放到 definitions 中,然後透過 $ref 引用該 JSON Schema :

schema = {
    'definitions': {
        'preference': {
            'type': 'object',
            'properties': {
                'cooking': {
                    'type': 'boolean',
                },
                'fishing': {
                    'type': 'boolean',
                },
            },
            'additionalProperties': False,
        }
    },
    'type': 'array',
    'items': {
        'type': 'object',
        'properties': {
            'user_id': {
                'type': 'integer',
            },
            'preference': {
                '$ref': '#/definitions/preference',
            },
        }
    }
}

$ref 所使用的 #/definitions/preference 指的是參考 # 當前這份 JSON Schema 文件底下的 definitions 所屬的 preference ,每往下一個層級就必須用 / 分隔。

The pound symbol ( # ) refers to the current document, and then the slash (/) separated keys thereafter just traverse the keys in the objects in the document.

p.s. 這種引用法被稱為 JSON Pointer

object 與 object 混合

學會 definitions$ref 之後,就能夠輕鬆地組合各種 JSON 格式。

例如以下是 object 中包含 object 的範例:

user_schema = {
    'definitions': {
        'meta': {
            'type': 'object',
            'properties': {
                'gender': {
                    'type': 'string',
                },
                'twitter': {
                    'type': 'string',
                },
            },
            'additionalProperties': False,
        }
    },
    'type': 'object',
    'properties': {
        'username': {
            'type': 'string',
        },
        'password': {
            'type': 'string',
        },
        'meta': {
            '$ref': '#/definitions/meta',
        }
    },
    'additionalProperties': False,
}

上述範例要驗證的 JSON 資料範例,如以下所示,可以看到 object 裡的 meta 又包含一個 object 的情況:

{
    'username': 'foo',
    'password': 'bar',
    'meta': {
        'gender': 'male',
        'twitter': 'foobar'
    }
}

array 與 object 混合

arrayobject 混合的型式常見於列表型的資料,例如搜尋結果就很有可能是 array 包含多個 object

以下範例為模擬搜尋結果的 JSON 資料:

results = [
    {
        'title': 'foo',
        'link': 'https://example.com/',
        'summary': 'this is summary',
        'keywords': ['a', 'b', 'c']
    },
    {
        'title': 'bar',
        'link': 'https://example.com/',
        'summary': 'this is summary',
        'keywords': ['d', 'e', 'f']
    },
]

知道資料的樣貌之後,可以進一步化為 JSON Schema ,上述的資料可以把搜尋結果的結構與 keywords 放到 definitions

schema = {
    'definitions': {
        'keywords': {
            'type': 'array',
            'items': {
                'type': 'string'
            }
        },
        'search_result': {
            'type': 'object',
            'properties': {
                'title': {
                    'type': 'string'
                },
                'link': {
                    'type': 'string'
                },
                'summary': {
                    'type': 'string'
                },
                'keywords': {
                    '$ref': '#/definitions/keywords'
                },
            }
        }
    },
    'type': 'array',
    'items': {
        '$ref': '#/definitions/search_result'
    }
}

上述 JSON Schema 可以看到 definitions 裡分別定義 2 種 JSON Schema( keywords 與 search_result ),其中 search_result 裡的 keywords 又指向到 definitions 底下的 keywords 。

而最外層的 'type': 'array''items': {'$ref': '#/definitions/search_result'} 代表此 JSON Schema 是一個元素都是 search_result 的 array 。

以上就是 arrayobject 混用的情況。

多種格式擇一( oneOf

JSON Schema 更提供 oneOf anyOf allOf not 等關鍵字,讓我們可以更加彈性地驗證 JSON 格式。以下舉比較常用到的 oneOf 為例,以下的 JSON Schema 為 integerstring 2 種格式擇一即可:

schema = {
    'oneOf': [
        {'type': 'string'},
        {'type': 'integer'},
    ]
}

因此當遇到非 stringinteger 型別的資料時,就會驗證不過:

import jsonschema

# pass
jsonschema.validate(123, schema)

# pass
jsonschema.validate('123', schema)

# failed
jsonschema.validate(['foo', 'bar'], schema)

以上就是 oneOf 的用法, anyOf allOf not 等關鍵字的用法可以參閱 Combining schemas

總結

在以 JSON 作為資料交換格式主流之一的今日,仍可以期待 JSON Schema 未來發展,也蠻推薦 API 可以利用 JSON Schema 進行格式驗證,減少撰寫驗證資料程式碼的成本。此外,眼尖的人也許會發現 JSON Schema 與 OpenAPI(Swagger)很相似,這是因為 OpenAPI 的制定也有參考 JSON Schema ,因此學會 JSON Schema 之後對 OpenAPI 的學習也有相當助益。

以上, Happy Coding!

References

http://json-schema.org/

https://spacetelescope.github.io/understanding-json-schema/index.html

對抗久坐職業傷害

研究指出每天增加 2 小時坐著的時間,會增加大腸癌、心臟疾病、肺癌的風險,也造成肩頸、腰背疼痛等常見問題。

然而對抗這些問題,卻只需要工作時定期休息跟伸展身體即可!

你想輕鬆改變現狀嗎?試試看我們的 PomodoRoll 番茄鐘吧! PomodoRoll 番茄鐘會根據你所設定的專注時間,定期建議你 1 項辦公族適用的伸展運動,幫助你打敗久坐所帶來的傷害!

贊助我們的創作

看完這篇文章了嗎? 休息一下,喝杯咖啡吧!

如果你覺得 MyApollo 有讓你獲得實用的資訊,希望能看到更多的技術分享,邀請你贊助我們一杯咖啡,讓我們有更多的動力與精力繼續提供高品質的文章,感謝你的支持!