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
裡的元素是 object
, object
裡又有可能是 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 混合
array
與 object
混合的型式常見於列表型的資料,例如搜尋結果就很有可能是 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 。
以上就是 array
與 object
混用的情況。
多種格式擇一( oneOf
)
JSON Schema 更提供 oneOf
anyOf
allOf
not
等關鍵字,讓我們可以更加彈性地驗證 JSON 格式。以下舉比較常用到的 oneOf
為例,以下的 JSON Schema 為 integer
與 string
2 種格式擇一即可:
schema = {
'oneOf': [
{'type': 'string'},
{'type': 'integer'},
]
}
因此當遇到非 string
或 integer
型別的資料時,就會驗證不過:
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