docs: Add Rule 53 for slot_fixes.yaml migration workflow
- Document that slot_fixes.yaml revision section is authoritative - Add link_branch explanation for nested class attributes - Clarify that deprecated slots must be fully removed, not just annotated
This commit is contained in:
kempersc
parent
13ba8fb09b
commit
9f9c69f7b8
2 changed files with 139 additions and 0 deletions
|
|
@ -31,10 +31,112 @@ The `slot_fixes.yaml` file has been **manually curated** to specify the exact re
|
||||||
- ✅ Follow the `revision` section TO THE LETTER
|
- ✅ Follow the `revision` section TO THE LETTER
|
||||||
- ✅ Use EXACTLY the slots and classes specified
|
- ✅ Use EXACTLY the slots and classes specified
|
||||||
- ✅ Apply ALL components of the revision (both slots AND classes)
|
- ✅ Apply ALL components of the revision (both slots AND classes)
|
||||||
|
- ✅ Interpret `link_branch` fields correctly (see below)
|
||||||
- ✅ Update `processed.status: true` after completing migration
|
- ✅ Update `processed.status: true` after completing migration
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Understanding `link_branch` in Revision Plans
|
||||||
|
|
||||||
|
🚨 **CRITICAL**: The `link_branch` field in revision plans indicates **nested class attributes**. Items with `link_branch: N` are slots/classes that belong TO the primary class, not standalone replacements.
|
||||||
|
|
||||||
|
### How to Interpret `link_branch`
|
||||||
|
|
||||||
|
| Revision Item | Meaning |
|
||||||
|
|---------------|---------|
|
||||||
|
| Items **WITHOUT** `link_branch` | **PRIMARY** slot and class to create |
|
||||||
|
| Items **WITH** `link_branch: 1` | First attribute branch that the primary class needs |
|
||||||
|
| Items **WITH** `link_branch: 2` | Second attribute branch that the primary class needs |
|
||||||
|
| Items **WITH** `link_branch: N` | Nth attribute branch for the primary class |
|
||||||
|
|
||||||
|
### Example: `visitor_count` Revision
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
- original_slot_id: https://nde.nl/ontology/hc/slot/visitor_count
|
||||||
|
revision:
|
||||||
|
- label: has_or_had_quantity # PRIMARY SLOT (no link_branch)
|
||||||
|
type: slot
|
||||||
|
- label: Quantity # PRIMARY CLASS (no link_branch)
|
||||||
|
type: class
|
||||||
|
- label: has_or_had_measurement_unit # Quantity needs this slot
|
||||||
|
type: slot
|
||||||
|
link_branch: 1 # ← Branch 1: unit attribute
|
||||||
|
- label: MeasureUnit # Range of has_or_had_measurement_unit
|
||||||
|
type: class
|
||||||
|
value:
|
||||||
|
- visitors
|
||||||
|
link_branch: 1
|
||||||
|
- label: temporal_extent # Quantity needs this slot too
|
||||||
|
type: slot
|
||||||
|
link_branch: 2 # ← Branch 2: time attribute
|
||||||
|
- label: TimeSpan # Range of temporal_extent
|
||||||
|
type: class
|
||||||
|
link_branch: 2
|
||||||
|
```
|
||||||
|
|
||||||
|
**Interpretation**: This creates:
|
||||||
|
1. **Primary**: `has_or_had_quantity` slot → `Quantity` class
|
||||||
|
2. **Branch 1**: `Quantity.has_or_had_measurement_unit` → `MeasureUnit` (with value "visitors")
|
||||||
|
3. **Branch 2**: `Quantity.temporal_extent` → `TimeSpan`
|
||||||
|
|
||||||
|
### Resulting Class Structure
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# The Quantity class should have these slots:
|
||||||
|
Quantity:
|
||||||
|
slots:
|
||||||
|
- has_or_had_measurement_unit # From link_branch: 1
|
||||||
|
- temporal_extent # From link_branch: 2
|
||||||
|
```
|
||||||
|
|
||||||
|
### Complex Example: `visitor_conversion_rate`
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
- original_slot_id: https://nde.nl/ontology/hc/slot/visitor_conversion_rate
|
||||||
|
revision:
|
||||||
|
- label: has_or_had_conversion_rate # PRIMARY SLOT
|
||||||
|
type: slot
|
||||||
|
- label: ConversionRate # PRIMARY CLASS
|
||||||
|
type: class
|
||||||
|
- label: has_or_had_type # ConversionRate.has_or_had_type
|
||||||
|
type: slot
|
||||||
|
link_branch: 1
|
||||||
|
- label: ConversionRateType # Abstract type class
|
||||||
|
type: class
|
||||||
|
link_branch: 1
|
||||||
|
- label: includes_or_included # ConversionRateType hierarchy slot
|
||||||
|
type: slot
|
||||||
|
link_branch: 1
|
||||||
|
- label: ConversionRateTypes # Concrete subclasses file
|
||||||
|
type: class
|
||||||
|
link_branch: 1
|
||||||
|
- label: temporal_extent # ConversionRate.temporal_extent
|
||||||
|
type: slot
|
||||||
|
link_branch: 2
|
||||||
|
- label: TimeSpan # Range of temporal_extent
|
||||||
|
type: class
|
||||||
|
link_branch: 2
|
||||||
|
```
|
||||||
|
|
||||||
|
**Interpretation**:
|
||||||
|
1. **Primary**: `has_or_had_conversion_rate` → `ConversionRate`
|
||||||
|
2. **Branch 1**: Type hierarchy with `ConversionRateType` (abstract) + `ConversionRateTypes` (concrete subclasses)
|
||||||
|
3. **Branch 2**: Temporal tracking via `temporal_extent` → `TimeSpan`
|
||||||
|
|
||||||
|
### Migration Checklist for `link_branch` Revisions
|
||||||
|
|
||||||
|
- [ ] Create/verify PRIMARY slot exists
|
||||||
|
- [ ] Create/verify PRIMARY class exists
|
||||||
|
- [ ] For EACH `link_branch: N`:
|
||||||
|
- [ ] Add the branch slot to PRIMARY class's `slots:` list
|
||||||
|
- [ ] Import the branch slot file
|
||||||
|
- [ ] Import the branch class file (if creating new class)
|
||||||
|
- [ ] Verify range of branch slot points to branch class
|
||||||
|
- [ ] Update consuming class to use PRIMARY slot (not deprecated slot)
|
||||||
|
- [ ] Update examples to show nested structure
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Mandatory: Follow slot_fixes.yaml Revisions Exactly
|
## Mandatory: Follow slot_fixes.yaml Revisions Exactly
|
||||||
|
|
||||||
**The `revision` section in `slot_fixes.yaml` is AUTHORITATIVE.** Do not substitute different slots based on your own judgment.
|
**The `revision` section in `slot_fixes.yaml` is AUTHORITATIVE.** Do not substitute different slots based on your own judgment.
|
||||||
|
|
|
||||||
37
AGENTS.md
37
AGENTS.md
|
|
@ -1603,6 +1603,43 @@ The `revision` section in `slot_fixes.yaml` specifies the EXACT slots and classe
|
||||||
- ❌ Partially apply revisions
|
- ❌ Partially apply revisions
|
||||||
- ❌ Add deprecation notes (keeping both old and new)
|
- ❌ Add deprecation notes (keeping both old and new)
|
||||||
|
|
||||||
|
**Understanding `link_branch` in Revisions**:
|
||||||
|
|
||||||
|
The `link_branch` field indicates **nested class attributes**:
|
||||||
|
|
||||||
|
| Revision Item | Meaning |
|
||||||
|
|---------------|---------|
|
||||||
|
| Items **WITHOUT** `link_branch` | PRIMARY slot and class to create |
|
||||||
|
| Items **WITH** `link_branch: 1` | First attribute the primary class needs |
|
||||||
|
| Items **WITH** `link_branch: 2` | Second attribute the primary class needs |
|
||||||
|
|
||||||
|
**Example - `visitor_count` with `link_branch`**:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
- original_slot_id: https://nde.nl/ontology/hc/slot/visitor_count
|
||||||
|
revision:
|
||||||
|
- label: has_or_had_quantity # PRIMARY SLOT
|
||||||
|
type: slot
|
||||||
|
- label: Quantity # PRIMARY CLASS
|
||||||
|
type: class
|
||||||
|
- label: has_or_had_measurement_unit # Quantity.has_or_had_measurement_unit
|
||||||
|
type: slot
|
||||||
|
link_branch: 1 # ← Branch 1
|
||||||
|
- label: MeasureUnit # Range of branch 1 slot
|
||||||
|
type: class
|
||||||
|
link_branch: 1
|
||||||
|
- label: temporal_extent # Quantity.temporal_extent
|
||||||
|
type: slot
|
||||||
|
link_branch: 2 # ← Branch 2
|
||||||
|
- label: TimeSpan # Range of branch 2 slot
|
||||||
|
type: class
|
||||||
|
link_branch: 2
|
||||||
|
```
|
||||||
|
|
||||||
|
**Interpretation**: Create `Quantity` class with TWO slots:
|
||||||
|
- `has_or_had_measurement_unit` → `MeasureUnit` (branch 1)
|
||||||
|
- `temporal_extent` → `TimeSpan` (branch 2)
|
||||||
|
|
||||||
**Example - Following slot_fixes.yaml**:
|
**Example - Following slot_fixes.yaml**:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue