glam/AGENTS.md

Rule 63: Mapping Specificity - Broad vs Narrow vs Exact Mappings

🚨 CRITICAL: 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

See: .opencode/rules/mapping-specificity-hypernym-rule.md for complete documentation.

Rule: Ontology Detection vs Heuristics

🚨 CRITICAL: When detecting classes and predicates in data/ontology/ or external ontology files, you must read the actual ontology definitions (e.g., RDF, OWL, TTL files) to determine if a term is a Class or a Property. Do not rely on naming heuristics (like "Capitalized means Class").

See: .opencode/rules/ontology-detection-rule.md