kempersc 554fe520ea Add comprehensive rules for LinkML schema management and ontology mapping

- Introduced Rule 42: No Ontology Prefixes in Slot Names to enforce clean naming conventions.
- Established Rule: No Rough Edits in Schema Files to ensure structural integrity during modifications.
- Implemented Rule: No Version Indicators in Names to maintain stable semantic naming.
- Created Rule: Ontology Detection vs Heuristics to emphasize the importance of verifying ontology definitions.
- Defined Rule 50: Ontology-to-LinkML Mapping Convention to standardize mapping practices.
- Added Rule: Polished Slot Storage Location to specify directory structure for polished slot files.
- Enforced Rule: Preserve Bespoke Slots Until Refactoring to prevent unintended migrations during slot updates.
- Instituted Rule 56: Semantic Consistency Over Simplicity to mandate execution of revisions in slot_fixes.yaml.
- Added new Genealogy Archives Registry Enrichment class with multilingual support and structured aliases.

2026-02-15 19:20:09 +01:00

3.5 KiB

Raw Blame History

Rule: Generic Slots, Specific Classes

Identifier: generic-slots-specific-classes Severity: CRITICAL

Core Principle

Slots MUST be generic predicates that can be reused across multiple classes. Classes MUST be specific to provide context and constraints.

DO NOT create class-specific slots when a generic predicate can be used.

Rationale

Predicate Proliferation: Creating bespoke slots for every class explodes the schema size (e.g., has_museum_name, has_library_name, has_archive_name instead of has_name).
Interoperability: Generic predicates (has_name, has_identifier, has_part) map cleanly to standard ontologies (Schema.org, Dublin Core, RiC-O).
Querying: It's easier to query "all entities with a name" than "all entities with museum_name OR library_name OR archive_name".
Maintenance: Updating one generic slot propagates to all classes.

Examples

❌ Anti-Pattern: Class-Specific Slots

# WRONG: Creating specific slots for each class
slots:
  has_museum_visitor_count:
    range: integer
  has_library_patron_count:
    range: integer

classes:
  Museum:
    slots:
      - has_museum_visitor_count
  Library:
    slots:
      - has_library_patron_count

✅ Correct Pattern: Generic Slot, Specific Class Usage

# CORRECT: One generic slot reused
slots:
  has_or_had_quantity:
    slot_uri: rico:hasOrHadQuantity
    range: Quantity
    multivalued: true

classes:
  Museum:
    slots:
      - has_or_had_quantity
    slot_usage:
      has_or_had_quantity:
        description: The number of visitors to the museum.

  Library:
    slots:
      - has_or_had_quantity
    slot_usage:
      has_or_had_quantity:
        description: The number of registered patrons.

Intermediate Class Pattern

Making slots generic often requires introducing Intermediate Classes to hold structured data, rather than flattening attributes onto the parent class.

❌ Anti-Pattern: Specific Flattened Slots

# WRONG: Flattened specific attributes
classes:
  Museum:
    slots:
      - has_museum_budget_amount
      - has_museum_budget_currency
      - has_museum_budget_year

✅ Correct Pattern: Generic Slot + Intermediate Class

# CORRECT: Generic slot pointing to structured class
slots:
  has_or_had_budget:
    range: Budget
    multivalued: true

classes:
  Museum:
    slots:
      - has_or_had_budget

  Budget:
    slots:
      - has_or_had_amount
      - has_or_had_currency
      - has_or_had_year

Specificity Levels

Level	Component	Example
Generic	Slot (Predicate)	`has_or_had_identifier`
Specific	Class (Subject/Object)	`ISILCode`
Specific	Slot Usage (Context)	"The ISIL code assigned to this library"

Migration Guide

If you encounter an overly specific slot:

Identify the generic concept (e.g., has_museum_opening_hours → has_opening_hours).
Check if a generic slot exists in modules/slots/.
If yes, use the generic slot and add slot_usage to the class.
If no, create the generic slot, not a specific one.

Naming Indicators

Reject slots containing:

Class names (e.g., has_custodian_name → has_name)
Narrow types (e.g., has_isbn_identifier → has_identifier)
Contextual specifics (e.g., has_primary_email → has_email + type/role)

3.5 KiB Raw Blame History