240 lines
7.8 KiB
Markdown
240 lines
7.8 KiB
Markdown
# Schema Authority Documentation Checklist
|
|
|
|
**Date**: 2025-11-21
|
|
**Task**: Establish LinkML schemas as single source of truth
|
|
**Status**: ✅ COMPLETE
|
|
|
|
---
|
|
|
|
## Objectives
|
|
|
|
- [x] Add "Schema Source of Truth" documentation to agent instructions
|
|
- [x] Update schema references to new `schemas/20251121/linkml/` location
|
|
- [x] Document schema hierarchy (authoritative vs. derived)
|
|
- [x] Provide workflow for schema changes
|
|
- [x] Warn against editing auto-generated files
|
|
|
|
---
|
|
|
|
## Files Updated
|
|
|
|
### 1. `AGENTS.md` ✅
|
|
**Location**: Root directory
|
|
**Status**: ✅ COMPLETE
|
|
|
|
- [x] Added Rule 0: LinkML Schemas Are the Single Source of Truth (line 24)
|
|
- [x] Documented master schema location: `schemas/20251121/linkml/`
|
|
- [x] Listed primary schema files (01_name_entity.yaml, 02_organization_observation_reconstruction.yaml)
|
|
- [x] Clarified derived files (RDF, TypeDB, UML, examples)
|
|
- [x] Documented regeneration workflow (edit LinkML → gen-owl → rdfpipe → validate)
|
|
- [x] Listed "Why LinkML is the Master" (5 reasons)
|
|
- [x] Documented NEVER/ALWAYS rules for agents
|
|
- [x] Added references to supporting docs (RDF_GENERATION_SUMMARY.md, etc.)
|
|
|
|
### 2. `.opencode/agent/README.md` ✅
|
|
**Location**: `.opencode/agent/` directory
|
|
**Status**: ✅ COMPLETE
|
|
|
|
- [x] Added "🚨 Schema Source of Truth" section (lines 5-63)
|
|
- [x] Updated schema version from v0.2.0 to v0.2.1
|
|
- [x] Updated all schema references to `schemas/20251121/linkml/`
|
|
- [x] Updated agent schema mappings to new class names:
|
|
- [x] `HeritageCustodian` → `CustodianAspect`
|
|
- [x] `Location` → `PlaceAspect`
|
|
- [x] `ChangeEvent` → `TemporalEvent`
|
|
- [x] `Identifier` → (unchanged)
|
|
- [x] Updated validation commands with correct paths
|
|
- [x] Added schema features list (ISO 20275, multi-aspect modeling, etc.)
|
|
- [x] Updated footer metadata (version, date, schema location)
|
|
|
|
### 3. `SESSION_SUMMARY_20251121_SCHEMA_AUTHORITY_COMPLETE.md` ✅
|
|
**Location**: Root directory
|
|
**Status**: ✅ COMPLETE
|
|
|
|
- [x] Documented session overview
|
|
- [x] Listed all changes made
|
|
- [x] Explained documentation hierarchy
|
|
- [x] Provided impact analysis
|
|
- [x] Created validation checklist
|
|
- [x] Listed next steps for future agents
|
|
- [x] Included technical context and statistics
|
|
|
|
### 4. `SCHEMA_AUTHORITY_CHECKLIST.md` ✅
|
|
**Location**: Root directory
|
|
**Status**: ✅ COMPLETE (this file)
|
|
|
|
- [x] Created comprehensive task checklist
|
|
- [x] Documented completion status
|
|
- [x] Listed verification steps
|
|
|
|
---
|
|
|
|
## Content Verification
|
|
|
|
### Rule 0 in `AGENTS.md`
|
|
|
|
- [x] Positioned before existing Rule 1 (ontology consultation)
|
|
- [x] Clear heading: "Rule 0: LinkML Schemas Are the Single Source of Truth"
|
|
- [x] Master schema location documented
|
|
- [x] Primary schema files listed with descriptions
|
|
- [x] Derived/generated files clearly marked
|
|
- [x] Workflow for schema changes (5 steps)
|
|
- [x] "Why LinkML is the Master" section (5 bullet points)
|
|
- [x] NEVER rules (3 items)
|
|
- [x] ALWAYS rules (4 items)
|
|
- [x] References to supporting documentation
|
|
|
|
### Schema Source of Truth Section in `.opencode/agent/README.md`
|
|
|
|
- [x] Prominent warning emoji (🚨)
|
|
- [x] Master schema location (same as AGENTS.md)
|
|
- [x] Primary schema files (same as AGENTS.md)
|
|
- [x] Derived/generated files (same as AGENTS.md)
|
|
- [x] Workflow for schema changes (same as AGENTS.md)
|
|
- [x] "Why LinkML is the Master" (same as AGENTS.md)
|
|
- [x] NEVER rules (same as AGENTS.md)
|
|
- [x] ALWAYS rules (same as AGENTS.md)
|
|
- [x] References to supporting documentation (same as AGENTS.md)
|
|
|
|
### Schema Reference Updates
|
|
|
|
- [x] All old `schemas/` paths updated to `schemas/20251121/linkml/`
|
|
- [x] Schema version updated from v0.2.0 to v0.2.1
|
|
- [x] ISO 20275 migration mentioned
|
|
- [x] Class name mappings updated to reflect new schema
|
|
- [x] Validation commands use correct paths
|
|
- [x] Footer metadata reflects current state
|
|
|
|
---
|
|
|
|
## Consistency Check
|
|
|
|
### Between `AGENTS.md` and `.opencode/agent/README.md`
|
|
|
|
- [x] Master schema location identical
|
|
- [x] Primary schema files identical
|
|
- [x] Derived/generated files identical
|
|
- [x] Workflow steps identical
|
|
- [x] "Why LinkML is the Master" identical
|
|
- [x] NEVER rules identical
|
|
- [x] ALWAYS rules identical
|
|
- [x] Reference links identical
|
|
|
|
### Schema Authority Principles
|
|
|
|
- [x] LinkML is authoritative (not RDF, TypeDB, or UML)
|
|
- [x] Edit LinkML first, then regenerate derived formats
|
|
- [x] Never edit auto-generated files directly
|
|
- [x] Always validate changes with linkml-validate
|
|
- [x] Document schema changes in YAML comments
|
|
- [x] Use version control for schema tracking
|
|
|
|
---
|
|
|
|
## Integration with Existing Documentation
|
|
|
|
### References Added
|
|
|
|
- [x] `schemas/20251121/RDF_GENERATION_SUMMARY.md` - RDF generation process
|
|
- [x] `docs/MIGRATION_GUIDE.md` - Schema migration procedures
|
|
- [x] LinkML documentation: https://linkml.io/
|
|
|
|
### Related Documentation (Cross-Check)
|
|
|
|
- [x] `SESSION_SUMMARY_20251121_ISO20275_COMPLETE.md` - Migration completion
|
|
- [x] `MIGRATION_CHECKLIST_ISO20275.md` - Migration tasks
|
|
- [x] `schemas/20251121/uml/MERMAID_UPDATE_SUMMARY.md` - Diagram fixes
|
|
- [x] All references to schema authority are consistent
|
|
|
|
---
|
|
|
|
## Testing and Validation
|
|
|
|
### Manual Review
|
|
|
|
- [x] Read full text of `AGENTS.md` Rule 0
|
|
- [x] Read full text of `.opencode/agent/README.md` schema section
|
|
- [x] Verify all schema paths use `schemas/20251121/linkml/`
|
|
- [x] Verify no references to old `schemas/` directory
|
|
- [x] Verify version numbers are v0.2.1
|
|
- [x] Verify class name mappings are correct
|
|
|
|
### Agent Comprehension Test
|
|
|
|
- [x] Rule 0 is positioned prominently (before other rules)
|
|
- [x] Schema hierarchy is clearly explained
|
|
- [x] Workflow steps are numbered and sequential
|
|
- [x] Warnings are explicit (❌ DO NOT, ✅ ALWAYS)
|
|
- [x] Examples are provided where helpful
|
|
- [x] References link to supporting docs
|
|
|
|
### Future-Proofing
|
|
|
|
- [x] Documentation explains WHY LinkML is master (not just HOW)
|
|
- [x] Workflow is detailed enough for agents to follow
|
|
- [x] Common mistakes are explicitly warned against
|
|
- [x] Migration procedures are documented for future schema changes
|
|
|
|
---
|
|
|
|
## Completion Criteria
|
|
|
|
### Primary Objectives
|
|
- [x] Schema authority clearly established
|
|
- [x] LinkML designated as single source of truth
|
|
- [x] Derived file types clearly identified
|
|
- [x] Workflow documented for schema changes
|
|
- [x] Both agent instruction files updated
|
|
|
|
### Secondary Objectives
|
|
- [x] Consistency between `AGENTS.md` and `.opencode/agent/README.md`
|
|
- [x] All schema paths updated to new location
|
|
- [x] Schema version updated to v0.2.1
|
|
- [x] Class name mappings updated
|
|
- [x] Session documentation complete
|
|
|
|
### Quality Criteria
|
|
- [x] Clear and unambiguous language
|
|
- [x] Prominent placement (Rule 0, top of agent README)
|
|
- [x] Visual warnings (❌/✅ icons)
|
|
- [x] Numbered workflows for easy following
|
|
- [x] References to supporting documentation
|
|
- [x] Examples provided where helpful
|
|
|
|
---
|
|
|
|
## Sign-Off
|
|
|
|
**Task**: Schema Authority Documentation
|
|
**Status**: ✅ COMPLETE
|
|
**Date**: 2025-11-21
|
|
|
|
**Files Modified**:
|
|
1. `AGENTS.md` (+58 lines)
|
|
2. `.opencode/agent/README.md` (+58 lines + scattered updates)
|
|
3. `SESSION_SUMMARY_20251121_SCHEMA_AUTHORITY_COMPLETE.md` (new, 400+ lines)
|
|
4. `SCHEMA_AUTHORITY_CHECKLIST.md` (new, this file)
|
|
|
|
**Total Documentation**: ~600 lines
|
|
|
|
**Verification**: All checklist items complete ✅
|
|
|
|
---
|
|
|
|
## Next Agent Handoff
|
|
|
|
Future agents working on this project should:
|
|
|
|
1. **Read Rule 0** in `AGENTS.md` before making any schema changes
|
|
2. **Refer to `schemas/20251121/linkml/`** for authoritative schema definitions
|
|
3. **Follow the workflow** (edit LinkML → regenerate RDF → update TypeDB → update UML → validate)
|
|
4. **Never edit** RDF, TypeDB, or UML files directly
|
|
5. **Always validate** changes with `linkml-validate`
|
|
|
|
**The schema authority is now clearly documented and ready for production use.**
|
|
|
|
---
|
|
|
|
**Prepared by**: OpenCode AI Agent
|
|
**Session**: 2025-11-21 Schema Authority Documentation
|
|
**Status**: ✅ ALL TASKS COMPLETE
|