sdcvalidator

sdcvalidator

SDC4 结构验证器——基于 xmlschema 的轻量封装，支持两级错误分类。

功能

• 根据 SDC4 XSD 架构验证 XML 实例
• 将错误分类为结构错误（第 1 级：拒绝）和语义错误（第 2 级：报告）
• 检查是否符合 SDC4 架构规范（不使用 xsd:extension，仅使用 xsd:restriction）
• 默认启用严格验证——在架构加载时捕获无效的限制派生（元素名称错误、类型不匹配）
• 使用架构感知的转换在 XML 和 JSON 之间转换

安装

pip install sdcvalidator

或从源码安装：

git clone https://github.com/SemanticDataCharter/sdcvalidator.git
cd sdcvalidator
pip install -e .

Python API

from sdcvalidator import SDC4Validator, ErrorTier

# Validate an XML instance (strict mode by default)
validator = SDC4Validator("my_schema.xsd")
result = validator.validate("my_instance.xml")

if result.is_valid:
    print("Valid!")
else:
    for err in result.structural_errors:
        print(f"STRUCTURAL: {err.reason}")
    for err in result.semantic_errors:
        print(f"SEMANTIC: {err.reason}")

验证模式

validation 参数用于控制加载时对 XSD 架构本身的检查严格程度：

• 'strict'（默认）——如果架构包含无效的限制派生（例如，元素名称与基类型不匹配），则引发 XMLSchemaParseError。这是推荐模式。
• 'lax'——静默收集架构派生错误，不引发异常。仅用于已知存在问题的既有架构。
• 'skip'——完全跳过架构级验证。

# Explicit lax mode for legacy schemas
validator = SDC4Validator("legacy_schema.xsd", validation='lax')

架构规范检查

from sdcvalidator import validate_sdc4_schema_compliance, assert_sdc4_schema_compliance

# Check if a schema uses xsd:extension (not allowed in SDC4)
is_valid, errors = validate_sdc4_schema_compliance("schema.xsd")

# Or raise an exception
assert_sdc4_schema_compliance("schema.xsd")

错误分类

from sdcvalidator import ErrorClassifier, ErrorTier

classifier = ErrorClassifier()
tier = classifier.classify(some_xmlschema_error)
# ErrorTier.STRUCTURAL or ErrorTier.SEMANTIC

Exceptional Value 恢复

语义错误（第 2 级）不一定要导致记录被拒绝。恢复会保留该值，并在其旁边插入一个 ISO 21090 ExceptionalValue（Invalid，用于类型、模式、范围或枚举验证失败的值），以说明哪个值不可用以及原因，同时保留记录其余部分的可用性。

from sdcvalidator import SDC4Validator, SDC4UnrecoverableError

v = SDC4Validator("dm-xxxx.xsd", validation="lax")
result = v.recover("record.xml")         # RecoveryResult; the source is never mutated
for r in result.recoveries:              # Recovery: path, code ("INV"), name, reason, inserted
    print(r.code, r.reason, r.path)
if not result.ok:                        # an error no ExceptionalValue covers
    print(result.unrecoverable)

tree = v.validate_with_recovery("record.xml", save=False)   # raises SDC4UnrecoverableError instead

• 记录中已有的 ExceptionalValue（例如在记录创建时写入的拒绝值或遮蔽字段）会予以保留，并覆盖其对应值；恢复过程不会再插入第二个。remove_existing_ev=True 会先移除它们。
• 恢复无法覆盖的错误会由 recover() 返回在 unrecoverable 中，并由 validate_with_recovery() 引发为 SDC4UnrecoverableError；绝不会跳过此类错误。
• 结构错误（第 1 级）会引发 SDC4StructuralValidationError。
• 如果记录内容包含带前缀的 QName（xsi:type="sdc4:..."），请传入 XMLResource。

XML/JSON 转换

from sdcvalidator.converters import xml_to_json, json_to_xml

# XML -> JSON (schema-aware)
data = xml_to_json("instance.xml", schema_path="schema.xsd")

# JSON -> XML
json_to_xml(data, "schema.xsd", "output.xml")

CLI

sdcvalidate——根据架构验证 XML

# Basic validation
sdcvalidate schema.xsd instance.xml

# JSON output
sdcvalidate schema.xsd instance.xml --json

# Skip SDC4 compliance check
sdcvalidate --no-compliance-check schema.xsd instance.xml

退出代码：0 表示有效，1 表示仅有语义错误，2 表示存在结构错误。

sdcvalidator-xml2json——将 XML 转换为 JSON

sdcvalidator-xml2json instance.xml --schema schema.xsd
sdcvalidator-xml2json instance.xml -o output.json

sdcvalidator-json2xml——将 JSON 转换为 XML

sdcvalidator-json2xml data.json schema.xsd -o output.xml

MCP 服务

sdcvalidator 提供基于标准输入/输出的 MCP（Model Context Protocol）服务，因此任何兼容 MCP 的 Agent 都可以验证 SDC4 数据，而无需导入 Python 库。它直接通过标准输入/输出实现 JSON-RPC 2.0，无需依赖外部 MCP SDK。

sdcvalidator            # what an MCP registry client runs (uvx sdcvalidator)
sdcvalidator mcp        # the same, spelled like the other Semantic Data Charter servers
sdcvalidator-mcp serve --mcp   # still works for existing client configurations

客户端配置只需包含 "command": "uvx", "args": ["sdcvalidator"]。

工具

工具	用途
validate_instance	根据对应的 SDC4 XSD 架构验证 XML 实例。返回通过/失败状态、错误数量和分类后的错误。
validate_and_report	验证实例并返回详细报告，其中包含两级错误分类（结构错误和语义错误）。
check_schema_compliance	检查 XSD 架构是否遵循 SDC4 原则（仅使用 restriction，不使用 xsd:extension）。不验证实例。

validate_instance 和 validate_and_report 接受 schema_path 和 instance_path，以及可选的布尔参数 check_compliance（默认值为 true）。check_schema_compliance 仅接受 schema_path。

两级错误分类

层级	类型	示例	操作
1	结构性	未知元素、基数违规、嵌套错误	拒绝
2	语义性	类型错误、模式违规、枚举不匹配	报告，或使用 ExceptionalValue 恢复

SDC4 架构合规性

SDC4 数据模型必须仅使用 xsd:restriction，绝不能使用 xsd:extension。这确保结构（参考模型）与语义（数据模型）相分离，从而保证全局互操作性。

验证器默认会检查这一点，并拒绝违反此原则的架构。

状态

已可用于生产环境。可在 PyPI 获取，采用 Apache 2.0 许可证。

许可证

Apache License 2.0 — 参见 LICENSE。

链接

• 语义数据章程
• SDC4 参考模型
• xmlschema