glam/.opencode/rules/linkml/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.
   • CRITICAL: Exact means the SAME semantic scope - neither broader nor narrower!
   • DO NOT AVOID EXACT BY DEFAULT: If equivalence is verified (including class/property category match and ontology definition review), exact_mappings SHOULD be used.

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, prov:Activity, schema:Thing, schema:Organization, schema:Action, rico:RecordSetType, crm:E55_Type.

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).

4. Close Mappings (skos:closeMatch): Use when the external concept is similar but not exactly equivalent.

   • Example: hc:AccessPolicy close_mappings dcterms:accessRights (related but different scope).

5. Related Mappings (skos:relatedMatch): Use for non-hierarchical relationships.

   • Example: hc:Collection related_mappings rico:RecordSet.

🚨 Type Compatibility Rule

Classes map to classes, properties map to properties. Never mix types in mappings.

Your Element	Valid Mapping Target
Class	Class (owl:Class, rdfs:Class)
Slot	Property (owl:ObjectProperty, owl:DatatypeProperty, rdf:Property)

❌ WRONG:

# AccessApplication is a CLASS, schema:Action is a CLASS - but Action is BROADER
AccessApplication:
  exact_mappings:
    - schema:Action  # WRONG: Action is a hypernym, not equivalent

✅ CORRECT:

AccessApplication:
  broad_mappings:
    - schema:Action  # CORRECT: Action is the broader category

🚨 No Self/Internal Exact Mappings

exact_mappings MUST NOT contain self-references or internal HC class references for the same concept.

❌ WRONG:

AcademicArchive:
  exact_mappings:
    - hc:AcademicArchive  # Self/internal reference; not an external equivalence mapping

✅ CORRECT:

AcademicArchive:
  exact_mappings:
    - wd:Q27032435  # External concept with equivalent semantic scope

Use exact_mappings only for equivalent terms in external ontologies or external controlled vocabularies, not for repeating the class itself.

✅ Positive Guidance: When Exact Mapping Is Correct

Use exact_mappings when all checks below pass:

• Semantic scope is equivalent (not parent/child, not merely similar)
• Ontological category matches (Class↔Class, Slot↔Property)
• Target term is verified in the ontology source files under data/ontology/ or verified Wikidata entity metadata
• No self/internal duplication (no hc: self-reference for the same concept)

✅ CORRECT:

Person:
  exact_mappings:
    - schema:Person

Acquisition:
  exact_mappings:
    - crm:E8_Acquisition

Do not downgrade a truly equivalent mapping to close_mappings or broad_mappings just to be conservative.

Common Hypernyms That Are NEVER Exact Mappings

These terms are always BROADER than your specific class - never use them as exact_mappings:

Hypernym	What It Means	Use Instead
schema:Action	Any action	broad_mappings
schema:Organization	Any organization	broad_mappings
schema:Thing	Anything at all	broad_mappings
schema:PropertyValue	Any property value	broad_mappings
schema:Permit	Any permit	broad_mappings
prov:Activity	Any activity	broad_mappings
prov:Entity	Any entity	broad_mappings
skos:Concept	Any concept	broad_mappings
crm:E55_Type	Any type classification	broad_mappings
crm:E42_Identifier	Any identifier	broad_mappings
rico:Identifier	Any identifier	broad_mappings
dcat:DataService	Any data service	broad_mappings

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

❌ WRONG:

AccessApplication:
  exact_mappings:
    - schema:Action  # WRONG: Action is a hypernym

✅ CORRECT:

AccessApplication:
  broad_mappings:
    - schema:Action  # CORRECT: Action is the broader category

How to Determine Mapping Type

Ask these questions:

1. Is it the SAME thing? → exact_mappings

   • "Could I swap these two terms in any context without changing meaning?"
   • If NO, it's not an exact mapping

2. Is the external term a PARENT category? → broad_mappings

   • "Is my class a TYPE OF the external term?"
   • Example: AccessApplication IS-A Action

3. Is the external term a CHILD category? → narrow_mappings

   • "Is the external term a TYPE OF my class?"
   • Example: Library IS-A Organization (so Organization has narrow_mapping to Library)

4. Is it similar but not hierarchical? → close_mappings

   • "Related but not equivalent or hierarchical"

5. Is there some other relationship? → related_mappings

   • "Connected in some way"

Verification Checklist

• Does the exact_mapping represent the exact same scope?
• Is the external term a generic parent class (e.g., Type, Concept, Entity, Action, Activity, Organization)? → Move to broad_mappings
• Is the external term a specific instance or subclass? → Check narrow_mappings
• Is the external term the same type (class→class, property→property)?
• Would swapping the terms change the meaning? If yes, not an exact_mapping