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 が空の配列であることを確認しました（unknown_class／unknown_property エラーがある状態で valid:true になることはありませんが、ブール値だけを信頼せず、配列の長さが 0 であることを確認してください）。
• results.warnings 内のすべての domain_mismatch エントリについて、プロパティ、そのエントリで報告された domain、および適用先のクラスを記録し、残すか移動するかを明示的に判断しました（警告は自動修正されず、サブクラスに対して意図的な場合もあります）。
• completeness_checker.py --json を実行し、completeness_score を引用する前に results.required_missing が空であることを確認しました。required_missing が空でない場合、スコアがどれほど高くてもアノテーションは無効です。
• required_missing、recommended_missing、optional_missing の各リストとともに、正確な completeness_score を記録しました（必須項目が欠けている間は、スコアを「完全」と言い換えないでください）。
• 不明なクラス／プロパティの各エラーについて、suggestions[0] の値を記録し、修正後の名前がオントロジーに実際に存在することを確認しました（チェッカーを再実行するか、ontology-explorer で確認）。最上位の候補が正しいと思い込まないでください。
• サブジェクト・プロパティ・オブジェクトの各トリプルに対して relationship_checker.py --json を実行し、各トリプルの results.results[i].valid が true であることを確認しました。問題のある domain または range を示す results.errors の文字列があれば記録しました。
• 使用した --ontology（例：cmso、asmo）が、アノテーションの作成時に対象としたオントロジーに一致することを確認しました。間違った制約ファイル／概要ファイルが読み込まれているだけで、クラスが「不明」になることがあります。

よくある落とし穴と合理化

つい選びたくなる近道	それが間違いである理由／すべきこと
「completeness_score は 0.67 だから、アノテーションはほぼ完全です。」	スコアでは必須・推奨・任意の各階層が同じ重みで扱われるため、スコアが高くても必須プロパティが欠けていることがあります。まず required_missing を確認してください。リストが空でなければ、スコアに関係なく無効です。
「schema_checker が返したのは警告だけで、エラーはなかったので無視します。」	domain_mismatch 警告は、そのプロパティが domain に属していない（そのサブクラスでもない）クラスに付与されていることを示します。多くの場合、プロパティは別のインスタンスに属します。警告をそれぞれ記録して明示的に判断し、自動的に無視しないでください。
「クラス名は一致しませんでしたが、バリデーターが候補を示したので、それを使います。」	suggestions は標準ライブラリの difflib によるファジーマッチング（しきい値 0.6）から得られるため、候補が誤っていたり、空だったりすることがあります。候補の名前を適用する前に、それがオントロジーに存在することを確認してください。
「3 つの関係のうち 2 つが通ったので、トリプルに問題はありません。」	results.valid はすべてのトリプルの AND です。各 results.results[i] とその errors を確認する必要があります。domain／range チェックが 1 つでも失敗すれば、関係の集合は無効になります。
「valid:true が返されたので、アノテーションは意味的に正しいです。」	チェッカーが検証するのは、手作業で整備された制約ファイルに照らしたクラス／プロパティの存在と domain／range だけです。データ型、カーディナリティ、値の妥当性はチェックしません。valid:true は必要条件であり、十分条件ではありません。
「プロパティがオントロジーに存在するので、自分のクラスにも適用できます。」	存在チェックはプロパティの全体集合に対して行われます。domain への適用可否は、サブクラスを考慮した別のチェックです。実在するプロパティでも、誤ったクラスに適用すると domain_mismatch 警告が発生することがあります。
「クラス名はそのまま信頼します。部分文字列が近ければ十分です。」	domain／サブクラスの照合は、完全一致と親クラスのたどり直しで行われ、部分文字列の包含ではありません。Material は Crystalline Material のプロパティとして認められません。オントロジー上の正確なクラス名を使用してください。

セキュリティ

入力検証

• --ontology は ontology_registry.json に登録されているオントロジー名（固定の許可リスト）に照らして検証します
• --annotation の JSON は json.loads() で解析し、必須の class キーと properties キーを持つ辞書として検証します
• --class の名前は、オントロジーの概要にある既知のクラスに照らして検証します。不明なクラスには明確なエラーが表示されます
• --provided のプロパティ名は、カンマ区切りの文字列として検証し、既知のプロパティと照合します
• --relationships の JSON は解析され、各項目に subject_class、property、object_class キーが必要な、空でない辞書のリストとして検証されます
• サイズ／長さの上限により、悪意のある入力を拒否します（終了コード 2）：生の JSON 入力とアノテーションファイルの上限は 1,000,000 バイトです。1 回の呼び出しで指定できるアノテーション／関係／指定プロパティは最大 1000 個です。各クラス名またはプロパティ名の上限は 500 文字です。クラス名とプロパティ名は文字列でなければなりません。

ファイルアクセス

• スクリプトは references/ ディレクトリから、前処理済みの JSON ファイル ontology_registry.json、cmso_summary.json、cmso_constraints.json を読み込みます（すべて読み取り専用です）
• スクリプトはファイルシステムに書き込みません。すべての出力は stdout に送られます
• ネットワークアクセスは不要です

ツールの制限

• Read：スクリプトのソース、参照ファイル、オントロジーの制約データの確認に使用します
• Bash：3 つの Python 検証スクリプト（schema_checker.py、completeness_checker.py、relationship_checker.py）を、明示的な引数リストで実行するために使用します

安全対策

• eval()、exec()、動的なコード生成は使用しません
• すべてのサブプロセス呼び出しでは、明示的な引数リストを使用します（shell=True は使用しません）
• JSON 入力の解析には json.loads() のみを使用します（pickle や、安全でないローダーを使った YAML は使用しません）
• 検証ロジックは、事前に読み込まれたインメモリのデータ構造を処理します。動的なファイル検索や走査は行いません

制限事項

• 制約ファイルは手作業で編集されており、OWL 公理から導出されたものではありません
• データ型は検証しません（例：値が実際に float か文字列かどうか）
• 多重度は検証しません（例：構造ごとに空間群が厳密に 1 つあるかどうか）
• サブクラスの判定には単純な親クラスのたどり方を使用し、OWL の完全な推論は行いません

参考資料

• 検証ルール — 検証内容とその理由
• CMSO の制約 — クラスごとの必須／推奨プロパティ
• CMSO ガイド — CMSO オントロジーの概要

バージョン履歴

日付	バージョン	変更内容
2026-06-23	1.2.0	サブクラスを考慮したドメイン照合（部分文字列による誤検知／見逃しを修正）、不明なクラス／プロパティに対する最近傍候補の提案、入力サイズ／長さの上限、eval とドキュメントの修正
2026-02-25	1.0	CMSO の検証サポートを含む初回リリース