JsonSchema如何实现废弃属性使用时的警告日志记录

deprecated 是JSON Schema规范定义的纯注解类关键字，默认不触发任何校验逻辑，这也是直接加注解没有任何效果的根本原因。要实现命中废弃规则时打印警告日志，核心是在校验流程中增加注解收集逻辑，遍历命中的Schema节点检测废弃标记，匹配到规则时主动输出日志即可。

Python jsonschema 库完整实现示例 #

该方案不需要依赖额外第三方插件，直接扩展原生校验器即可：

• 支持给整个字段标记废弃
• 支持给特定取值分支标记废弃
• 不阻断原生校验流程，仅额外输出告警

1. 首先定义带废弃标记的Schema，可自定义废弃提示信息

from jsonschema import Draft202012Validator
import logging
logging.basicConfig(level=logging.WARNING)

# 示例Schema规则
schema = {
    "type": "object",
    "properties": {
        "old_username": {
            "type": "string",
            "deprecated": True,
            "deprecation_msg": "old_username字段将在v2.0版本下线，请替换为user_name字段"
        },
        "user_name": {"type": "string"},
        "account_status": {
            "type": "integer",
            "oneOf": [
                {"const": -1, "deprecated": True, "deprecation_msg": "状态值-1已废弃，请使用0=禁用、1=正常"},
                {"const": 0},
                {"const": 1}
            ]
        }
    }
}

2. 自定义支持废弃告警的校验器，在原生校验逻辑之外增加注解遍历检测

class DeprecationAlertValidator(Draft202012Validator):
    def iter_errors(self, instance, _schema=None):
        # 先执行原生校验，返回所有格式不匹配的错误
        yield from super().iter_errors(instance, _schema)

        # 递归遍历实例与匹配的Schema节点，检测废弃标记
        def scan_deprecation(node, node_schema, path):
            # 命中废弃规则时打印警告
            if node_schema.get("deprecated", False):
                log_msg = node_schema.get(
                    "deprecation_msg",
                    f"路径{'/'.join(path) if path else '根节点'}使用了已废弃规则"
                )
                logging.warning(log_msg)

            # 递归遍历对象子属性
            if isinstance(node, dict) and "properties" in node_schema:
                for prop_name, prop_schema in node_schema["properties"].items():
                    if prop_name in node:
                        scan_deprecation(node[prop_name], prop_schema, path + [prop_name])

            # 递归遍历数组元素
            if isinstance(node, list) and "items" in node_schema:
                for idx, item in enumerate(node):
                    scan_deprecation(item, node_schema["items"], path + [f"[{idx}]"])

            # 检测oneOf/anyOf/allOf组合规则里的废弃分支
            for combiner in ["oneOf", "anyOf", "allOf"]:
                if combiner not in node_schema:
                    continue
                for sub_schema in node_schema[combiner]:
                    try:
                        Draft202012Validator(sub_schema).validate(node)
                        scan_deprecation(node, sub_schema, path)
                    except Exception:
                        continue

        scan_deprecation(instance, self.schema, [])

3. 调用方式和原生校验器完全一致

if __name__ == "__main__":
    validator = DeprecationAlertValidator(schema)
    # 测试数据：同时使用废弃字段、废弃状态值
    test_instance = {
        "old_username": "zhangsan",
        "account_status": -1
    }
    # 执行校验时会自动输出两条警告，同时不影响正常校验流程
    validate_errors = list(validator.iter_errors(test_instance))
    print(f"格式校验错误数量：{len(validate_errors)}")

其他技术栈适配思路 #

• JS/TS Ajv库：通过addKeyword方法自定义deprecated关键字处理逻辑，校验函数中命中规则时调用console.warn或项目日志组件输出即可
• Java Jackson/JsonSchemaValidator：注册自定义Schema遍历监听器，反序列化/校验过程中检测到deprecated标记时输出日志
• Go gojsonschema：扩展自定义Schema关键字处理器，在Validate回调中增加告警逻辑

内容的提问来源于stack exchange，提问作者Felipe Hsu