61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
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
|
|
|
|
```yaml
|
|
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
|
|
|
|
1. **Machine readability**: Tools parsing `description` expect only semantic content
|
|
2. **Translation accuracy**: Only the semantic definition should be translated to `alt_descriptions`
|
|
3. **Clean documentation**: Separation of concerns makes files easier to maintain
|
|
4. **Consistency**: All metadata follows the same pattern across all slot files
|