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:
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
|
||||
Reference in New Issue
Block a user