Validate material sample annotations against ontology constraints — check that class names and property names exist in the ontology, verify domain and range consistency for object property relationships, assess annotation completeness (required, recommended, and optional properties), and flag unknown or misspelled terms. Use when verifying that CMSO or other ontology annotations are correct before publishing, checking whether all required properties are present for a class like Crystal Structure or Unit Cell, auditing relationship triples between instances, or catching annotation errors early in a FAIR data workflow, even if the user only says "is my annotation correct" or "what am I missing."
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
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 (each unknown_class/unknown_property error carries a suggestions array of nearest matches), results.warnings, results.class_valid, results.properties_valid
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 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".)
Apply the nearest-match suggestions from the error, or use ontology-explorer to find the correct name
Property 'X' not found ... (did you mean 'Y'?)
Invalid/misspelled property name
Apply the nearest-match suggestions from the error, or 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. It weights required, recommended, and optional properties
equally, so a moderate score (e.g. 0.5-0.67) can coexist with missing
required properties. ALWAYS check required_missing first: a non-empty
required_missing means the annotation is invalid regardless of the score.
required_missing: must fix for valid annotation
recommended_missing: should fix for quality
unrecognized: may indicate typos or properties from a different ontology
Verification checklist
Ran schema_checker.py --json and recorded results.valid; confirmed results.errors is an empty array (a valid:true with any unknown_class/unknown_property error cannot occur, but confirm the array length is 0 rather than trusting the boolean alone).
For every domain_mismatch entry in results.warnings, recorded the property, its reported domain, and the class it was applied to, then made an explicit keep-or-move decision (warnings are not auto-fixed and may be intentional for a subclass).
Ran completeness_checker.py --json and confirmed results.required_missing is empty BEFORE quoting completeness_score — a non-empty required_missing means the annotation is invalid no matter how high the score is.
Recorded the exact completeness_score together with the required_missing, recommended_missing, and optional_missing lists (do not paraphrase the score as "complete" while any required item is missing).
For each unknown class/property error, recorded the suggestions[0] value and confirmed the corrected name actually exists in the ontology (re-ran the checker, or checked via ontology-explorer) rather than assuming the top suggestion is right.
Ran relationship_checker.py --json for every subject-property-object triple and confirmed each per-triple results.results[i].valid is true; recorded any results.errors strings naming the offending domain or range.
Confirmed the --ontology used (e.g. cmso, asmo) matches the ontology the annotation was authored against — a class can be "unknown" simply because the wrong constraints/summary file was loaded.
Common pitfalls & rationalizations
Tempting shortcut
Why it's wrong / what to do
"completeness_score is 0.67, so the annotation is basically complete."
The score weights required, recommended, and optional tiers equally, so a high score can still hide a missing required property. Check required_missing first; a non-empty list means invalid regardless of score.
"schema_checker returned only warnings, no errors, so I'll ignore them."
domain_mismatch warnings flag a property attached to a class that is not (a subclass of) its domain — often the property belongs on a different instance. Record each warning and decide explicitly; don't auto-dismiss.
"The class name didn't match but the validator gave a suggestion, so I'll just use it."
suggestions come from stdlib difflib fuzzy matching (cutoff 0.6) and can be wrong or empty. Verify the suggested name exists in the ontology before applying it.
"Two of the three relationships passed, so the triples are fine."
results.valid is the AND over all triples; you must inspect each results.results[i] and its errors. A single failing domain/range check invalidates the relationship set.
"It returned valid:true, so the annotation is semantically correct."
The checker only verifies class/property existence and domain/range against a manually curated constraints file. It does not check data types, cardinality, or value plausibility — valid:true is necessary, not sufficient.
"Property exists in the ontology, so it applies to my class."
Existence is checked against the full property set; domain applicability is a separate subclass-aware check. A real property can still trigger a domain_mismatch warning on the wrong class.
"I'll trust the bare class name; substrings are close enough."
Domain/subclass matching is exact-equality plus parent traversal, NOT substring containment. Material is not credited with Crystalline Material properties; use the precise ontology class name.
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
Size/length caps reject abusive input (exit code 2): raw JSON inputs and annotation files are capped at 1,000,000 bytes; at most 1000 annotations/relationships/provided properties per call; each class or property name is capped at 500 characters. Class and property names must be strings.
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
Subclass-aware domain matching (fixes substring false positives/negatives), nearest-match suggestions on unknown class/property, input size/length caps, eval and doc corrections
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/heshamfs/ontology-validator17 author: HeshamFS18 version: "1.2.2"19 security_tier: high20 security_reviewed: true21 tested_with:22 - claude-code23 last_evaluated: "2026-06-24"24 eval_cases: 525 last_reviewed: "2026-06-23"26 standards:27 - "CMSO — Computational Material Sample Ontology v0.0.1 (OCDO, purls.helmholtz-metadaten.de/cmso/)"28 - "ASMO — Atomistic Simulation Methods Ontology (OCDO)"29 - "W3C OWL 2 / RDFS domain, range, and rdfs:subClassOf semantics"30 - "FAIR Guiding Principles (Wilkinson et al. 2016)"31---3233# Ontology Validator3435## Goal3637Validate that material sample annotations comply with ontology constraints: correct class names, valid properties, consistent domain/range relationships, and required fields present.3839## Requirements4041- Python 3.10+42- No external dependencies (Python standard library only)43- Requires ontology-explorer's `cmso_summary.json` and `ontology_registry.json`4445## Inputs to Gather4647| Input | Description | Example |48|-------|-------------|---------|49| Annotation | JSON dict or list of annotation dicts | `{"class":"UnitCell","properties":{"has Bravais lattice":"cF"}}` |50| Class name | Class to check completeness for | `Crystal Structure` |51| Provided properties | Comma-separated property names | `"has unit cell,has space group"` |52| Relationships | JSON array of subject-property-object triples | `[{"subject_class":"Material","property":"has structure","object_class":"Crystal Structure"}]` |5354## Decision Guidance5556```57What do you need to validate?58├── An annotation (classes and properties are correct)59│ └── schema_checker.py --ontology cmso --annotation '<json>'60├── Completeness of a class annotation61│ └── completeness_checker.py --ontology cmso --class <name> --provided <props>62└── Object property relationships63 └── relationship_checker.py --ontology cmso --relationships '<json>'64```6566## Script Outputs (JSON Fields)6768| Script | Key Outputs |69|--------|-------------|70| `scripts/schema_checker.py` | `results.valid`, `results.errors` (each unknown_class/unknown_property error carries a `suggestions` array of nearest matches), `results.warnings`, `results.class_valid`, `results.properties_valid` |71| `scripts/completeness_checker.py` | `results.completeness_score`, `results.required_missing`, `results.recommended_missing`, `results.optional_missing`, `results.unrecognized` |72| `scripts/relationship_checker.py` | `results.valid`, `results.results`, `results.errors` |7374## Workflow75761. After mapping a sample with ontology-mapper, pass the annotations to `schema_checker.py` to verify correctness.772. For a specific class, use `completeness_checker.py` to see what required/recommended properties are missing.783. When building relationships between instances, use `relationship_checker.py` to ensure domain/range consistency.7980## Conversational Workflow Example8182```83User: I annotated my sample as CrystalStructure with properties hasUnitCell and hasBasis.84 Is this correct and complete?8586Agent: Let me both validate the annotation and check its completeness.8788[Runs: schema_checker.py --ontology cmso --annotation89 '{"class":"Crystal Structure","properties":{"has unit cell":true,"has basis":true}}' --json]90[Runs: completeness_checker.py --ontology cmso --class "Crystal Structure"91 --provided "has unit cell,has basis" --json]9293From schema_checker.py (results.warnings):94- has unit cell: valid for Crystal Structure95- has basis: domain_mismatch warning — its domain is "Unit Cell", not96 Crystal Structure (so this property belongs on the Unit Cell instance)9798From completeness_checker.py (results, completeness_score = 0.5):99- **required_missing**: has space group100101So: add "has space group" to the Crystal Structure annotation, and move102"has basis" onto the Unit Cell annotation. (The domain insight comes from103schema_checker.py's warnings; completeness_checker.py only reports the104missing required "has space group".)105```106107## CLI Examples108109```bash110# Validate an annotation111python3 skills/ontology/ontology-validator/scripts/schema_checker.py \112 --ontology cmso \113 --annotation '{"class":"Unit Cell","properties":{"has Bravais lattice":"cF"}}' \114 --json115116# Check completeness117python3 skills/ontology/ontology-validator/scripts/completeness_checker.py \118 --ontology cmso \119 --class "Crystal Structure" \120 --provided "has unit cell,has space group" \121 --json122123# Validate relationships124python3 skills/ontology/ontology-validator/scripts/relationship_checker.py \125 --ontology cmso \126 --relationships '[{"subject_class":"Computational Sample","property":"has material","object_class":"Material"}]' \127 --json128```129130## Error Handling131132| Error | Cause | Resolution |133|-------|-------|------------|134| `Class 'X' not found ... (did you mean 'Y'?)` | Invalid/misspelled class name | Apply the nearest-match `suggestions` from the error, or use ontology-explorer to find the correct name |135| `Property 'X' not found ... (did you mean 'Y'?)` | Invalid/misspelled property name | Apply the nearest-match `suggestions` from the error, or use property_lookup.py to search |136| `Annotation must be a dict` | Wrong input format | Provide valid JSON dict |137| `Relationships must be a non-empty list` | Wrong input format | Provide JSON array of relationship dicts |138139## Interpretation Guidance140141- **Errors** indicate definite problems (unknown class/property, range mismatch)142- **Warnings** indicate potential issues (domain mismatch — may be intentional for subclasses)143- **Completeness score**: 0.0-1.0 ratio of provided vs. total tracked144 properties. It weights required, recommended, and optional properties145 **equally**, so a moderate score (e.g. 0.5-0.67) can coexist with missing146 required properties. ALWAYS check `required_missing` first: a non-empty147 `required_missing` means the annotation is invalid regardless of the score.148- **required_missing**: must fix for valid annotation149- **recommended_missing**: should fix for quality150- **unrecognized**: may indicate typos or properties from a different ontology151152## Verification checklist153154- [ ] Ran `schema_checker.py --json` and recorded `results.valid`; confirmed `results.errors` is an empty array (a `valid:true` with any `unknown_class`/`unknown_property` error cannot occur, but confirm the array length is 0 rather than trusting the boolean alone).155- [ ] For every `domain_mismatch` entry in `results.warnings`, recorded the property, its reported `domain`, and the class it was applied to, then made an explicit keep-or-move decision (warnings are not auto-fixed and may be intentional for a subclass).156- [ ] Ran `completeness_checker.py --json` and confirmed `results.required_missing` is empty BEFORE quoting `completeness_score` — a non-empty `required_missing` means the annotation is invalid no matter how high the score is.157- [ ] Recorded the exact `completeness_score` together with the `required_missing`, `recommended_missing`, and `optional_missing` lists (do not paraphrase the score as "complete" while any required item is missing).158- [ ] For each unknown class/property error, recorded the `suggestions[0]` value and confirmed the corrected name actually exists in the ontology (re-ran the checker, or checked via ontology-explorer) rather than assuming the top suggestion is right.159- [ ] Ran `relationship_checker.py --json` for every subject-property-object triple and confirmed each per-triple `results.results[i].valid` is true; recorded any `results.errors` strings naming the offending `domain` or `range`.160- [ ] Confirmed the `--ontology` used (e.g. `cmso`, `asmo`) matches the ontology the annotation was authored against — a class can be "unknown" simply because the wrong constraints/summary file was loaded.161162## Common pitfalls & rationalizations163164| Tempting shortcut | Why it's wrong / what to do |165|-------------------|------------------------------|166| "completeness_score is 0.67, so the annotation is basically complete." | The score weights required, recommended, and optional tiers **equally**, so a high score can still hide a missing required property. Check `required_missing` first; a non-empty list means invalid regardless of score. |167| "schema_checker returned only warnings, no errors, so I'll ignore them." | `domain_mismatch` warnings flag a property attached to a class that is not (a subclass of) its domain — often the property belongs on a different instance. Record each warning and decide explicitly; don't auto-dismiss. |168| "The class name didn't match but the validator gave a suggestion, so I'll just use it." | `suggestions` come from stdlib `difflib` fuzzy matching (cutoff 0.6) and can be wrong or empty. Verify the suggested name exists in the ontology before applying it. |169| "Two of the three relationships passed, so the triples are fine." | `results.valid` is the AND over all triples; you must inspect each `results.results[i]` and its `errors`. A single failing domain/range check invalidates the relationship set. |170| "It returned valid:true, so the annotation is semantically correct." | The checker only verifies class/property existence and domain/range against a **manually curated** constraints file. It does not check data types, cardinality, or value plausibility — `valid:true` is necessary, not sufficient. |171| "Property exists in the ontology, so it applies to my class." | Existence is checked against the full property set; domain applicability is a separate subclass-aware check. A real property can still trigger a `domain_mismatch` warning on the wrong class. |172| "I'll trust the bare class name; substrings are close enough." | Domain/subclass matching is exact-equality plus parent traversal, NOT substring containment. `Material` is not credited with `Crystalline Material` properties; use the precise ontology class name. |173174## Security175176### Input Validation177- `--ontology` is validated against registered ontology names in `ontology_registry.json` (fixed allowlist)178- `--annotation` JSON is parsed with `json.loads()` and validated as a dict with required `class` and `properties` keys179- `--class` names are validated against known classes in the ontology summary; unknown classes produce clear errors180- `--provided` property names are validated as comma-separated strings and matched against known properties181- `--relationships` JSON is parsed and validated as a non-empty list of dicts, each requiring `subject_class`, `property`, and `object_class` keys182- Size/length caps reject abusive input (exit code 2): raw JSON inputs and annotation files are capped at 1,000,000 bytes; at most 1000 annotations/relationships/provided properties per call; each class or property name is capped at 500 characters. Class and property names must be strings.183184### File Access185- Scripts read pre-processed JSON files from the `references/` directory: `ontology_registry.json`, `cmso_summary.json`, `cmso_constraints.json` (all read-only)186- No scripts write to the filesystem; all output goes to stdout187- No network access is required188189### Tool Restrictions190- **Read**: Used to inspect script source, reference files, and ontology constraint data191- **Bash**: Used to execute the three Python validation scripts (`schema_checker.py`, `completeness_checker.py`, `relationship_checker.py`) with explicit argument lists192193### Safety Measures194- No `eval()`, `exec()`, or dynamic code generation195- All subprocess calls use explicit argument lists (no `shell=True`)196- JSON input parsing uses `json.loads()` only (no pickle, no YAML with unsafe loaders)197- Validation logic operates on pre-loaded in-memory data structures; no dynamic file discovery or traversal198199## Limitations200201- Constraints file is manually curated, not derived from OWL axioms202- Does not validate data types (e.g., whether a value is actually a float vs string)203- Does not validate cardinality (e.g., exactly one space group per structure)204- Subclass checking uses simple parent traversal, not full OWL reasoning205206## References207208- [Validation Rules](references/validation_rules.md) — what is validated and why209- [CMSO Constraints](references/cmso_constraints.json) — required/recommended properties per class210- [CMSO Guide](../ontology-explorer/references/cmso_guide.md) — CMSO ontology overview211212## Version History213214| Date | Version | Changes |215|------|---------|---------|216| 2026-06-23 | 1.2.0 | Subclass-aware domain matching (fixes substring false positives/negatives), nearest-match suggestions on unknown class/property, input size/length caps, eval and doc corrections |217| 2026-02-25 | 1.0 | Initial release with CMSO validation support |
Run npx get-skill add heshamfs/ontology-validator in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Validate material sample annotations against ontology constraints — check that class names and property names exist in the ontology, verify domain and range consistency for object property relationships, assess annotation completeness (required, recommended, and optional properties), and flag unknown or misspelled terms. Use when verifying that CMSO or other ontology annotations are correct before publishing, checking whether all required properties are present for a class like Crystal Structure or Unit Cell, auditing relationship triples between instances, or catching annotation errors early in a FAIR data workflow, even if the user only says "is my annotation correct" or "what am I missing." It is listed under Productivity on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
HeshamFS (@heshamfs) published this skill. Their other Agent Skills are listed on their SkillMD profile.