Rule 48: Class Files Must Not Define Inline Slots

🚨 CRITICAL: LinkML class files in schemas/20251121/linkml/modules/classes/ MUST NOT define their own slots inline. All slots MUST be imported from the centralized modules/slots/ directory.

Problem Statement

When class files define their own slots (e.g., AccessRestriction.yaml defining its own slot properties), this creates:

Duplication: Same slot semantics defined in multiple places
Inconsistency: Slot definitions may diverge between files
Frontend Issues: LinkML viewer cannot properly render slot relationships
Maintenance Burden: Changes require updates in multiple locations

Architecture Requirement

schemas/20251121/linkml/
├── modules/
│   ├── classes/           # Class definitions ONLY
│   │   └── *.yaml         # NO inline slot definitions
│   ├── slots/             # ALL slot definitions go here
│   │   └── *.yaml         # One file per slot or logical group
│   └── enums/             # Enumeration definitions

Correct Pattern

Class file (modules/classes/AccessRestriction.yaml):

id: https://nde.nl/ontology/hc/class/AccessRestriction
name: AccessRestriction
prefixes:
  hc: https://nde.nl/ontology/hc/
  linkml: https://w3id.org/linkml/

imports:
  - linkml:types
  - ../slots/restriction_type      # Import slot from centralized location
  - ../slots/restriction_reason
  - ../slots/applies_from
  - ../slots/applies_until

default_range: string

classes:
  AccessRestriction:
    class_uri: hc:AccessRestriction
    description: >-
      Describes access restrictions on heritage collections or items.      
    slots:
      - restriction_type           # Reference slot by name
      - restriction_reason
      - applies_from
      - applies_until

Slot file (modules/slots/restriction_type.yaml):

id: https://nde.nl/ontology/hc/slot/restriction_type
name: restriction_type
prefixes:
  hc: https://nde.nl/ontology/hc/
  schema: http://schema.org/
  linkml: https://w3id.org/linkml/

imports:
  - linkml:types

slots:
  restriction_type:
    slot_uri: hc:restrictionType
    description: The type of access restriction applied.
    range: string
    exact_mappings:
      - schema:accessMode

Anti-Pattern (WRONG)

DO NOT define slots inline in class files:

# WRONG - AccessRestriction.yaml with inline slots
classes:
  AccessRestriction:
    slots:
      - restriction_type
      
slots:                           # ❌ DO NOT define slots here
  restriction_type:
    description: Type of restriction
    range: string

Identifying Violations

To find class files that incorrectly define slots:

# Find class files with inline slot definitions
grep -l "^slots:" schemas/20251121/linkml/modules/classes/*.yaml

Files that match need refactoring:

Extract slot definitions to modules/slots/
Add imports for the extracted slots
Remove inline slots: section from class file

Migration Workflow

Identify inline slots in class file
Check if slot exists in modules/slots/
If exists: Remove inline definition, add import
If not exists: Create new slot file in modules/slots/, then add import
Validate: Run linkml-validate to ensure schema integrity
Update manifest: Regenerate manifest.json if needed

Rationale

Single Source of Truth: Each slot defined exactly once
Reusability: Slots can be used across multiple classes
Frontend Compatibility: LinkML viewer depends on centralized slots for proper edge rendering in UML diagrams
Semantic Consistency: slot_uri and mappings defined once, applied everywhere
Maintenance: Changes to slot semantics applied in one place

3.9 KiB Raw Permalink Blame History