39 lines
2 KiB
Markdown
39 lines
2 KiB
Markdown
### Rule 63: Mapping Specificity - Broad vs Narrow vs Exact Mappings
|
|
|
|
🚨 **CRITICAL**: When mapping LinkML classes to external ontologies, you MUST distinguish between **equivalence**, **hypernyms** (broader concepts), and **hyponyms** (narrower concepts).
|
|
|
|
**The Rule**:
|
|
|
|
1. **Exact Mappings (`skos:exactMatch`)**: Use ONLY when the external concept is **semantically equivalent** to your class.
|
|
* *Example*: `hc:Person` `exact_mappings` `schema:Person`.
|
|
|
|
2. **Broad Mappings (`skos:broadMatch`)**: Use when the external concept is a **hypernym** (a broader, more general category) of your class.
|
|
* *Example*: `hc:AcademicArchiveRecordSetType` `broad_mappings` `rico:RecordSetType`.
|
|
* *Rationale*: An academic archive record set *is a* record set type, but `rico:RecordSetType` is broader.
|
|
* *Common Hypernyms*: `skos:Concept`, `prov:Entity`, `schema:Thing`, `schema:Organization`, `rico:RecordSetType`.
|
|
|
|
3. **Narrow Mappings (`skos:narrowMatch`)**: Use when the external concept is a **hyponym** (a narrower, more specific category) of your class.
|
|
* *Example*: `hc:Organization` `narrow_mappings` `hc:Library` (if mapping inversely).
|
|
|
|
**Common Violations to Avoid**:
|
|
|
|
❌ **WRONG**:
|
|
```yaml
|
|
AcademicArchiveRecordSetType:
|
|
exact_mappings:
|
|
- rico:RecordSetType # WRONG: This implies AcademicArchiveRecordSetType == RecordSetType
|
|
```
|
|
|
|
✅ **CORRECT**:
|
|
```yaml
|
|
AcademicArchiveRecordSetType:
|
|
broad_mappings:
|
|
- rico:RecordSetType # CORRECT: RecordSetType is broader
|
|
```
|
|
|
|
**See**: `.opencode/rules/mapping-specificity-hypernym-rule.md` for complete documentation.
|
|
|
|
### Rule: Ontology Detection vs Heuristics
|
|
🚨 **CRITICAL**: When detecting classes and predicates in `data/ontology/` or external ontology files, you must **read the actual ontology definitions** (e.g., RDF, OWL, TTL files) to determine if a term is a Class or a Property. Do not rely on naming heuristics (like "Capitalized means Class").
|
|
|
|
**See**: `.opencode/rules/ontology-detection-rule.md`
|