kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/SCHEMA_AUTHORITY_CHECKLIST.md
kempersc edb1e07941 updated schemata
2025-11-21 22:12:33 +01:00

7.8 KiB
Raw Blame History

Schema Authority Documentation Checklist

Date: 2025-11-21
Task: Establish LinkML schemas as single source of truth
Status: ✅ COMPLETE

Objectives

  • Add "Schema Source of Truth" documentation to agent instructions
  • Update schema references to new schemas/20251121/linkml/ location
  • Document schema hierarchy (authoritative vs. derived)
  • Provide workflow for schema changes
  • Warn against editing auto-generated files

Files Updated

1. AGENTS.md ✅

Location: Root directory
Status: ✅ COMPLETE

  • Added Rule 0: LinkML Schemas Are the Single Source of Truth (line 24)
  • Documented master schema location: schemas/20251121/linkml/
  • Listed primary schema files (01_name_entity.yaml, 02_organization_observation_reconstruction.yaml)
  • Clarified derived files (RDF, TypeDB, UML, examples)
  • Documented regeneration workflow (edit LinkML → gen-owl → rdfpipe → validate)
  • Listed "Why LinkML is the Master" (5 reasons)
  • Documented NEVER/ALWAYS rules for agents
  • Added references to supporting docs (RDF_GENERATION_SUMMARY.md, etc.)

2. .opencode/agent/README.md ✅

Location: .opencode/agent/ directory
Status: ✅ COMPLETE

  • Added "🚨 Schema Source of Truth" section (lines 5-63)
  • Updated schema version from v0.2.0 to v0.2.1
  • Updated all schema references to schemas/20251121/linkml/
  • Updated agent schema mappings to new class names:
    • HeritageCustodian → CustodianAspect
    • Location → PlaceAspect
    • ChangeEvent → TemporalEvent
    • Identifier → (unchanged)
  • Updated validation commands with correct paths
  • Added schema features list (ISO 20275, multi-aspect modeling, etc.)
  • Updated footer metadata (version, date, schema location)

3. SESSION_SUMMARY_20251121_SCHEMA_AUTHORITY_COMPLETE.md ✅

Location: Root directory
Status: ✅ COMPLETE

  • Documented session overview
  • Listed all changes made
  • Explained documentation hierarchy
  • Provided impact analysis
  • Created validation checklist
  • Listed next steps for future agents
  • Included technical context and statistics

4. SCHEMA_AUTHORITY_CHECKLIST.md ✅

Location: Root directory
Status: ✅ COMPLETE (this file)

  • Created comprehensive task checklist
  • Documented completion status
  • Listed verification steps

Content Verification

Rule 0 in AGENTS.md

  • Positioned before existing Rule 1 (ontology consultation)
  • Clear heading: "Rule 0: LinkML Schemas Are the Single Source of Truth"
  • Master schema location documented
  • Primary schema files listed with descriptions
  • Derived/generated files clearly marked
  • Workflow for schema changes (5 steps)
  • "Why LinkML is the Master" section (5 bullet points)
  • NEVER rules (3 items)
  • ALWAYS rules (4 items)
  • References to supporting documentation

Schema Source of Truth Section in .opencode/agent/README.md

  • Prominent warning emoji (🚨)
  • Master schema location (same as AGENTS.md)
  • Primary schema files (same as AGENTS.md)
  • Derived/generated files (same as AGENTS.md)
  • Workflow for schema changes (same as AGENTS.md)
  • "Why LinkML is the Master" (same as AGENTS.md)
  • NEVER rules (same as AGENTS.md)
  • ALWAYS rules (same as AGENTS.md)
  • References to supporting documentation (same as AGENTS.md)

Schema Reference Updates

  • All old schemas/ paths updated to schemas/20251121/linkml/
  • Schema version updated from v0.2.0 to v0.2.1
  • ISO 20275 migration mentioned
  • Class name mappings updated to reflect new schema
  • Validation commands use correct paths
  • Footer metadata reflects current state

Consistency Check

Between AGENTS.md and .opencode/agent/README.md

  • Master schema location identical
  • Primary schema files identical
  • Derived/generated files identical
  • Workflow steps identical
  • "Why LinkML is the Master" identical
  • NEVER rules identical
  • ALWAYS rules identical
  • Reference links identical

Schema Authority Principles

  • LinkML is authoritative (not RDF, TypeDB, or UML)
  • Edit LinkML first, then regenerate derived formats
  • Never edit auto-generated files directly
  • Always validate changes with linkml-validate
  • Document schema changes in YAML comments
  • Use version control for schema tracking

Integration with Existing Documentation

References Added

  • schemas/20251121/RDF_GENERATION_SUMMARY.md - RDF generation process
  • docs/MIGRATION_GUIDE.md - Schema migration procedures
  • LinkML documentation: https://linkml.io/

Related Documentation (Cross-Check)

  • SESSION_SUMMARY_20251121_ISO20275_COMPLETE.md - Migration completion
  • MIGRATION_CHECKLIST_ISO20275.md - Migration tasks
  • schemas/20251121/uml/MERMAID_UPDATE_SUMMARY.md - Diagram fixes
  • All references to schema authority are consistent

Testing and Validation

Manual Review

  • Read full text of AGENTS.md Rule 0
  • Read full text of .opencode/agent/README.md schema section
  • Verify all schema paths use schemas/20251121/linkml/
  • Verify no references to old schemas/ directory
  • Verify version numbers are v0.2.1
  • Verify class name mappings are correct

Agent Comprehension Test

  • Rule 0 is positioned prominently (before other rules)
  • Schema hierarchy is clearly explained
  • Workflow steps are numbered and sequential
  • Warnings are explicit (❌ DO NOT, ✅ ALWAYS)
  • Examples are provided where helpful
  • References link to supporting docs

Future-Proofing

  • Documentation explains WHY LinkML is master (not just HOW)
  • Workflow is detailed enough for agents to follow
  • Common mistakes are explicitly warned against
  • Migration procedures are documented for future schema changes

Completion Criteria

Primary Objectives

  • Schema authority clearly established
  • LinkML designated as single source of truth
  • Derived file types clearly identified
  • Workflow documented for schema changes
  • Both agent instruction files updated

Secondary Objectives

  • Consistency between AGENTS.md and .opencode/agent/README.md
  • All schema paths updated to new location
  • Schema version updated to v0.2.1
  • Class name mappings updated
  • Session documentation complete

Quality Criteria

  • Clear and unambiguous language
  • Prominent placement (Rule 0, top of agent README)
  • Visual warnings (❌/✅ icons)
  • Numbered workflows for easy following
  • References to supporting documentation
  • 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