glam/.opencode/rules/mapping-specificity-hypernym-rule.md

Mapping Specificity Rule: Broad vs Narrow vs Exact Mappings

🚨 CRITICAL: Mapping Semantics

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:

AcademicArchiveRecordSetType:
  exact_mappings:
    - rico:RecordSetType  # WRONG: This implies AcademicArchiveRecordSetType == RecordSetType

✅ CORRECT:

AcademicArchiveRecordSetType:
  broad_mappings:
    - rico:RecordSetType  # CORRECT: RecordSetType is broader

❌ WRONG:

SocialMovement:
  exact_mappings:
    - schema:Organization # WRONG: SocialMovement is a specific TYPE of Organization

✅ CORRECT:

SocialMovement:
  broad_mappings:
    - schema:Organization # CORRECT

Verification Checklist

• Does the exact_mapping represent the exact same scope?
• If the external term is a generic parent class (e.g., Type, Concept, Entity), move it to broad_mappings.
• If the external term is a specific instance or subclass, check narrow_mappings.