markitect-main/history/260105-schema-of-schemas/SCHEMA_MANAGEMENT_SUMMARY.md

Schema Management: Executive Summary

TL;DR: Implement naming conventions, versioning, and markdown-first schema format to solve current schema management issues.

Problems Identified

1. Inconsistent Naming - Mix of schema.json suffix and no suffix
2. No Versioning - Can't track schema evolution or maintain multiple versions
3. Duplicate Schemas - 3 manpage schemas with similar content
4. Format Mismatch - JSON schemas in markdown-centric tool

Recommended Solution

1. Naming Convention (Immediate)

Format: {domain}-schema-v{major}.{minor}.json or .md

Examples:

manpage-schema-v1.0.json
terminology-schema-v1.0.json
api-documentation-schema-v1.0.json

Migration:

markdown-manpage → manpage-schema-v1.0.json
enhanced-manpage → manpage-schema-v2.0.json (breaking changes)
terminology-schema.json → terminology-schema-v1.0.json

2. Markdown-First Format (Short-term)

Proposal: Store schemas as markdown files with embedded JSON

Benefits:

• Aligns with markdown philosophy ✅
• Rich documentation alongside schema ✅
• Version history in same file ✅
• Examples and usage inline ✅
• Lower barrier to entry ✅

Example: See examples/schemas/manpage-schema-v1.md

Format:

# Schema Title v1.0

## Documentation sections...

## Schema Definition

\`\`\`json
{ schema here }
\`\`\`

3. Schema Metadata Standard (Immediate)

Required fields:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://markitect.dev/schemas/{domain}/v{major}",
  "version": "1.0.0",
  "title": "Human Readable Title",
  "description": "Detailed description",
  "x-markitect-metadata": {
    "domain": "manpage",
    "document-types": ["manual-page"],
    "created": "2026-01-04",
    "example": "examples/manpages/example.md"
  }
}

Implementation Phases

Phase 1: Foundation (1-2 days)

• Analyze current state
• Define naming convention spec
• Create schema metadata template
• Rename existing schemas
• Update schema-catalog.yaml

Phase 2: Markdown Format (3-5 days)

• Design markdown schema format
• Implement parser (extract JSON from markdown)
• Convert 1 schema as proof-of-concept
• Test and iterate
• Migrate all schemas

Phase 3: Tooling (2-3 days)

• Update CLI to support .md schemas
• Add schema validation command
• Create migration guide
• Update documentation

Cost-Benefit Analysis

Cost: 6-10 days total effort

Benefits:

• Professional schema management ⭐⭐⭐⭐⭐
• Better discoverability ⭐⭐⭐⭐
• Easier maintenance ⭐⭐⭐⭐⭐
• Markdown alignment ⭐⭐⭐⭐⭐
• Version tracking ⭐⭐⭐⭐⭐

ROI: High - Foundational improvement that benefits all future schema work

Alternative Considered

Alternative: Keep JSON, generate markdown docs automatically

Pros:

• Simpler implementation (2-3 days)
• JSON remains source of truth
• Standard tooling works

Cons:

• Doesn't solve format mismatch
• Documentation generated, not authored
• Two files to manage

Verdict: Markdown-first better aligns with project philosophy

Quick Wins (Today)

1. Rename schemas with versioned names (30 minutes)
2. Add metadata to existing schemas (1 hour)
3. Update catalog with proper versioning (30 minutes)

Questions to Resolve

1. File extension: .md or .schema.md for markdown schemas?
2. JSON extraction: Real-time or pre-compiled cache?
3. Backward compatibility: Support both formats during transition?
4. CLI changes: --schema file.md or auto-detect format?

Next Steps

1. Review this proposal and example (examples/schemas/manpage-schema-v1.md)
2. Decide on markdown-first vs generated docs approach
3. Prototype parser for markdown schemas
4. Migrate one schema as proof-of-concept
5. Iterate based on feedback
6. Full rollout to all schemas

References

• Full proposal: SCHEMA_MANAGEMENT_PROPOSAL.md
• Example markdown schema: examples/schemas/manpage-schema-v1.md
• Current schema catalog: markitect/schemas/schema-catalog.yaml