glam/.opencode/rules/exact-mapping-predicate-class-distinction.md

Exact Mapping Predicate/Class Distinction Rule

🚨 CRITICAL: The exact_mappings property implies semantic equivalence. Equivalence can only exist between elements of the same ontological category.

The Rule

1. Slots (Predicates) MUST ONLY have exact_mappings to ontology predicates (properties).

   • ❌ INVALID: Slot analyzes_or_analyzed maps to schema:object (a Class).
   • ✅ VALID: Slot analyzes_or_analyzed maps to crm:P129_is_about (a Property).

2. Classes (Entities) MUST ONLY have exact_mappings to ontology classes (entities).

   • ❌ INVALID: Class Person maps to foaf:name (a Property).
   • ✅ VALID: Class Person maps to foaf:Person (a Class).

3. When true equivalence exists and is verified, exact mapping is preferred.

   • ✅ VALID: Class Acquisition maps to crm:E8_Acquisition.
   • ✅ VALID: Slot mapped to an actually equivalent ontology property.
   • ❗ Do not avoid exact_mappings by default; avoid only when scope is broader/narrower/similar-but-not-equal.

Rationale

Mapping a slot (which defines a relationship or attribute) to a class (which defines a type of entity) is a category error. schema:object represents the class of objects, not the relationship of "having an object" or "analyzing an object".

Verification Checklist

When adding or reviewing exact_mappings:

• Is the LinkML element a Class or a Slot?
• Did you verify the target term type in the ontology definition files (do not rely on naming heuristics)?
• Do they match? (Class↔Class, Slot↔Property)
• If the target ontology uses opaque IDs (like CIDOC-CRM E55_Type), verify the type definition in the ontology file.
• If semantic scope is truly equivalent, use exact_mappings (not close/broad as a conservative fallback).

Common Pitfalls to Fix

• Mapping slots to schema:Object or schema:Thing.
• Mapping slots to skos:Concept.
• Mapping classes to schema:name or dc:title.