tegwick
3003b9b8da
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
Moved schema-of-schemas planning artifacts from roadmap to history with datestamp prefix, marking completion of all 6 implementation phases. **Changes:** - Moved roadmap/schema-of-schemas/ → history/2026-01-05-schema-of-schemas/ - Updated all documentation references to new location - Marked implementation as completed in TODO.md - Updated CHANGELOG.md to reflect archived status **Implementation Summary:** All 6 phases completed successfully: - Phase 1: Filename validation (50 tests) - Phase 2: Markdown schema loader (35 tests) - Phase 3: Schema-for-schemas metaschema (12 tests) - Phase 4: Schema migration (2 migrated, 3 deleted) - Phase 5: CLI enhancements (multi-schema validation) - Phase 6: Integration testing and documentation **Deliverables:** - 97 unit tests (100% passing) - 4 production schemas in registry - Comprehensive user documentation - Updated examples (manpages, terminology) - Complete schema management system The schema-of-schemas topic is now complete and archived for historical reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
521 lines
14 KiB
Markdown
521 lines
14 KiB
Markdown
---
|
|
schema-id: "https://markitect.dev/schemas/schema/v1.0"
|
|
version: "1.0.0"
|
|
status: "stable"
|
|
domain: "schema"
|
|
description: "Metaschema for validating MarkiTect schema files"
|
|
---
|
|
|
|
# Schema-for-Schemas v1.0
|
|
|
|
## Overview
|
|
|
|
This metaschema validates that MarkiTect schema files follow conventions and standards. It ensures schemas are well-formed, properly versioned, and include required MarkiTect extensions.
|
|
|
|
**Purpose**: Quality assurance for schema authors
|
|
|
|
**Validates**:
|
|
- Core JSON Schema fields (title, description, $schema, $id)
|
|
- Version format (SemVer: major.minor.patch)
|
|
- $id URL format (HTTPS with version)
|
|
- MarkiTect extensions (x-markitect-*)
|
|
- Section classification structures
|
|
- Content control patterns
|
|
|
|
## Schema Conventions
|
|
|
|
### Required Fields
|
|
|
|
Every MarkiTect schema MUST include:
|
|
|
|
1. **$schema**: JSON Schema version (draft-07)
|
|
2. **$id**: Canonical HTTPS URL with version
|
|
3. **title**: Human-readable schema name
|
|
4. **description**: Brief explanation of what the schema validates
|
|
5. **version**: SemVer version string (major.minor.patch)
|
|
|
|
### Recommended Fields
|
|
|
|
Schemas SHOULD include:
|
|
|
|
- **type**: Root schema type (usually "object")
|
|
- **properties**: Object properties definition
|
|
- **required**: Array of required property names
|
|
|
|
### MarkiTect Extensions
|
|
|
|
#### x-markitect-sections
|
|
|
|
Defines document sections with classifications and content rules.
|
|
|
|
**Structure**:
|
|
```json
|
|
{
|
|
"SECTION_NAME": {
|
|
"classification": "required|recommended|optional|discouraged|improper",
|
|
"heading_level": 2,
|
|
"content_instruction": "What this section should contain",
|
|
"min_paragraphs": 1,
|
|
"max_paragraphs": 10,
|
|
"min_code_blocks": 0,
|
|
"max_code_blocks": 5,
|
|
"alternatives": ["ALTERNATIVE_NAME"],
|
|
"error_message": "Error if validation fails",
|
|
"warning_if_missing": "Warning if section absent"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Classifications**:
|
|
- `required`: Section must be present
|
|
- `recommended`: Section should be present (warning if missing)
|
|
- `optional`: Section may be present
|
|
- `discouraged`: Section should be avoided (warning if present)
|
|
- `improper`: Section must not be present (error if present)
|
|
|
|
#### x-markitect-content-control
|
|
|
|
Defines content patterns and quality metrics.
|
|
|
|
**Structure**:
|
|
```json
|
|
{
|
|
"section_name": {
|
|
"required_patterns": ["regex1", "regex2"],
|
|
"discouraged_patterns": ["regex3"],
|
|
"forbidden_patterns": ["regex4"],
|
|
"content_quality": {
|
|
"min_words": 50,
|
|
"max_words": 1000,
|
|
"readability_target": "technical|general",
|
|
"min_sentences": 3
|
|
},
|
|
"content_instructions": ["instruction1", "instruction2"],
|
|
"link_validation": {
|
|
"check_internal": true,
|
|
"check_external": false,
|
|
"allow_fragments": true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### x-markitect-metadata
|
|
|
|
Additional schema metadata.
|
|
|
|
**Structure**:
|
|
```json
|
|
{
|
|
"status": "stable|draft|deprecated",
|
|
"authors": ["Author Name <email@example.com>"],
|
|
"created": "2026-01-04",
|
|
"updated": "2026-01-04",
|
|
"tags": ["tag1", "tag2"]
|
|
}
|
|
```
|
|
|
|
#### x-markitect-source
|
|
|
|
Automatically added by schema loader (not in schema file).
|
|
|
|
**Structure**:
|
|
```json
|
|
{
|
|
"file": "/path/to/schema-v1.0.md",
|
|
"filename": "schema-v1.0.md",
|
|
"format": "markdown",
|
|
"frontmatter": {...}
|
|
}
|
|
```
|
|
|
|
## Validation Rules
|
|
|
|
### $id Format
|
|
|
|
Must be HTTPS URL with version:
|
|
```
|
|
https://markitect.dev/schemas/{domain}/v{major}
|
|
```
|
|
|
|
**Examples**:
|
|
- ✅ `https://markitect.dev/schemas/manpage/v1.0`
|
|
- ✅ `https://markitect.dev/schemas/api-documentation/v2.0`
|
|
- ❌ `http://example.com/schema` (not HTTPS)
|
|
- ❌ `https://markitect.dev/schemas/manpage` (no version)
|
|
|
|
### Version Format
|
|
|
|
Must be SemVer (major.minor.patch):
|
|
```
|
|
{major}.{minor}.{patch}
|
|
```
|
|
|
|
**Examples**:
|
|
- ✅ `1.0.0`
|
|
- ✅ `2.5.3`
|
|
- ❌ `1.0` (missing patch)
|
|
- ❌ `v1.0.0` (has 'v' prefix)
|
|
|
|
### Title Format
|
|
|
|
Should be descriptive and end with "Schema":
|
|
|
|
**Examples**:
|
|
- ✅ "Unix Manual Page Schema"
|
|
- ✅ "API Documentation Schema"
|
|
- ❌ "Schema" (too generic)
|
|
|
|
## Usage
|
|
|
|
### Validating a Schema
|
|
|
|
```bash
|
|
# Validate a schema file
|
|
markitect schema-validate manpage-schema-v1.0.md
|
|
|
|
# Show detailed errors
|
|
markitect schema-validate manpage-schema-v1.0.md --detailed-errors
|
|
```
|
|
|
|
### Programmatic Usage
|
|
|
|
```python
|
|
from pathlib import Path
|
|
from markitect.schema_loader import MarkdownSchemaLoader
|
|
|
|
# Load schema to validate
|
|
loader = MarkdownSchemaLoader()
|
|
schema_data = loader.load_schema(Path("my-schema-v1.0.md"))
|
|
|
|
# Check structure
|
|
issues = loader.validate_schema_structure(schema_data['schema'])
|
|
if issues:
|
|
for issue in issues:
|
|
print(f"⚠️ {issue}")
|
|
```
|
|
|
|
## Common Validation Errors
|
|
|
|
### Missing Required Fields
|
|
|
|
**Error**: `Missing required field: $schema`
|
|
|
|
**Solution**: Add `$schema` field:
|
|
```json
|
|
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
...
|
|
}
|
|
```
|
|
|
|
### Invalid $id Format
|
|
|
|
**Error**: `$id should be a full HTTPS URL`
|
|
|
|
**Solution**: Use proper format:
|
|
```json
|
|
{
|
|
"$id": "https://markitect.dev/schemas/my-domain/v1.0",
|
|
...
|
|
}
|
|
```
|
|
|
|
### Invalid Version Format
|
|
|
|
**Error**: `version must be in SemVer format (major.minor.patch)`
|
|
|
|
**Solution**: Use three-part version:
|
|
```json
|
|
{
|
|
"version": "1.0.0",
|
|
...
|
|
}
|
|
```
|
|
|
|
### Invalid Section Classification
|
|
|
|
**Error**: `Invalid classification value: 'mandatory'`
|
|
|
|
**Solution**: Use valid classification:
|
|
```json
|
|
{
|
|
"x-markitect-sections": {
|
|
"SYNOPSIS": {
|
|
"classification": "required",
|
|
...
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Valid values: `required`, `recommended`, `optional`, `discouraged`, `improper`
|
|
|
|
## Schema Definition
|
|
|
|
```json
|
|
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"$id": "https://markitect.dev/schemas/schema/v1.0",
|
|
"title": "MarkiTect Schema-for-Schemas",
|
|
"description": "Metaschema for validating MarkiTect schema files",
|
|
"version": "1.0.0",
|
|
"type": "object",
|
|
"required": ["$schema", "$id", "title", "description", "version"],
|
|
"properties": {
|
|
"$schema": {
|
|
"type": "string",
|
|
"const": "http://json-schema.org/draft-07/schema#",
|
|
"description": "JSON Schema version (must be draft-07)"
|
|
},
|
|
"$id": {
|
|
"type": "string",
|
|
"pattern": "^https://[a-z0-9.-]+/schemas/[a-z0-9-]+/v[0-9]+\\.[0-9]+$",
|
|
"description": "Canonical schema URI with HTTPS and version"
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"minLength": 5,
|
|
"maxLength": 200,
|
|
"description": "Human-readable schema name"
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"minLength": 10,
|
|
"maxLength": 500,
|
|
"description": "Brief explanation of what this schema validates"
|
|
},
|
|
"version": {
|
|
"type": "string",
|
|
"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
|
|
"description": "Semantic version (major.minor.patch)"
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"enum": ["object", "array", "string", "number", "boolean", "null"],
|
|
"description": "Root schema type"
|
|
},
|
|
"properties": {
|
|
"type": "object",
|
|
"description": "Object property definitions"
|
|
},
|
|
"required": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Required property names"
|
|
},
|
|
"x-markitect-sections": {
|
|
"type": "object",
|
|
"description": "Section definitions with classifications",
|
|
"patternProperties": {
|
|
"^[A-Z][A-Z0-9_ ]*$": {
|
|
"type": "object",
|
|
"required": ["classification", "heading_level"],
|
|
"properties": {
|
|
"classification": {
|
|
"type": "string",
|
|
"enum": ["required", "recommended", "optional", "discouraged", "improper"],
|
|
"description": "Section requirement level"
|
|
},
|
|
"heading_level": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 6,
|
|
"description": "Markdown heading level (1-6)"
|
|
},
|
|
"position": {
|
|
"type": "string",
|
|
"enum": ["after_title", "before_title", "anywhere"],
|
|
"description": "Section position constraint"
|
|
},
|
|
"content_instruction": {
|
|
"type": "string",
|
|
"description": "What this section should contain"
|
|
},
|
|
"min_paragraphs": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Minimum paragraph count"
|
|
},
|
|
"max_paragraphs": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"description": "Maximum paragraph count"
|
|
},
|
|
"min_code_blocks": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Minimum code block count"
|
|
},
|
|
"max_code_blocks": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Maximum code block count"
|
|
},
|
|
"alternatives": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Alternative section names"
|
|
},
|
|
"error_message": {
|
|
"type": "string",
|
|
"description": "Error message if validation fails"
|
|
},
|
|
"warning_if_missing": {
|
|
"type": "string",
|
|
"description": "Warning message if section absent"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-markitect-content-control": {
|
|
"type": "object",
|
|
"description": "Content pattern and quality rules",
|
|
"patternProperties": {
|
|
"^[a-z_]+$": {
|
|
"type": "object",
|
|
"properties": {
|
|
"required_patterns": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Required regex patterns"
|
|
},
|
|
"discouraged_patterns": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Patterns to warn about"
|
|
},
|
|
"forbidden_patterns": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Patterns that cause errors"
|
|
},
|
|
"content_quality": {
|
|
"type": "object",
|
|
"properties": {
|
|
"min_words": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Minimum word count"
|
|
},
|
|
"max_words": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"description": "Maximum word count"
|
|
},
|
|
"readability_target": {
|
|
"type": "string",
|
|
"enum": ["technical", "general"],
|
|
"description": "Target readability level"
|
|
},
|
|
"min_sentences": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"description": "Minimum sentence count"
|
|
}
|
|
}
|
|
},
|
|
"content_instructions": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Content writing guidelines"
|
|
},
|
|
"link_validation": {
|
|
"type": "object",
|
|
"properties": {
|
|
"check_internal": {
|
|
"type": "boolean",
|
|
"description": "Validate internal links"
|
|
},
|
|
"check_external": {
|
|
"type": "boolean",
|
|
"description": "Validate external links"
|
|
},
|
|
"allow_fragments": {
|
|
"type": "boolean",
|
|
"description": "Allow fragment identifiers"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"x-markitect-metadata": {
|
|
"type": "object",
|
|
"description": "Additional schema metadata",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": ["stable", "draft", "deprecated"],
|
|
"description": "Schema lifecycle status"
|
|
},
|
|
"authors": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Schema authors"
|
|
},
|
|
"created": {
|
|
"type": "string",
|
|
"format": "date",
|
|
"description": "Creation date (ISO 8601)"
|
|
},
|
|
"updated": {
|
|
"type": "string",
|
|
"format": "date",
|
|
"description": "Last update date (ISO 8601)"
|
|
},
|
|
"tags": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Schema tags for categorization"
|
|
}
|
|
}
|
|
},
|
|
"x-markitect-source": {
|
|
"type": "object",
|
|
"description": "Source file metadata (added by loader)",
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"description": "Full file path"
|
|
},
|
|
"filename": {
|
|
"type": "string",
|
|
"description": "File name only"
|
|
},
|
|
"format": {
|
|
"type": "string",
|
|
"enum": ["markdown", "json"],
|
|
"description": "Source file format"
|
|
},
|
|
"frontmatter": {
|
|
"type": "object",
|
|
"description": "YAML frontmatter from markdown"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"additionalProperties": true
|
|
}
|
|
```
|
|
|
|
## Version History
|
|
|
|
### v1.0.0 (2026-01-04)
|
|
- Initial metaschema version
|
|
- Validates core JSON Schema fields
|
|
- Validates MarkiTect extensions
|
|
- Supports section classifications
|
|
- Supports content control patterns
|
|
- SemVer version validation
|
|
- HTTPS $id URL validation
|
|
|
|
## Related Documentation
|
|
|
|
- [Schema Naming Specification](../../history/2026-01-05-schema-of-schemas/SCHEMA_NAMING_SPEC.md)
|
|
- [Schema Loader Guide](../../history/2026-01-05-schema-of-schemas/SCHEMA_LOADER_GUIDE.md)
|
|
- [Schema Management Workplan](../../history/2026-01-05-schema-of-schemas/WORKPLAN.md) (archived)
|
|
- [Schema Management Guide](../../docs/SCHEMA_MANAGEMENT_GUIDE.md) (user documentation)
|