sdcvalidator-ts

sdcvalidator-ts

使用 TypeScript 实现的 SDC4 验证工具。它会根据已发布的 SDC4 模型验证受治理的数据记录，并使用 ISO 21090 ExceptionalValues 恢复语义错误；在符合性测试套件中，其结果与参考实现 sdcvalidator 相同。

符合版本： sdcvalidator 4.6.3（其符合性测试套件中的全部 151 个案例）。CI 会运行固定到该标签版本的测试套件。

它可在 Node（20 或更高版本）、Deno（包括 Supabase Edge Functions）和浏览器中运行。你需要提供模型和记录文本，因此它不会读取文件，也不会发起网络请求。

import { SDC4Validator, REFERENCE_MODEL_URL } from 'sdcvalidator-ts';

const validator = new SDC4Validator({
  text: modelXsd,                       // the model's published XSD
  resolve: (location) => sdc4Xsd,       // the reference model it includes (REFERENCE_MODEL_URL)
});

const result = validator.validate(recordXml);
// { valid, structural: [...], semantic: [{ path, ev, kind, constraint, message }, ...] }

const recovered = validator.recover(recordXml);
// { ok, recoveries: [{ path, code, name, inserted }], unrecoverable: [...], record, text }
// Throws StructuralValidationError if the record has structural errors.

MCP 服务

此软件包包含一个 MCP 服务，因此 Agent 可以直接调用它。它通过标准输入/输出使用 JSON-RPC 2.0，并在 Node 上运行；它会读取你指定的文件。

npx sdcvalidator-ts mcp

工具	功能
validate_instance	返回通过或失败的结果及错误数量
validate_and_report	列出每个错误：路径、级别、违反的约束以及 ExceptionalValue 代码
recover_instance	返回恢复后的记录及覆盖的每个值；结构错误会导致拒绝
check_schema_compliance	检查架构是否遵循 SDC4 原则：限制，而非扩展

除合规性检查只接受架构外，每个工具都需要 schema_path 和 instance_path，并可选接受 reference_path。模型中 xsd:include 引用的参考模型会从其 URL 获取一次并缓存。指定 reference_path 时，则会改为从该本地副本读取，因此服务可离线运行。

该服务已在 MCP 注册表中登记为 io.github.SemanticDataCharter/sdcvalidator-ts。

“结果相同”的含义

符合性测试套件会对每个案例进行比较：

• 判定结果；
• 按路径区分的结构错误和语义错误；
• 每个语义错误对应的 ExceptionalValue 代码；
• 恢复结果；
• 恢复后的记录（作为树进行比较，忽略注释）。

错误消息不参与比较。错误按违反的约束分类，而非按消息措辞分类。

ExceptionalValue 代码采用参考实现 sdcvalidator 4.6.3 中的代码：

• OTH： 值不在其枚举范围内。
• INV： 值的类型不符，或违反其他任意方面的限制（模式、长度、范围、位数、内置类型自身的范围）、固定值或断言。
• NA： 仅允许元素的位置出现了字符数据。
• 无代码： 结构元素（label、vtb、vte 等）上的错误，无法恢复。

当 sdcvalidator 的映射发生变化时，测试套件的预期结果也会随之变化；本库会在下次发布前跟进。

XSD 子集

SDC4 架构只使用 XSD 1.1 的一个狭窄子集，本库实现了该子集：

• 元素： 全局和局部元素，以及 ref、出现次数、fixed、abstract 和替换组。
• 复杂类型： 复杂内容和简单内容、限制和扩展、序列和选择。
• 简单类型： 限制（包括枚举、模式、长度、范围、位数和 whiteSpace 方面）及列表；约 40 种内置类型。
• xsd:assert： 使用 fontoxpath 求值，并从派生类型继承。
• xsd:include。

子集之外的构造会引发 UnsupportedSchemaError 并指出构造名称，绝不会被忽略。

在解析前会拒绝 DOCTYPE 和实体声明，因此绝不会解析外部实体。

开发

npm install
npm run typecheck
npm test     # needs the conformance suite: a sibling sdcvalidator checkout, or CONFORMANCE_DIR
npm run build

依赖项已精确锁定版本：@xmldom/xmldom 0.9.12（用于解析）和 fontoxpath 3.34.0（用于断言的 XPath 3.1）。

许可证

Apache-2.0。