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`.
    *   **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**:
```yaml
# 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**:
```yaml
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**:
```yaml
AcademicArchive:
  exact_mappings:
    - hc:AcademicArchive  # Self/internal reference; not an external equivalence mapping
```

✅ **CORRECT**:
```yaml
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**:
```yaml
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**:
```yaml
AcademicArchiveRecordSetType:
  exact_mappings:
    - rico:RecordSetType  # WRONG: This implies AcademicArchiveRecordSetType == RecordSetType
```

✅ **CORRECT**:
```yaml
AcademicArchiveRecordSetType:
  broad_mappings:
    - rico:RecordSetType  # CORRECT: RecordSetType is broader
```

❌ **WRONG**:
```yaml
SocialMovement:
  exact_mappings:
    - schema:Organization # WRONG: SocialMovement is a specific TYPE of Organization
```

✅ **CORRECT**:
```yaml
SocialMovement:
  broad_mappings:
    - schema:Organization # CORRECT
```

❌ **WRONG**:
```yaml
AccessApplication:
  exact_mappings:
    - schema:Action  # WRONG: Action is a hypernym
```

✅ **CORRECT**:
```yaml
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`