JSON Schema及其用法

本篇主要介绍JSON Schema的基本语法，必要时会使用python代码来验证。

  JSON Schema是一种用于描述JSON数据的规范，可以用来定义JSON数据对象的结构、格式和约束条件。通过JSON Schema，可以对JSON数据进行验证、校验和文档化，确保数据的正确性和完整性。

1 Json Schema基本语法

  JSON Schema能校验JSON数据，但JSON Schema本身也是一种JSON结构。JSON Schema的基本语法中主要包括以下几个关键词：

关键词	说明
$schema	声明该模式是根据标准的特定草案编写的，主要用于版本控制，可省略；
$id	定义模式的URI，可省略；
title/description	描述和注释信息。不会对要校验的JSON数据。可省略；
type	数据类型。该关键字会定义JSON数据的第一个约束，只有当type取值为object时，才能指定该shema校验的为JSON数据；

具体举例如下：

from jsonschema import validate
schema={"type": "string"}
schema1={ "type":"object"}  
data={ "message": "Hello"}
def json_validate(data,schema):
    try:
        validate(instance=data, schema=schema)
        print("Valid")
    except:
        print("Invalid")

json_validate(data,schema)
json_validate(data,schema1)

其输出内容为：

Invalid
Valid

2 JSON Schema类型

  虽然前文中type中的关键字为object时才能校验JSON数据，但是type关键字还可以有其他取值，并且不同数据类型有各自其他限定的关键词。 type关键字可取值有：object、string、array、integer、number、boolean、null。boolean和null并没有相关的限定关键词，这里就不介绍了。
JSON Schema实际上是一个嵌套结构，下面的很多关键词的取值也可以是一个JSON Schema格式。

2.1 object类型

object类型类似于Python中的字典(dict)类型，其限定关键词主要有以下几个：

关键词	说明
properties	object类型。其中每个键是待校验的JSON中属性的名称，值是用于验证该属性的模式。此关键字将忽略与properties关键字中的任何键名称不匹配的任何属性；
patternProperties	object类型。如果待校验的JSON中属性的名称与给定的正则表达式匹配，则属性值必须符合指定的模式；
additionalProperties	取值为true/false。是否允许待校验的JSON中存在未在properties属性中或不符合patternProperties中的模式的键值；
required	List型。待校验的JSON中必须存在的键值。也就是说patternProperties中指定的键值不是必须存在的；
minProperties	数值。待校验的JSON中必须满足的最小属性个数；
maxProperties	数值。待校验的JSON中必须满足的最大属性个数；
propertyNames	待校验的JSON中属性名称必须满足的模式；可以配合pattern关键词使用；

具体举例如下：

from jsonschema import validate
schema={
    "type": "object",
    "properties": {
        "message": {"type": "string"}
    },
    "required": ["message","role"],
    "additionalProperties": False, 
}
data={
    "role":"system",
    "message":"你是谁啊"
}
def json_validate(data,schema):
    try:
        validate(instance=data, schema=schema)
        print("Valid")
    except:
        print("Invalid")
json_validate(data,schema)

具体结果如下：

Invalid

2.2 string型

string类型限定的关键词主要有以下：

minLength/maxLength	数值型。字符串的最小长度、最大长度；
pattern	字符串需满足的正则表达式；
format	时间和日期：“date-time”、“time”、“date"和"duration”; 邮件：“email”，“idn-email”； 域名：“hostname” “idn-hostname”； IP: “ipv4” “ipv6”； 资源标识符：“uuid” “uri” “uri-reference” “iri” “iri-reference” ; uri-template: “uri-template”; json pointer: “json-pointer” “relative-json-pointer”; 正则表达式：“regex”

举例如下：

from jsonschema import validate
schema={
    "type": "object",
    "properties": {
        "message": {"type": "string"},
        'date': {"type": "string",
                "format": "date"}
    },
    "required": ["message","role"],
    "additionalProperties": True,
}
data={
    "role":"system",
    "message":"你是谁啊",
    "date":"2024-03-30"
}
def json_validate(data,schema):
    try:
        validate(instance=data, schema=schema)
        print("Valid")
    except:
        print("Invalid")

json_validate(data,schema)

2.3 numeric型

JSON schema中的numeric型有两种取值：number(类似于Python中的float型和int型)和integer(仅类似于Python中int型)。所以这里重点介绍number，其限定的关键词包括以下几种：

关键词	描述
multipleOf	正整数。数值必须为给定值的倍数；
minimum	数值必须大于等于该值；
maximum	数值必须小于等于该值；
exclusiveMinimum	数值必须大于该值；
exclusiveMaximum	数值必须小于该值；

举例如下：

from jsonschema import validate

schema={
    "type": "object",
    "properties": {
        "num":{"type":"number",
                "multiplesOf":10,
                "miximum":20,
                "maximum":300}
            }
}
data={
    "num":230
}
def json_validate(data,schema):
    try:
        validate(instance=data, schema=schema)
        print("Valid")
    except:
        print("Invalid")

json_validate(data,schema)

其结果如下：

Valid

2.4 array型

array型类似于类似于python中的list型和tuple型，其限定的关键词主要有以下：

关键词	描述
items	object型。用于验证数组中的所有项;
prefixItems	List型。按索引验证tuple中的每一个项。此时若将items设置为false, 那么元组中将不允许有其他项；
contains	object型。数组中至少要包含的项；
unevaluatedItems	true/false, 数组中是否允许任何未在items、prefixItems和contains指定的数据项存在；
minItems	最小的元组数；
maxItems	最大的元组数；
uniqueItems	true/false, 数据项是否要求是唯一的；

举例如下：

from jsonschema import validate
schema={
    "type": "object",
    "properties": {
        "num": {
            "type": "array",
            "prefixItrems": [
               { "type": "number"},
               {"type":"string"}
            ],
            "unevaluatedItems": True
        }
    }
}
data={"num":[1,'hello',5.4]}
def json_validate(data,schema):
    try:
        validate(instance=data, schema=schema)
        print("Valid")
    except:
        print("Invalid")
json_validate(data,schema)

其结果如下：

Valid

3 其他

除了以上介绍的关键词之外，还有一些其他的常用关键词，具体如下：

• enum: 枚举类型。
• const：常数。
• contentMediaType：
• contentEncoding：

参考资料：

1. https://json-schema.org/understanding-json-schema/reference
2. https://zhuanlan.zhihu.com/p/72607132