Rule: Canonical Slot Protection

Summary

When resolving slot aliases to canonical names, a slot name that has its own .yaml file (i.e., is itself a canonical slot) MUST NOT be replaced with a different canonical name, even if it also appears as an alias in another slot file.

Context

Slot files in schemas/20251121/linkml/modules/slots/ (top-level and new/) each define a canonical slot name. Some slot files also list aliases that overlap with canonical names from other slot files. These cross-references are accidental (e.g., indicating semantic relatedness) and should be corrected by removing the canonical names from the aliases lists in which they occur. The occurance of canonical names in alianses lists does NOT mean the referenced slot should be renamed.

Rule

Before renaming any slot reference (in slots:, slot_usage:, or imports: of class files), check whether the current name is itself a canonical slot name — i.e., whether a .yaml file exists for it in the slots directory.
If the name IS canonical (has its own .yaml file), do NOT rename it and do NOT redirect its import. The class file is correctly referencing that slot's own definition file.
Only rename a slot reference if the name does NOT have its own .yaml file and is ONLY found as an alias in another slot's file.

Examples

WRONG

# categorized_as.yaml defines aliases: [..., "has_type", ...]
# has_type.yaml exists with canonical name "has_type"

# WRONG: Renaming has_type -> categorized_as in a class file
# This destroys the valid reference to has_type.yaml
slots:
  - categorized_as  # was: has_type -- INCORRECT REPLACEMENT

CORRECT

# has_type.yaml exists => "has_type" is canonical => leave it alone
slots:
  - has_type  # CORRECT: has_type is canonical, keep it

# "custodian_type" does NOT have its own .yaml file
# "custodian_type" is listed as an alias in has_type.yaml
# => rename custodian_type -> has_type
slots:
  - has_type  # was: custodian_type -- CORRECT REPLACEMENT

Implementation Check

# Pseudocode for alias resolution
def should_rename(slot_name, alias_map, existing_slot_files):
    if slot_name in existing_slot_files:
        return False  # It's canonical — do not rename
    if slot_name in alias_map:
        return True   # It's only an alias — rename to canonical
    return False      # Unknown — leave alone

Rationale

Multiple slot files may list overlapping aliases by accident or for documentation or semantic linking purposes. A canonical slot name appearing as an alias in another file does not invalidate the original slot definition. Treating it as an alias would incorrectly redirect class files away from the slot's own definition, breaking the schema's intended structure.

2.8 KiB Raw Permalink Blame History