markitect-main/roadmap/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:**
```markdown
# Schema Title v1.0

## Documentation sections...

## Schema Definition

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

### 3. Schema Metadata Standard (Immediate)

**Required fields:**
```json
{
  "$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)
- [x] 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](./SCHEMA_MANAGEMENT_PROPOSAL.md)
- Example markdown schema: [examples/schemas/manpage-schema-v1.md](../../examples/schemas/manpage-schema-v1.md)
- Current schema catalog: [markitect/schemas/schema-catalog.yaml](../../markitect/schemas/schema-catalog.yaml)