ontology-validator

本体验证器

目标

验证材料样本注释是否符合本体约束：类名正确、属性有效、定义域/值域关系一致，并且包含必填字段。

要求

• Python 3.10+
• 无外部依赖（仅使用 Python 标准库）
• 需要 ontology-explorer 的 cmso_summary.json 和 ontology_registry.json

要收集的输入

输入	描述	示例
注释	JSON 字典或注释字典列表	{"class":"UnitCell","properties":{"has Bravais lattice":"cF"}}
类名	要检查完整性的类	Crystal Structure
已提供的属性	以逗号分隔的属性名	"has unit cell,has space group"
关系	主体-属性-客体三元组的 JSON 数组	[{"subject_class":"Material","property":"has structure","object_class":"Crystal Structure"}]

决策指南

What do you need to validate?
├── An annotation (classes and properties are correct)
│   └── schema_checker.py --ontology cmso --annotation '<json>'
├── Completeness of a class annotation
│   └── completeness_checker.py --ontology cmso --class <name> --provided <props>
└── Object property relationships
    └── relationship_checker.py --ontology cmso --relationships '<json>'

脚本输出（JSON 字段）

脚本	主要输出
scripts/schema_checker.py	results.valid、results.errors（每个 unknown_class/unknown_property 错误都包含一个最近匹配项的 suggestions 数组）、results.warnings、results.class_valid、results.properties_valid
scripts/completeness_checker.py	results.completeness_score、results.required_missing、results.recommended_missing、results.optional_missing、results.unrecognized
scripts/relationship_checker.py	results.valid、results.results、results.errors

工作流

1. 使用 ontology-mapper 映射样本后，将注释传递给 schema_checker.py 以验证其正确性。
2. 对于特定类，使用 completeness_checker.py 查看缺失的必需/推荐属性。
3. 构建实例之间的关系时，使用 relationship_checker.py 确保定义域/值域一致。

对话工作流示例

User: I annotated my sample as CrystalStructure with properties hasUnitCell and hasBasis.
      Is this correct and complete?

Agent: Let me both validate the annotation and check its completeness.

[Runs: schema_checker.py --ontology cmso --annotation
       '{"class":"Crystal Structure","properties":{"has unit cell":true,"has basis":true}}' --json]
[Runs: completeness_checker.py --ontology cmso --class "Crystal Structure"
       --provided "has unit cell,has basis" --json]

From schema_checker.py (results.warnings):
- has unit cell: valid for Crystal Structure
- has basis: domain_mismatch warning — its domain is "Unit Cell", not
  Crystal Structure (so this property belongs on the Unit Cell instance)

From completeness_checker.py (results, completeness_score = 0.5):
- **required_missing**: has space group

So: add "has space group" to the Crystal Structure annotation, and move
"has basis" onto the Unit Cell annotation. (The domain insight comes from
schema_checker.py's warnings; completeness_checker.py only reports the
missing required "has space group".)

CLI 示例

# Validate an annotation
python3 skills/ontology/ontology-validator/scripts/schema_checker.py \
  --ontology cmso \
  --annotation '{"class":"Unit Cell","properties":{"has Bravais lattice":"cF"}}' \
  --json

# Check completeness
python3 skills/ontology/ontology-validator/scripts/completeness_checker.py \
  --ontology cmso \
  --class "Crystal Structure" \
  --provided "has unit cell,has space group" \
  --json

# Validate relationships
python3 skills/ontology/ontology-validator/scripts/relationship_checker.py \
  --ontology cmso \
  --relationships '[{"subject_class":"Computational Sample","property":"has material","object_class":"Material"}]' \
  --json

错误处理

错误	原因	解决方法
Class 'X' not found ... (did you mean 'Y'?)	类名无效或拼写错误	应用错误中最接近匹配项的 suggestions，或使用 ontology-explorer 查找正确名称
Property 'X' not found ... (did you mean 'Y'?)	属性名无效或拼写错误	应用错误中最接近匹配项的 suggestions，或使用 property_lookup.py 搜索
Annotation must be a dict	输入格式错误	提供有效的 JSON 字典
Relationships must be a non-empty list	输入格式错误	提供关系字典组成的 JSON 数组

解读指南

• 错误 表示确定存在问题（类/属性未知、值域不匹配）
• 警告 表示可能存在问题（定义域不匹配——对子类而言可能是有意为之）
• 完整性评分：已提供属性与已跟踪属性总数之比，范围为 0.0-1.0。必需、推荐和可选属性的权重相同，因此中等评分（例如 0.5-0.67）也可能同时存在缺失的必需属性。请务必先检查 required_missing：只要 required_missing 非空，无论评分如何，注释都无效。
• required_missing：必须修复，注释才有效
• recommended_missing：建议修复，以提升质量
• unrecognized：可能表示存在拼写错误，或使用了来自其他本体的属性

验证检查清单

• 运行了 schema_checker.py --json 并记录 results.valid；确认 results.errors 是空数组（valid:true 时不会出现任何 unknown_class/unknown_property 错误，但仍须确认数组长度为 0，而不能只相信布尔值）。
• 对于 results.warnings 中的每一条 domain_mismatch，记录其属性、报告的 domain，以及应用该属性的类，然后明确决定保留还是移至其他位置（警告不会自动修复，而且对于子类来说可能是有意为之）。
• 运行了 completeness_checker.py --json，并在引用 completeness_score 之前确认 results.required_missing 为空——required_missing 非空意味着注释无效，无论分数多高。
• 记录准确的 completeness_score，以及 required_missing、recommended_missing 和 optional_missing 列表（只要仍缺少任何必需项，就不要将分数概括为“完整”）。
• 对于每个未知类/属性错误，记录 suggestions[0] 的值，并确认修正后的名称确实存在于本体中（重新运行检查器，或通过 ontology-explorer 检查），而不是想当然地认为排名最高的建议是正确的。
• 对每个主体-属性-客体三元组运行了 relationship_checker.py --json，并确认每个三元组对应的 results.results[i].valid 都为 true；记录 results.errors 中指出违规 domain 或 range 的字符串。
• 确认所用的 --ontology（例如 cmso、asmo）与编写注释时依据的本体相符——有时只是因为加载了错误的约束/摘要文件，某个类才被判定为“未知”。

常见陷阱与自我辩解

看似省事的做法	为什么不对／应该怎么做
“completeness_score 是 0.67，所以注释基本完整。”	该分数对必需、推荐和可选三个级别赋予相同权重，因此即使分数很高，也可能仍缺少必需属性。先检查 required_missing；只要列表非空，注释就无效，无论分数多高。
“schema_checker 只返回了警告，没有错误，所以我会忽略它们。”	domain_mismatch 警告表示某个属性被关联到了不属于（其子类也不属于）该属性所属 domain 的类——通常是因为该属性应该应用于另一个实例。记录每条警告并明确作出决定；不要自动忽略。
“类名不匹配，但验证器给了一个建议，所以我就用它。”	suggestions 来自标准库 difflib 的模糊匹配（阈值为 0.6），结果可能错误，也可能为空。应用建议前，请确认该名称确实存在于本体中。
“三个关系中有两个通过了，所以这些三元组没问题。”	results.valid 是对所有三元组结果进行 AND 运算的结果；必须检查每个 results.results[i] 及其 errors。只要有一项 domain/range 检查失败，整组关系就无效。
“它返回了 valid:true，所以注释在语义上是正确的。”	检查器只会根据一份人工整理的约束文件，验证类/属性是否存在以及 domain/range 是否匹配。它不会检查数据类型、基数或值是否合理——valid:true 是必要条件，但不是充分条件。
“属性存在于本体中，所以它适用于我的类。”	是否存在是根据完整属性集检查的；domain 适用性则是另一项考虑子类关系的检查。即使属性确实存在，在错误的类上仍可能触发 domain_mismatch 警告。
“我就相信这个类名，子字符串差不多就行。”	domain/子类匹配采用精确相等后沿父类关系遍历，而不是子字符串包含。Material 不会获得 Crystalline Material 的属性；请使用精确的本体类名。

安全

输入验证

• --ontology 会根据 ontology_registry.json 中注册的本体名称进行验证（固定允许列表）
• 使用 json.loads() 解析 --annotation JSON，并验证其为包含必需的 class 和 properties 键的字典
• --class 名称会根据本体摘要中的已知类进行验证；未知类会产生明确的错误
• --provided 属性名称会作为逗号分隔字符串进行验证，并与已知属性匹配
• 使用 json.loads() 解析 --relationships JSON，并验证其为非空字典列表，每个字典都必须包含 subject_class、property 和 object_class 键
• 大小／长度上限会拒绝过量输入（退出代码为 2）：原始 JSON 输入和注释文件上限为 1,000,000 字节；每次调用最多允许 1000 个注释／关系／已提供属性；每个类名或属性名最多 500 个字符。类名和属性名必须是字符串。

文件访问

• 脚本从 references/ 目录读取预处理的 JSON 文件：ontology_registry.json、cmso_summary.json、cmso_constraints.json（均为只读）
• 没有脚本会写入文件系统；所有输出都发送到标准输出
• 无需网络访问

工具限制

• Read：用于检查脚本源代码、参考文件和本体约束数据
• Bash：用于执行三个 Python 验证脚本（schema_checker.py、completeness_checker.py、relationship_checker.py），并传入显式参数列表

安全措施

• 不使用 eval()、exec() 或动态代码生成
• 所有子进程调用均使用显式参数列表（不使用 shell=True）
• JSON 输入解析仅使用 json.loads()（不使用 pickle，也不使用带不安全加载器的 YAML）
• 验证逻辑基于预加载的内存数据结构运行；不进行动态文件发现或遍历

局限性

• 约束文件由人工整理，并非从 OWL 公理推导而来
• 不验证数据类型（例如，值究竟是浮点数还是字符串）
• 不验证基数（例如，每个结构是否恰好有一个空间群）
• 子类检查采用简单的父类遍历，不执行完整的 OWL 推理

参考资料

• 验证规则 — 验证的内容及原因
• CMSO 约束 — 各类必需／推荐的属性
• CMSO 指南 — CMSO 本体概览

版本历史

日期	版本	变更
2026-06-23	1.2.0	支持感知子类的域匹配（修复子串匹配误报／漏报）、对未知类／属性提供最近匹配建议、添加输入大小／长度上限、修正 eval 和文档
2026-02-25	1.0	首次发布，支持 CMSO 验证