json-schema-validator

用途

JSON Schema Validator 用于将 JSON 数据与 JSON Schema（Draft 7）规范进行校验，适用于 API 校验、配置文件校验或数据质量检查等场景。

主要能力

• Schema 校验：使用 Schema 校验 JSON 数据
• 错误详情：提供详细的校验错误信息
• 批量校验：可校验多个文件
• Schema 生成：可从示例数据生成 Schema
• 多 Draft 支持：支持 Draft 4、6、7

使用方式

Python 类库

from json_validator import JSONValidator

validator = JSONValidator()

# 使用 Schema 校验数据
schema = {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer", "minimum": 0}
},
"required": ["name"]
}

data = {"name": "John", "age": 30}
result = validator.validate(data, schema)
print(f"Valid: {result['valid']}")

命令行使用

# 使用 Schema 校验 JSON 文件
python json_validator.py --data user.json --schema user_schema.json

# 使用内联 Schema 校验
python json_validator.py --data config.json --schema '{"type": "object"}'

# 从示例生成 Schema
python json_validator.py --generate sample.json --output schema.json

# 批量校验目录
python json_validator.py --data-dir ./configs/ --schema config_schema.json

API 参考

JSONValidator 类：

class JSONValidator:
    def __init__(self, draft: str = "draft7")

    # 校验
    def validate(self, data: dict, schema: dict) -> dict
    def validate_file(self, data_path: str, schema_path: str) -> dict
    def validate_batch(self, data_files: list, schema: dict) -> list

    # Schema 操作
    def generate_schema(self, data: dict) -> dict
    def check_schema(self, schema: dict) -> dict

校验结果格式：

{
    "valid": True,  # 或 False
    "errors": [],   # 错误详情列表
    "path": "$",    # 指向数据根的 JSON 路径
}

# 含错误时：
{
    "valid": False,
    "errors": [
        {
            "message": "'name' is a required property",
            "path": "$",
            "schema_path": "required"
        },
        {
            "message": "-5 is less than minimum 0",
            "path": "$.age",
            "schema_path": "properties.age.minimum"
        }
    ]
}

Schema 示例

对象 Schema：

schema = {
    "type": "object",
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "active": {"type": "boolean", "default": True}
    },
    "required": ["id", "name", "email"],
    "additionalProperties": False
}

数组 Schema：

schema = {
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "id": {"type": "integer"},
            "value": {"type": "number"}
        }
    },
    "minItems": 1,
    "uniqueItems": True
}

嵌套 Schema：

schema = {
    "type": "object",
    "properties": {
        "user": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "address": {
                    "type": "object",
                    "properties": {
                        "street": {"type": "string"},
                        "city": {"type": "string"}
                    }
                }
            }
        }
    }
}

从数据生成 Schema

validator = JSONValidator()

sample_data = {
    "name": "Product A",
    "price": 29.99,
    "tags": ["electronics", "sale"],
    "inStock": True
}

schema = validator.generate_schema(sample_data)
# 根据数据类型返回推断出的 Schema

支持的校验关键字

类型校验：

• type：string、number、integer、boolean、array、object、null
• enum：允许的值
• const：精确值

字符串校验：

• minLength、maxLength
• pattern：正则模式
• format：email、uri、date、date-time、ipv4、ipv6、uuid

数字校验：

• minimum、maximum
• exclusiveMinimum、exclusiveMaximum
• multipleOf

数组校验：

• items：元素 Schema
• minItems、maxItems
• uniqueItems
• contains

对象校验：

• properties：属性 Schema
• required：必填属性
• additionalProperties
• minProperties、maxProperties
• patternProperties

错误处理

result = validator.validate(data, schema)

if not result['valid']:
    for error in result['errors']:
        print(f"Error at {error['path']}: {error['message']}")

依赖

jsonschema>=4.20.0