tegwick
60d9f7a2c3
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>
6.8 KiB
6.8 KiB
description, domain, schema-id, status, version
| description | domain | schema-id | status | version |
|---|---|---|---|---|
| Schema for validating terminology and glossary documents with consistent structure | terminology | https://markitect.dev/schemas/terminology/v1.0 | stable | 1.0.0 |
Terminology Document Schema v1.0.0
Overview
Schema for validating terminology and glossary documents with consistent structure
Usage
markitect validate document.md --schema v1.0
Schema Definition
{
"$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