LinkML Slot File Editing Rules

Rule 1: Preserve Original Descriptions

NEVER alter the original English description field of LinkML slot files.

When editing slot files:

Keep the original description text exactly as provided
Translations in alt_descriptions must accurately reflect the original English description
Do not paraphrase, expand, or "improve" the original description
If the description seems unclear, ask the user before making changes

Rule 2: Translation Accuracy

All alt_descriptions translations must be faithful translations of the original English description, not creative interpretations or expansions.

Rule 3: Description Field Purity

The description field must contain ONLY the semantic definition of the slot.

Comments, migration notes, usage examples, and other metadata MUST be placed in the appropriate YAML keys:

Content Type	Correct Location	WRONG Location
Semantic definition	`description`	-
Migration notes	`comments`	`description`
Usage notes	`comments`	`description`
Examples	`examples`	`description`
Ontology alignment info	`comments` (or header)	`description`
Rule compliance notes	`comments`	`description`
Temporal semantics notes	`comments`	`description`

❌ WRONG: Embedding comments in description

slots:
  my_slot:
    description: |
      To possess or be associated with structured data.

      MIGRATED from `old_slot_name` per Rule 53.
      
      **USAGE**: Used for X, Y, Z.

✅ CORRECT: Separate description from comments

slots:
  my_slot:
    description: |
      To possess or be associated with structured data.      
    comments:
      - MIGRATED from old_slot_name per slot_fixes.yaml (Rule 53).
      - |
        **USAGE**: Used for X, Y, Z.

Why This Matters

Machine readability: Tools parsing description expect only semantic content
Translation accuracy: Only the semantic definition should be translated to alt_descriptions
Clean documentation: Separation of concerns makes files easier to maintain
Consistency: All metadata follows the same pattern across all slot files

2.2 KiB Raw Blame History