pv-mapping
Map permissible values in LinkML enums to ontology terms. Use this skill when: (1) Adding or updating ontology mappings (meaning: field) for enum permissible values, (2) Fixing validation errors from linkml-term-validator, (3) User asks to map enums to ontology terms or fix CURIE mappings. This skill covers OAK/runoak lookup, CURIE verification, and validation workflows.
When & Why to Use This Skill
This Claude skill automates the complex process of mapping LinkML enum permissible values to standardized ontology terms. By leveraging the Ontology Access Kit (OAK), it ensures semantic precision through real-time CURIE verification, automated term lookups, and rigorous schema validation, making it an essential tool for data architects and bioinformaticians working with semantic data models.
Use Cases
- Scenario 1: Updating LinkML schemas by automatically finding and mapping permissible values to verified ontology terms (e.g., NCIT, SO) to enhance data interoperability.
- Scenario 2: Resolving 'linkml-term-validator' errors by identifying invalid CURIEs, fixing label mismatches, and ensuring all mappings resolve to the correct semantic concepts.
- Scenario 3: Streamlining the data modeling workflow by using runoak commands to search for and verify ontology labels and CURIEs without leaving the development environment.
- Scenario 4: Maintaining high-quality metadata standards by validating existing mappings and removing obsolete or incorrect CURIEs that fail validation checks.
| name | pv-mapping |
|---|---|
| description | > |
| (1) Adding or updating ontology mappings (meaning | field) for enum permissible values, |
Permissible Value Ontology Mapping
Core Rules
- Never change PERMISSIBLE_VALUE names - Keep uppercase names like
NUCLEIC_ACID - Use
title:for ontology label - Match the ontology term's label - Use
meaning:for CURIE - Always verify via runoak before adding - Never guess CURIEs - Wrong mappings are worse than no mappings
Workflow
1. Look up term via runoak
# Search for terms
runoak -i sqlite:obo:ncit search "nucleic acid"
# Verify a CURIE exists and get its label
runoak -i sqlite:obo:ncit info NCIT:C706
2. Add mapping
NUCLEIC_ACID:
title: Nucleic Acids # matches ontology term label
description: DNA or RNA sample
meaning: NCIT:C706 # verified CURIE
Note that either the permissible value key, the title, or one of the aliases should be a (case insensitive) match to the ontology term.
If there is already a canonical meaning field, OR the concept is not a close map, then linkml close/narrow/broad/exact mappings can be used:
NUCLEIC_ACID:
title: Nucleic Acids # matches ontology term label
description: DNA or RNA sample
meaning: NCIT:C706 # verified CURIE
close_mappings:
- SO:0000348. # label is nucleic_acid
aliases:
- nucleic_acid # to match SO
3. Validate
just validate
Interpreting Validation Errors
| Error Type | Action |
|---|---|
| "resolves to [wrong concept]" | Fix immediately - CURIE points to wrong term |
| "label mismatch" | Usually OK - add title: to match label if needed, or use an aliases |
| "Could not retrieve" | Check CURIE format or remove if term doesn't exist |
Ontology Selection
See references/ontologies.md for:
- Domain-to-ontology mapping (which ontology for which concept type)
- CURIE format patterns for each ontology
- Additional runoak commands
When to Remove Mappings
Remove meaning: when:
- No appropriate ontology term exists
- CURIE consistently fails validation
- Mapped term is semantically incorrect or not the same concept