feat: implement Phase 4 - Schema Migration
Completed Phase 4 of the schema-of-schemas implementation with successful migration of all legacy schemas to the new markdown format following the naming convention. Migration Script (scripts/migrate_schemas.py - 240 lines): - Automated schema migration from JSON to markdown format - Updates version and $id fields to follow conventions - Generates proper frontmatter metadata - Dry-run mode for safe testing - Database cleanup functionality - Comprehensive progress reporting Schemas Migrated (2): - terminology-schema.json → terminology-schema-v1.0.md - Fixed missing version field - Updated $id from /terminology-v1.json to /terminology/v1.0 - Validates successfully against metaschema - api-documentation → api-documentation-schema-v1.0.md - Added version: 1.0.0 - Updated $id to follow /api-documentation/v1.0 format - Validates successfully against metaschema Schemas Deleted (3): - markdown-manpage (duplicate of manpage-schema-v1.0.md) - markdown-manpage-schema.json (duplicate of manpage-schema-v1.0.md) - enhanced-manpage (replaced by manpage-schema-v1.0.md) CLI Enhancement (markitect/cli.py): - Updated schema-ingest to support markdown (.md) files - Auto-detects file type and uses MarkdownSchemaLoader for .md files - Extracts JSON schema from markdown for database storage - Maintains backward compatibility with JSON files Final Schema Registry (4 schemas): ✅ terminology-schema-v1.0.md - Terminology validation ✅ api-documentation-schema-v1.0.md - API documentation structure ✅ manpage-schema-v1.0.md - Unix manual pages ✅ schema-schema-v1.0.md - Metaschema for validating schemas All schemas: - Follow naming convention: {domain}-schema-v{major}.{minor}.md - Include proper frontmatter with schema-id, version, status - Validate successfully against schema-schema-v1.0.md metaschema - Stored in database and ready for use Progress Tracking: - Updated TODO.md with Phase 4 completion - Updated CHANGELOG.md with migration details - Next: Phase 5 - CLI & Documentation Updates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1617,33 +1617,52 @@ def validate(config, file_path, schema, schema_json, quiet, detailed_errors, err
|
||||
@pass_config
|
||||
def schema_ingest(config, schema_file, name):
|
||||
"""
|
||||
Read and store a JSON schema file in the database.
|
||||
Read and store a schema file in the database.
|
||||
|
||||
Supports both JSON (.json) and Markdown (.md) schema files.
|
||||
Validates schemas against the MarkiTect metaschema to ensure compatibility
|
||||
with MarkiTect features like heading text capture and content instructions.
|
||||
Implements Issue #3 and Issue #50 functionality.
|
||||
|
||||
SCHEMA_FILE: Path to the JSON schema file to store
|
||||
SCHEMA_FILE: Path to the schema file to store (.json or .md)
|
||||
|
||||
Examples:
|
||||
markitect schema-ingest my_schema.json
|
||||
markitect schema-ingest manpage-schema-v1.0.md
|
||||
markitect schema-ingest external_schema.json --name custom-name
|
||||
markitect schema-ingest markitect_schema.json -v # Show metaschema validation
|
||||
"""
|
||||
try:
|
||||
# Determine schema name
|
||||
schema_name = name if name else schema_file.name
|
||||
|
||||
# Read schema file content
|
||||
with open(schema_file, 'r', encoding='utf-8') as f:
|
||||
schema_content = f.read()
|
||||
# Load schema based on file type
|
||||
if schema_file.suffix == '.md':
|
||||
# Load markdown schema
|
||||
from .schema_loader import MarkdownSchemaLoader
|
||||
loader = MarkdownSchemaLoader()
|
||||
|
||||
# Validate JSON format
|
||||
try:
|
||||
schema_data = json.loads(schema_content)
|
||||
except json.JSONDecodeError as e:
|
||||
click.echo(f"Error: Invalid JSON in schema file - {e}", err=True)
|
||||
sys.exit(1)
|
||||
try:
|
||||
schema_data_full = loader.load_schema(schema_file)
|
||||
schema_data = schema_data_full['schema']
|
||||
|
||||
# Store the JSON content for database
|
||||
schema_content = json.dumps(schema_data, indent=2)
|
||||
|
||||
if config.get('verbose'):
|
||||
click.echo(f"✅ Loaded markdown schema: {schema_file.name}")
|
||||
except Exception as e:
|
||||
click.echo(f"Error: Failed to load markdown schema - {e}", err=True)
|
||||
sys.exit(1)
|
||||
else:
|
||||
# Load JSON schema
|
||||
with open(schema_file, 'r', encoding='utf-8') as f:
|
||||
schema_content = f.read()
|
||||
|
||||
# Validate JSON format
|
||||
try:
|
||||
schema_data = json.loads(schema_content)
|
||||
except json.JSONDecodeError as e:
|
||||
click.echo(f"Error: Invalid JSON in schema file - {e}", err=True)
|
||||
sys.exit(1)
|
||||
|
||||
# Validate against MarkiTect metaschema
|
||||
from .metaschema import MetaschemaValidator
|
||||
|
||||
268
markitect/schemas/api-documentation-schema-v1.0.md
Normal file
268
markitect/schemas/api-documentation-schema-v1.0.md
Normal file
@@ -0,0 +1,268 @@
|
||||
---
|
||||
description: Schema for API documentation structure and content validation
|
||||
domain: api-documentation
|
||||
schema-id: https://markitect.dev/schemas/api-documentation/v1.0
|
||||
status: stable
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# API Endpoint Documentation Schema v1.0.0
|
||||
|
||||
## Overview
|
||||
|
||||
Schema for API endpoint documentation with classification and content control
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
markitect validate document.md --schema v1.0
|
||||
```
|
||||
|
||||
## Schema Definition
|
||||
|
||||
```json
|
||||
{
|
||||
"$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
|
||||
}
|
||||
},
|
||||
"version": "1.0.0",
|
||||
"$id": "https://markitect.dev/schemas/api-documentation/v1.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Version History
|
||||
|
||||
### v1.0.0
|
||||
- Initial version
|
||||
252
markitect/schemas/terminology-schema-v1.0.md
Normal file
252
markitect/schemas/terminology-schema-v1.0.md
Normal file
@@ -0,0 +1,252 @@
|
||||
---
|
||||
description: Schema for validating terminology and glossary documents with consistent
|
||||
structure
|
||||
domain: terminology
|
||||
schema-id: https://markitect.dev/schemas/terminology/v1.0
|
||||
status: stable
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Terminology Document Schema v1.0.0
|
||||
|
||||
## Overview
|
||||
|
||||
Schema for validating terminology and glossary documents with consistent structure
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
markitect validate document.md --schema v1.0
|
||||
```
|
||||
|
||||
## Schema Definition
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://markitect.dev/schemas/terminology/v1.0",
|
||||
"title": "Terminology Document Schema",
|
||||
"description": "Schema for validating terminology and glossary documents with consistent structure",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"headings": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"level_1": {
|
||||
"type": "array",
|
||||
"description": "Main document title",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"content": {
|
||||
"type": "string",
|
||||
"pattern": ".*(Terminology|Glossary|Terms|Definitions).*"
|
||||
}
|
||||
}
|
||||
},
|
||||
"minItems": 1,
|
||||
"maxItems": 1
|
||||
},
|
||||
"level_2": {
|
||||
"type": "array",
|
||||
"description": "Category headings (Core Concepts, Document Types, etc.)",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"content": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
}
|
||||
}
|
||||
},
|
||||
"minItems": 1,
|
||||
"maxItems": 20
|
||||
},
|
||||
"level_3": {
|
||||
"type": "array",
|
||||
"description": "Individual term headings",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"content": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"description": "Term name - should be title case"
|
||||
}
|
||||
}
|
||||
},
|
||||
"minItems": 1
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"level_1",
|
||||
"level_2",
|
||||
"level_3"
|
||||
]
|
||||
},
|
||||
"paragraphs": {
|
||||
"type": "array",
|
||||
"description": "Content paragraphs including definitions and descriptions",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"content": {
|
||||
"type": "string",
|
||||
"minLength": 10
|
||||
}
|
||||
}
|
||||
},
|
||||
"minItems": 3
|
||||
},
|
||||
"bold_text": {
|
||||
"type": "array",
|
||||
"description": "Bold text used for field labels (Definition, Synonyms, etc.)",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"content": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"Definition:",
|
||||
"Synonyms:",
|
||||
"Related Terms:",
|
||||
"Example:",
|
||||
"Examples:",
|
||||
"Use Cases:",
|
||||
"Usage:",
|
||||
"Format:",
|
||||
"Components:",
|
||||
"Steps:",
|
||||
"Tools:",
|
||||
"Levels:",
|
||||
"Status:",
|
||||
"Migration:",
|
||||
"Required:",
|
||||
"Recommended:",
|
||||
"Optional:",
|
||||
"Discouraged:",
|
||||
"Improper:"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"minItems": 1
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"headings",
|
||||
"paragraphs"
|
||||
],
|
||||
"x-markitect-sections": {
|
||||
"document_title": {
|
||||
"classification": "required",
|
||||
"heading_level": 1,
|
||||
"content_instruction": "Main title should include words like 'Terminology', 'Glossary', or 'Definitions'",
|
||||
"pattern": ".*(Terminology|Glossary|Terms|Definitions).*"
|
||||
},
|
||||
"category_sections": {
|
||||
"classification": "required",
|
||||
"heading_level": 2,
|
||||
"min_sections": 1,
|
||||
"content_instruction": "Organize terms into logical categories (e.g., Core Concepts, Document Types, Process Terms)"
|
||||
},
|
||||
"term_definitions": {
|
||||
"classification": "required",
|
||||
"heading_level": 3,
|
||||
"min_sections": 1,
|
||||
"content_instruction": "Each term should be a level 3 heading followed by its definition and optional metadata"
|
||||
}
|
||||
},
|
||||
"x-markitect-content-control": {
|
||||
"term_structure": {
|
||||
"required_components": [
|
||||
{
|
||||
"label": "Definition:",
|
||||
"type": "bold_text",
|
||||
"description": "Clear, concise definition of the term"
|
||||
}
|
||||
],
|
||||
"optional_components": [
|
||||
{
|
||||
"label": "Synonyms:",
|
||||
"type": "bold_text",
|
||||
"description": "Alternative names or abbreviations"
|
||||
},
|
||||
{
|
||||
"label": "Related Terms:",
|
||||
"type": "bold_text",
|
||||
"description": "Links to related concepts"
|
||||
},
|
||||
{
|
||||
"label": "Example:",
|
||||
"type": "bold_text_or_code",
|
||||
"description": "Practical example demonstrating the term"
|
||||
},
|
||||
{
|
||||
"label": "Use Cases:",
|
||||
"type": "list",
|
||||
"description": "Common scenarios where term applies"
|
||||
}
|
||||
],
|
||||
"content_quality": {
|
||||
"min_words_per_definition": 10,
|
||||
"max_words_per_definition": 200,
|
||||
"readability_target": "technical"
|
||||
},
|
||||
"content_instructions": [
|
||||
"Start each term with a level 3 heading containing the term name",
|
||||
"Follow immediately with 'Definition:' in bold",
|
||||
"Provide a clear, self-contained definition",
|
||||
"Add optional fields (Synonyms, Related Terms, Examples) as needed",
|
||||
"Use consistent formatting across all terms",
|
||||
"Group related terms under category headings (level 2)"
|
||||
]
|
||||
},
|
||||
"definition_pattern": {
|
||||
"description": "Each definition should follow: Term heading (###) → Definition: (bold) → Definition text",
|
||||
"validation": {
|
||||
"heading_level_3_followed_by": "bold_text_starting_with_Definition",
|
||||
"definition_length": {
|
||||
"min_words": 10,
|
||||
"max_words": 200
|
||||
}
|
||||
}
|
||||
},
|
||||
"deprecated_terms": {
|
||||
"classification": "optional",
|
||||
"heading_level": 2,
|
||||
"content_instruction": "Optional section for deprecated terms with migration guidance",
|
||||
"required_fields": [
|
||||
"Status: DEPRECATED",
|
||||
"Migration:"
|
||||
]
|
||||
}
|
||||
},
|
||||
"x-markitect-validation-rules": {
|
||||
"term_count": {
|
||||
"min": 3,
|
||||
"recommended_min": 10,
|
||||
"description": "Terminology document should define at least 3 terms, 10+ recommended"
|
||||
},
|
||||
"category_balance": {
|
||||
"description": "Each category should have at least 2 terms",
|
||||
"min_terms_per_category": 2
|
||||
},
|
||||
"definition_quality": {
|
||||
"all_terms_must_have_definition": true,
|
||||
"definition_must_follow_term_heading": true,
|
||||
"definition_min_words": 10
|
||||
},
|
||||
"consistency": {
|
||||
"use_consistent_field_labels": true,
|
||||
"maintain_heading_hierarchy": true
|
||||
}
|
||||
},
|
||||
"version": "1.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Version History
|
||||
|
||||
### v1.0.0
|
||||
- Initial version
|
||||
Reference in New Issue
Block a user