tegwick
77415bfad7
Some checks failed
Test Suite / unit-tests (3.11) (push) Has been cancelled
Test Suite / unit-tests (3.12) (push) Has been cancelled
Test Suite / integration-tests (push) Has been cancelled
Test Suite / e2e-tests (push) Has been cancelled
Test Suite / performance-tests (push) Has been cancelled
Test Suite / code-quality (push) Has been cancelled
Test Suite / security-scan (push) Has been cancelled
Test Suite / test-summary (push) Has been cancelled
155 lines
4.2 KiB
Markdown
155 lines
4.2 KiB
Markdown
# 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)
|