tegwick
d68e762612
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
Complete Phase 1 of Schema Evolution Workplan implementing flexible content control and section classification system. ## New Features ### 1. x-markitect-sections Extension - Five classification levels: required, recommended, optional, discouraged, improper - Per-section content constraints (paragraphs, code blocks, lists) - Position hints for section ordering - Custom error/warning messages - Alternative section names support - Content instructions for authors ### 2. x-markitect-content-control Extension - Required/discouraged/forbidden pattern matching - Content quality metrics (word count, readability target, sentence count) - Content instruction arrays - Link validation configuration ### 3. Metaschema Validation - Updated markitect-metaschema.json with complete validation rules - Enhanced metaschema.py with validation methods for both extensions - Comprehensive validation of all extension properties - Clear error messages for invalid schemas ### 4. Documentation & Examples - Complete specification in docs/specifications/schema-extensions-spec.md - Enhanced manpage schema demonstrating all 5 classification levels - API documentation schema showing alternative patterns - Detailed usage examples and validation behavior ## Implementation Details **Files Modified:** - markitect/schemas/markitect-metaschema.json: Added extension definitions - markitect/metaschema.py: Added _validate_sections() and _validate_content_control() **Files Created:** - docs/specifications/schema-extensions-spec.md: Complete specification (v1.0) - examples/manpages/enhanced-manpage-schema.json: Demonstrates all classifications - examples/manpages/api-documentation-schema.json: Shows API doc patterns ## Validation Behavior **Classification Levels:** - required: Missing = ERROR (validation fails) - recommended: Missing = WARNING (validation succeeds with warnings) - optional: No validation impact - discouraged: Present = WARNING (validation succeeds with warnings) - improper: Present = ERROR (validation fails) ## Next Steps Phase 2: Schema Refinement Tools (schema-analyze, schema-refine, schema-compose) Phase 3: Enhanced Validation Engine (classification-aware validation, quality metrics) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
209 lines
8.3 KiB
JSON
209 lines
8.3 KiB
JSON
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"$id": "https://markitect.io/schemas/markitect-metaschema.json",
|
|
"type": "object",
|
|
"title": "MarkiTect Extended JSON Schema Metaschema",
|
|
"description": "Metaschema for MarkiTect JSON schemas that extends standard JSON Schema with MarkiTect-specific features for document structure analysis and generation",
|
|
"allOf": [
|
|
{
|
|
"$ref": "http://json-schema.org/draft-07/schema#"
|
|
},
|
|
{
|
|
"properties": {
|
|
"x-markitect-heading-text": {
|
|
"type": "string",
|
|
"description": "Preserve actual heading text from source document for validation and template generation"
|
|
},
|
|
"x-markitect-content-instructions": {
|
|
"type": "string",
|
|
"description": "Instructions for content authors about what should go in this section"
|
|
},
|
|
"x-markitect-outline-mode": {
|
|
"type": "boolean",
|
|
"description": "Indicates if this schema was generated in outline mode, focusing on structural hierarchy"
|
|
},
|
|
"x-markitect-outline-depth": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"description": "Maximum heading depth captured in outline mode"
|
|
},
|
|
"x-markitect-instruction-type": {
|
|
"type": "string",
|
|
"enum": ["description", "example", "constraint", "template"],
|
|
"description": "Type of content instruction provided"
|
|
},
|
|
"x-markitect-generated-from": {
|
|
"type": "string",
|
|
"description": "Source file or document this schema was generated from"
|
|
},
|
|
"x-markitect-generation-mode": {
|
|
"type": "string",
|
|
"enum": ["outline", "full"],
|
|
"description": "Mode used to generate this schema"
|
|
},
|
|
"x-markitect-sections": {
|
|
"type": "object",
|
|
"description": "Section classification and content control for document sections",
|
|
"patternProperties": {
|
|
"^[A-Z][A-Z0-9_ ]*$": {
|
|
"type": "object",
|
|
"description": "Section definition with classification and constraints",
|
|
"properties": {
|
|
"classification": {
|
|
"type": "string",
|
|
"enum": ["required", "recommended", "optional", "discouraged", "improper"],
|
|
"description": "Classification level determining validation behavior"
|
|
},
|
|
"heading_level": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 6,
|
|
"description": "Expected heading level (H1-H6) for this section"
|
|
},
|
|
"position": {
|
|
"type": "string",
|
|
"enum": ["after_title", "before_section_name", "after_section_name", "anywhere"],
|
|
"description": "Where this section should appear in the document"
|
|
},
|
|
"content_instruction": {
|
|
"type": "string",
|
|
"description": "Human-readable instruction for section content"
|
|
},
|
|
"min_paragraphs": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Minimum number of paragraphs in this section"
|
|
},
|
|
"max_paragraphs": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Maximum number of paragraphs in this section"
|
|
},
|
|
"min_code_blocks": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Minimum number of code blocks in this section"
|
|
},
|
|
"max_code_blocks": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Maximum number of code blocks in this section"
|
|
},
|
|
"min_lists": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Minimum number of lists in this section"
|
|
},
|
|
"max_lists": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Maximum number of lists in this section"
|
|
},
|
|
"warning_if_missing": {
|
|
"type": "string",
|
|
"description": "Custom warning message for missing recommended sections"
|
|
},
|
|
"error_message": {
|
|
"type": "string",
|
|
"description": "Custom error message for required/improper section violations"
|
|
},
|
|
"alternatives": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Alternative section names that satisfy the requirement"
|
|
}
|
|
},
|
|
"required": ["classification"]
|
|
}
|
|
}
|
|
},
|
|
"x-markitect-content-control": {
|
|
"type": "object",
|
|
"description": "Content validation rules including patterns and quality metrics",
|
|
"patternProperties": {
|
|
"^[a-z][a-z0-9_]*$": {
|
|
"type": "object",
|
|
"description": "Content control rules for a specific section",
|
|
"properties": {
|
|
"required_patterns": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Regex patterns that must appear in section content"
|
|
},
|
|
"discouraged_patterns": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Regex patterns that should not appear in content (warning)"
|
|
},
|
|
"forbidden_patterns": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Regex patterns that must not appear in content (error)"
|
|
},
|
|
"content_quality": {
|
|
"type": "object",
|
|
"description": "Quality metrics for section content",
|
|
"properties": {
|
|
"min_words": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Minimum word count"
|
|
},
|
|
"max_words": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Maximum word count"
|
|
},
|
|
"readability_target": {
|
|
"type": "string",
|
|
"enum": ["simple", "general", "technical", "advanced"],
|
|
"description": "Target readability level"
|
|
},
|
|
"min_sentences": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Minimum sentence count"
|
|
},
|
|
"max_sentences": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Maximum sentence count"
|
|
}
|
|
}
|
|
},
|
|
"content_instructions": {
|
|
"type": "array",
|
|
"items": {"type": "string"},
|
|
"description": "Array of human-readable content creation instructions"
|
|
},
|
|
"link_validation": {
|
|
"type": "object",
|
|
"description": "Link checking configuration",
|
|
"properties": {
|
|
"check_internal": {
|
|
"type": "boolean",
|
|
"description": "Validate internal document links"
|
|
},
|
|
"check_external": {
|
|
"type": "boolean",
|
|
"description": "Validate external URLs"
|
|
},
|
|
"allow_fragments": {
|
|
"type": "boolean",
|
|
"description": "Allow fragment-only links like #section"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"patternProperties": {
|
|
"^x-markitect-": {
|
|
"description": "MarkiTect extension properties"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
} |