feat: implement Phase 1 - Enhanced Schema Format with Classifications
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
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>
This commit is contained in:
230
examples/manpages/api-documentation-schema.json
Normal file
230
examples/manpages/api-documentation-schema.json
Normal file
@@ -0,0 +1,230 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "API Endpoint Documentation Schema",
|
||||
"description": "Schema for API endpoint documentation with classification and content control",
|
||||
"x-markitect-sections": {
|
||||
"ENDPOINT": {
|
||||
"classification": "required",
|
||||
"heading_level": 2,
|
||||
"position": "after_title",
|
||||
"content_instruction": "HTTP method and endpoint path (e.g., GET /api/v1/users)",
|
||||
"min_paragraphs": 1,
|
||||
"max_paragraphs": 3,
|
||||
"error_message": "ENDPOINT section must specify the HTTP method and path"
|
||||
},
|
||||
"DESCRIPTION": {
|
||||
"classification": "required",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "What this endpoint does and when to use it",
|
||||
"min_paragraphs": 2,
|
||||
"error_message": "DESCRIPTION is required to explain endpoint functionality"
|
||||
},
|
||||
"AUTHENTICATION": {
|
||||
"classification": "required",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "Authentication requirements (API key, OAuth, etc.)",
|
||||
"min_paragraphs": 1,
|
||||
"error_message": "AUTHENTICATION requirements must be documented"
|
||||
},
|
||||
"REQUEST PARAMETERS": {
|
||||
"classification": "recommended",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "List all request parameters with types and descriptions",
|
||||
"alternatives": ["PARAMETERS", "REQUEST", "INPUT"],
|
||||
"warning_if_missing": "Documenting request parameters helps API consumers use the endpoint correctly"
|
||||
},
|
||||
"RESPONSE": {
|
||||
"classification": "recommended",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "Response format, status codes, and example responses",
|
||||
"min_code_blocks": 1,
|
||||
"warning_if_missing": "Response documentation with examples improves API usability"
|
||||
},
|
||||
"EXAMPLES": {
|
||||
"classification": "recommended",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "Complete request/response examples",
|
||||
"min_code_blocks": 2,
|
||||
"warning_if_missing": "Examples make API documentation significantly more useful"
|
||||
},
|
||||
"ERROR CODES": {
|
||||
"classification": "recommended",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "Possible error responses and how to handle them",
|
||||
"alternatives": ["ERRORS", "ERROR HANDLING"],
|
||||
"warning_if_missing": "Error documentation helps developers handle failures gracefully"
|
||||
},
|
||||
"RATE LIMITING": {
|
||||
"classification": "optional",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "Rate limit information for this endpoint"
|
||||
},
|
||||
"CHANGELOG": {
|
||||
"classification": "optional",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "Version history and changes to this endpoint"
|
||||
},
|
||||
"SEE ALSO": {
|
||||
"classification": "optional",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "Related endpoints and documentation"
|
||||
},
|
||||
"IMPLEMENTATION NOTES": {
|
||||
"classification": "discouraged",
|
||||
"heading_level": 2,
|
||||
"warning_if_missing": "Implementation details should be in developer documentation, not API docs"
|
||||
},
|
||||
"INTERNAL API": {
|
||||
"classification": "improper",
|
||||
"heading_level": 2,
|
||||
"error_message": "Internal API endpoints must not be in public documentation"
|
||||
},
|
||||
"EXPERIMENTAL": {
|
||||
"classification": "improper",
|
||||
"heading_level": 2,
|
||||
"error_message": "Experimental features must not be in stable API documentation"
|
||||
}
|
||||
},
|
||||
"x-markitect-content-control": {
|
||||
"endpoint": {
|
||||
"required_patterns": [
|
||||
"\\*\\*[A-Z]+\\*\\*",
|
||||
"`/api/",
|
||||
"\\*\\*[A-Z]+\\*\\*\\s+`/[^`]+`"
|
||||
],
|
||||
"content_quality": {
|
||||
"min_words": 5,
|
||||
"max_words": 50,
|
||||
"readability_target": "technical"
|
||||
},
|
||||
"content_instructions": [
|
||||
"Format: **METHOD** `endpoint_path`",
|
||||
"Example: **GET** `/api/v1/users/{id}`",
|
||||
"Use bold for HTTP method",
|
||||
"Use code formatting for path",
|
||||
"Include path parameters in curly braces"
|
||||
]
|
||||
},
|
||||
"description": {
|
||||
"discouraged_patterns": [
|
||||
"TODO",
|
||||
"FIXME",
|
||||
"TBD",
|
||||
"Coming soon"
|
||||
],
|
||||
"forbidden_patterns": [
|
||||
"password",
|
||||
"secret",
|
||||
"api[_-]?key\\s*=",
|
||||
"token\\s*="
|
||||
],
|
||||
"content_quality": {
|
||||
"min_words": 30,
|
||||
"max_words": 500,
|
||||
"readability_target": "technical",
|
||||
"min_sentences": 2
|
||||
},
|
||||
"content_instructions": [
|
||||
"Explain what the endpoint does",
|
||||
"Describe the main use case",
|
||||
"Mention any prerequisites",
|
||||
"Note any side effects",
|
||||
"Keep concise but complete"
|
||||
]
|
||||
},
|
||||
"request_parameters": {
|
||||
"required_patterns": [
|
||||
"\\*\\*[a-z_]+\\*\\*",
|
||||
"\\*[A-Za-z]+\\*"
|
||||
],
|
||||
"content_instructions": [
|
||||
"Use bold for parameter names",
|
||||
"Use italic for parameter types",
|
||||
"Include: name, type, required/optional, description",
|
||||
"Use definition list format",
|
||||
"Specify default values where applicable"
|
||||
]
|
||||
},
|
||||
"response": {
|
||||
"required_patterns": [
|
||||
"```json",
|
||||
"200",
|
||||
"\\{[^}]*\\}"
|
||||
],
|
||||
"content_quality": {
|
||||
"min_words": 50,
|
||||
"max_words": 500,
|
||||
"readability_target": "technical"
|
||||
},
|
||||
"content_instructions": [
|
||||
"Show example JSON response",
|
||||
"Document all status codes",
|
||||
"Explain response fields",
|
||||
"Include success and error examples",
|
||||
"Use proper JSON formatting in code blocks"
|
||||
]
|
||||
},
|
||||
"examples": {
|
||||
"required_patterns": [
|
||||
"```bash",
|
||||
"curl",
|
||||
"```json"
|
||||
],
|
||||
"content_quality": {
|
||||
"min_words": 100,
|
||||
"max_words": 1000,
|
||||
"readability_target": "general"
|
||||
},
|
||||
"content_instructions": [
|
||||
"Provide complete curl examples",
|
||||
"Show request headers",
|
||||
"Include example responses",
|
||||
"Add explanatory comments",
|
||||
"Cover common scenarios"
|
||||
],
|
||||
"link_validation": {
|
||||
"check_internal": true,
|
||||
"check_external": true,
|
||||
"allow_fragments": true
|
||||
}
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"headings": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"level_1": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"maxItems": 1
|
||||
},
|
||||
"level_2": {
|
||||
"type": "array",
|
||||
"minItems": 3,
|
||||
"maxItems": 15
|
||||
},
|
||||
"level_3": {
|
||||
"type": "array",
|
||||
"minItems": 0,
|
||||
"maxItems": 30
|
||||
}
|
||||
}
|
||||
},
|
||||
"paragraphs": {
|
||||
"type": "array",
|
||||
"minItems": 8,
|
||||
"maxItems": 200
|
||||
},
|
||||
"code_blocks": {
|
||||
"type": "array",
|
||||
"minItems": 3,
|
||||
"maxItems": 30
|
||||
},
|
||||
"emphasis": {
|
||||
"type": "array",
|
||||
"minItems": 15,
|
||||
"maxItems": 200
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user