Ontology Validator
Goal
Validate that material sample annotations comply with ontology constraints: correct class names, valid properties, consistent domain/range relationships, and required fields present.
Requirements
- Python 3.10+
- No external dependencies (Python standard library only)
- Requires ontology-explorer's
cmso_summary.json and ontology_registry.json
Inputs to Gather
| Input |
Description |
Example |
| Annotation |
JSON dict or list of annotation dicts |
{"class":"UnitCell","properties":{"has Bravais lattice":"cF"}} |
| Class name |
Class to check completeness for |
Crystal Structure |
| Provided properties |
Comma-separated property names |
"has unit cell,has space group" |
| Relationships |
JSON array of subject-property-object triples |
[{"subject_class":"Material","property":"has structure","object_class":"Crystal Structure"}] |
Decision Guidance
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>'
Script Outputs (JSON Fields)
| Script |
Key Outputs |
scripts/schema_checker.py |
results.valid, results.errors, 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 |
Workflow
- After mapping a sample with ontology-mapper, pass the annotations to
schema_checker.py to verify correctness.
- For a specific class, use
completeness_checker.py to see what required/recommended properties are missing.
- When building relationships between instances, use
relationship_checker.py to ensure domain/range consistency.
Conversational Workflow Example
User: I annotated my sample as CrystalStructure with properties hasUnitCell and hasBasis.
Is this correct and complete?
Agent: Let me validate your annotation and check completeness.
[Runs: completeness_checker.py --ontology cmso --class "Crystal Structure" --provided "has unit cell,has basis" --json]
Your annotation is partially complete:
- has unit cell: provided (required)
- has basis: not a direct property of Crystal Structure (it belongs to Unit Cell)
- **Missing required**: has space group
The "has basis" property belongs to the Unit Cell class, not Crystal Structure.
You should add "has space group" to Crystal Structure and move "has basis"
to the Unit Cell annotation.
CLI Examples
# 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
Error Handling
| Error |
Cause |
Resolution |
Class 'X' not found |
Invalid class name |
Use ontology-explorer to find correct name |
Property 'X' not found |
Invalid property name |
Use property_lookup.py to search |
Annotation must be a dict |
Wrong input format |
Provide valid JSON dict |
Relationships must be a non-empty list |
Wrong input format |
Provide JSON array of relationship dicts |
Interpretation Guidance
- Errors indicate definite problems (unknown class/property, range mismatch)
- Warnings indicate potential issues (domain mismatch — may be intentional for subclasses)
- Completeness score: 0.0-1.0 ratio of provided vs. total tracked properties
- required_missing: must fix for valid annotation
- recommended_missing: should fix for quality
- unrecognized: may indicate typos or properties from a different ontology
Security
Input Validation
--ontology is validated against registered ontology names in ontology_registry.json (fixed allowlist)
--annotation JSON is parsed with json.loads() and validated as a dict with required class and properties keys
--class names are validated against known classes in the ontology summary; unknown classes produce clear errors
--provided property names are validated as comma-separated strings and matched against known properties
--relationships JSON is parsed and validated as a non-empty list of dicts, each requiring subject_class, property, and object_class keys
File Access
- Scripts read pre-processed JSON files from the
references/ directory: ontology_registry.json, cmso_summary.json, cmso_constraints.json (all read-only)
- No scripts write to the filesystem; all output goes to stdout
- No network access is required
Tool Restrictions
- Read: Used to inspect script source, reference files, and ontology constraint data
- Bash: Used to execute the three Python validation scripts (
schema_checker.py, completeness_checker.py, relationship_checker.py) with explicit argument lists
Safety Measures
- No
eval(), exec(), or dynamic code generation
- All subprocess calls use explicit argument lists (no
shell=True)
- JSON input parsing uses
json.loads() only (no pickle, no YAML with unsafe loaders)
- Validation logic operates on pre-loaded in-memory data structures; no dynamic file discovery or traversal
Limitations
- Constraints file is manually curated, not derived from OWL axioms
- Does not validate data types (e.g., whether a value is actually a float vs string)
- Does not validate cardinality (e.g., exactly one space group per structure)
- Subclass checking uses simple parent traversal, not full OWL reasoning
References
- Validation Rules — what is validated and why
- CMSO Constraints — required/recommended properties per class
- CMSO Guide — CMSO ontology overview
Version History
| Date |
Version |
Changes |
| 2026-02-25 |
1.0 |
Initial release with CMSO validation support |
1---2name: ontology-validator3description: >4 Validate material sample annotations against ontology constraints — check5 that class names and property names exist in the ontology, verify domain6 and range consistency for object property relationships, assess annotation7 completeness (required, recommended, and optional properties), and flag8 unknown or misspelled terms. Use when verifying that CMSO or other9 ontology annotations are correct before publishing, checking whether all10 required properties are present for a class like Crystal Structure or11 Unit Cell, auditing relationship triples between instances, or catching12 annotation errors early in a FAIR data workflow, even if the user only13 says "is my annotation correct" or "what am I missing."14allowed-tools: Read, Bash15metadata:16 source: https://skillmd.com/skills/zuoguyoupan2023/ontology-validator17 author: HeshamFS18 version: "1.1.0"19 security_tier: high20 security_reviewed: true21 tested_with:22 - claude-code23 - gemini-cli24 - vs-code-copilot25 eval_cases: 526 last_reviewed: "2026-03-26"27---2829# Ontology Validator3031## Goal3233Validate that material sample annotations comply with ontology constraints: correct class names, valid properties, consistent domain/range relationships, and required fields present.3435## Requirements3637- Python 3.10+38- No external dependencies (Python standard library only)39- Requires ontology-explorer's `cmso_summary.json` and `ontology_registry.json`4041## Inputs to Gather4243| Input | Description | Example |44|-------|-------------|---------|45| Annotation | JSON dict or list of annotation dicts | `{"class":"UnitCell","properties":{"has Bravais lattice":"cF"}}` |46| Class name | Class to check completeness for | `Crystal Structure` |47| Provided properties | Comma-separated property names | `"has unit cell,has space group"` |48| Relationships | JSON array of subject-property-object triples | `[{"subject_class":"Material","property":"has structure","object_class":"Crystal Structure"}]` |4950## Decision Guidance5152```53What do you need to validate?54├── An annotation (classes and properties are correct)55│ └── schema_checker.py --ontology cmso --annotation '<json>'56├── Completeness of a class annotation57│ └── completeness_checker.py --ontology cmso --class <name> --provided <props>58└── Object property relationships59 └── relationship_checker.py --ontology cmso --relationships '<json>'60```6162## Script Outputs (JSON Fields)6364| Script | Key Outputs |65|--------|-------------|66| `scripts/schema_checker.py` | `results.valid`, `results.errors`, `results.warnings`, `results.class_valid`, `results.properties_valid` |67| `scripts/completeness_checker.py` | `results.completeness_score`, `results.required_missing`, `results.recommended_missing`, `results.optional_missing`, `results.unrecognized` |68| `scripts/relationship_checker.py` | `results.valid`, `results.results`, `results.errors` |6970## Workflow71721. After mapping a sample with ontology-mapper, pass the annotations to `schema_checker.py` to verify correctness.732. For a specific class, use `completeness_checker.py` to see what required/recommended properties are missing.743. When building relationships between instances, use `relationship_checker.py` to ensure domain/range consistency.7576## Conversational Workflow Example7778```79User: I annotated my sample as CrystalStructure with properties hasUnitCell and hasBasis.80 Is this correct and complete?8182Agent: Let me validate your annotation and check completeness.8384[Runs: completeness_checker.py --ontology cmso --class "Crystal Structure" --provided "has unit cell,has basis" --json]8586Your annotation is partially complete:87- has unit cell: provided (required)88- has basis: not a direct property of Crystal Structure (it belongs to Unit Cell)89- **Missing required**: has space group9091The "has basis" property belongs to the Unit Cell class, not Crystal Structure.92You should add "has space group" to Crystal Structure and move "has basis"93to the Unit Cell annotation.94```9596## CLI Examples9798```bash99# Validate an annotation100python3 skills/ontology/ontology-validator/scripts/schema_checker.py \101 --ontology cmso \102 --annotation '{"class":"Unit Cell","properties":{"has Bravais lattice":"cF"}}' \103 --json104105# Check completeness106python3 skills/ontology/ontology-validator/scripts/completeness_checker.py \107 --ontology cmso \108 --class "Crystal Structure" \109 --provided "has unit cell,has space group" \110 --json111112# Validate relationships113python3 skills/ontology/ontology-validator/scripts/relationship_checker.py \114 --ontology cmso \115 --relationships '[{"subject_class":"Computational Sample","property":"has material","object_class":"Material"}]' \116 --json117```118119## Error Handling120121| Error | Cause | Resolution |122|-------|-------|------------|123| `Class 'X' not found` | Invalid class name | Use ontology-explorer to find correct name |124| `Property 'X' not found` | Invalid property name | Use property_lookup.py to search |125| `Annotation must be a dict` | Wrong input format | Provide valid JSON dict |126| `Relationships must be a non-empty list` | Wrong input format | Provide JSON array of relationship dicts |127128## Interpretation Guidance129130- **Errors** indicate definite problems (unknown class/property, range mismatch)131- **Warnings** indicate potential issues (domain mismatch — may be intentional for subclasses)132- **Completeness score**: 0.0-1.0 ratio of provided vs. total tracked properties133- **required_missing**: must fix for valid annotation134- **recommended_missing**: should fix for quality135- **unrecognized**: may indicate typos or properties from a different ontology136137## Security138139### Input Validation140- `--ontology` is validated against registered ontology names in `ontology_registry.json` (fixed allowlist)141- `--annotation` JSON is parsed with `json.loads()` and validated as a dict with required `class` and `properties` keys142- `--class` names are validated against known classes in the ontology summary; unknown classes produce clear errors143- `--provided` property names are validated as comma-separated strings and matched against known properties144- `--relationships` JSON is parsed and validated as a non-empty list of dicts, each requiring `subject_class`, `property`, and `object_class` keys145146### File Access147- Scripts read pre-processed JSON files from the `references/` directory: `ontology_registry.json`, `cmso_summary.json`, `cmso_constraints.json` (all read-only)148- No scripts write to the filesystem; all output goes to stdout149- No network access is required150151### Tool Restrictions152- **Read**: Used to inspect script source, reference files, and ontology constraint data153- **Bash**: Used to execute the three Python validation scripts (`schema_checker.py`, `completeness_checker.py`, `relationship_checker.py`) with explicit argument lists154155### Safety Measures156- No `eval()`, `exec()`, or dynamic code generation157- All subprocess calls use explicit argument lists (no `shell=True`)158- JSON input parsing uses `json.loads()` only (no pickle, no YAML with unsafe loaders)159- Validation logic operates on pre-loaded in-memory data structures; no dynamic file discovery or traversal160161## Limitations162163- Constraints file is manually curated, not derived from OWL axioms164- Does not validate data types (e.g., whether a value is actually a float vs string)165- Does not validate cardinality (e.g., exactly one space group per structure)166- Subclass checking uses simple parent traversal, not full OWL reasoning167168## References169170- [Validation Rules](references/validation_rules.md) — what is validated and why171- [CMSO Constraints](references/cmso_constraints.json) — required/recommended properties per class172- [CMSO Guide](../ontology-explorer/references/cmso_guide.md) — CMSO ontology overview173174## Version History175176| Date | Version | Changes |177|------|---------|---------|178| 2026-02-25 | 1.0 | Initial release with CMSO validation support |