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

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?
• Does the target ontology term represent a Class (usually Capitalized) or a Property (usually lowercase)?
• 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.

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.