feat: add terminology schema example and improve schema-list command
This commit completes Phase 2 of schema evolution work and establishes a new example demonstrating schema usage for terminology documents. ## New Features ### Terminology Validation Example (examples/terminology/) - Complete example terminology document with proper structure - JSON schema with MarkiTect extensions for validation - Demonstrates schema usage beyond manpages (glossaries, lexicons) - Validates term structure: Definition, Synonyms, Related Terms, Examples - Includes content control and quality validation rules - Full documentation with usage examples and best practices ### Schema Registration System - Registered terminology schema in markitect database - Created schema catalog (markitect/schemas/schema-catalog.yaml) - Copied schema to official location (markitect/schemas/) - Provides metadata, features, and usage info for all schemas ### Improved schema-list Command - Now displays creation timestamps in default output - Table format includes Created/Updated columns - Cleaner timestamp formatting (removed microseconds) - Better visibility into when schemas were added ## Files Changed Added: - examples/terminology/README.md - Complete documentation - examples/terminology/terminology-example.md - Example glossary - examples/terminology/terminology-schema.json - Validation schema - markitect/schemas/terminology-schema.json - Registered schema - markitect/schemas/schema-catalog.yaml - Schema registry Modified: - markitect/cli.py - Enhanced schema-list with timestamps - TODO.md - Documented Phase 2 completion and new example Moved: - SCHEMA_EVOLUTION_WORKPLAN.md → todo/ directory ## Schema Features Demonstrated - Heading hierarchy validation (H1 → H2 → H3) - Term structure validation with required/optional fields - Content quality metrics (word counts, readability targets) - MarkiTect extensions (x-markitect-sections, x-markitect-content-control) - Classification system (required/recommended/optional/discouraged/improper) ## Usage ```bash # List schemas with timestamps markitect schema-list # Validate terminology document markitect validate glossary.md --schema terminology-schema.json # View in table format markitect schema-list --format table ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
287
examples/terminology/README.md
Normal file
287
examples/terminology/README.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# Terminology Document Example
|
||||
|
||||
This example demonstrates how to use MarkiTect schemas to validate terminology and glossary documents.
|
||||
|
||||
## Overview
|
||||
|
||||
Terminology documents (glossaries, dictionaries, lexicons) benefit from consistent structure and validation. This example shows how to:
|
||||
|
||||
1. Structure terminology documents with clear categories and term definitions
|
||||
2. Validate terminology documents using JSON schemas
|
||||
3. Use MarkiTect's schema extensions for content control
|
||||
|
||||
## Files
|
||||
|
||||
- **terminology-example.md** - Example terminology document with proper structure
|
||||
- **terminology-schema.json** - JSON schema for validating terminology documents
|
||||
- **README.md** - This file
|
||||
|
||||
## Terminology Document Structure
|
||||
|
||||
A well-structured terminology document includes:
|
||||
|
||||
### Required Elements
|
||||
|
||||
1. **Main Title (Level 1 Heading)**
|
||||
- Should include keywords: "Terminology", "Glossary", "Terms", or "Definitions"
|
||||
|
||||
2. **Category Sections (Level 2 Headings)**
|
||||
- Organize terms into logical groups
|
||||
- Examples: "Core Concepts", "Document Types", "Process Terms"
|
||||
|
||||
3. **Term Definitions (Level 3 Headings)**
|
||||
- Each term as a level 3 heading
|
||||
- Followed by structured content
|
||||
|
||||
### Term Structure
|
||||
|
||||
Each term should include:
|
||||
|
||||
**Required:**
|
||||
- **Definition:** Clear, concise explanation of the term
|
||||
|
||||
**Optional (but recommended):**
|
||||
- **Synonyms:** Alternative names or abbreviations
|
||||
- **Related Terms:** Links to related concepts
|
||||
- **Example:** Practical usage example
|
||||
- **Use Cases:** Common scenarios
|
||||
- **Format:** For document type terms
|
||||
- **Components:** For complex concepts
|
||||
- **Steps:** For process terms
|
||||
|
||||
## Usage
|
||||
|
||||
### Using the Registered Schema
|
||||
|
||||
The terminology schema is registered in markitect's database and can be used by name:
|
||||
|
||||
```bash
|
||||
# List all registered schemas (terminology-schema.json should appear)
|
||||
markitect schema-list
|
||||
|
||||
# Validate using the registered schema
|
||||
markitect validate my-glossary.md --schema terminology-schema.json
|
||||
|
||||
# Or use the local file directly
|
||||
markitect validate my-glossary.md --schema examples/terminology/terminology-schema.json
|
||||
```
|
||||
|
||||
### Validate with Detailed Errors
|
||||
|
||||
```bash
|
||||
markitect validate my-glossary.md --schema terminology-schema.json --detailed-errors
|
||||
```
|
||||
|
||||
### Register the Schema (if needed)
|
||||
|
||||
If the schema isn't already registered, you can add it to markitect's database:
|
||||
|
||||
```bash
|
||||
markitect schema-ingest markitect/schemas/terminology-schema.json
|
||||
```
|
||||
|
||||
### Generate Schema from Example
|
||||
|
||||
```bash
|
||||
markitect schema-generate terminology-example.md --output my-terminology-schema.json
|
||||
```
|
||||
|
||||
## Schema Features
|
||||
|
||||
This schema demonstrates several MarkiTect features:
|
||||
|
||||
### 1. Structural Validation
|
||||
|
||||
- Enforces consistent heading hierarchy (H1 → H2 → H3)
|
||||
- Validates minimum term count
|
||||
- Ensures proper document structure
|
||||
|
||||
### 2. Content Pattern Validation
|
||||
|
||||
- Validates title pattern (must contain terminology-related keywords)
|
||||
- Checks for required field labels (Definition:, Synonyms:, etc.)
|
||||
- Enforces consistent formatting
|
||||
|
||||
### 3. MarkiTect Extensions
|
||||
|
||||
The schema uses MarkiTect-specific extensions:
|
||||
|
||||
#### `x-markitect-sections`
|
||||
Defines section classifications and requirements:
|
||||
- `document_title` (required)
|
||||
- `category_sections` (required, min 1)
|
||||
- `term_definitions` (required, min 1)
|
||||
|
||||
#### `x-markitect-content-control`
|
||||
Specifies content requirements:
|
||||
- Required vs optional components
|
||||
- Content quality metrics (word counts)
|
||||
- Content instructions for authors
|
||||
|
||||
#### `x-markitect-validation-rules`
|
||||
Custom validation rules:
|
||||
- Minimum term count (3 required, 10+ recommended)
|
||||
- Category balance (min 2 terms per category)
|
||||
- Definition quality checks
|
||||
- Consistency validation
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Consistent Field Labels
|
||||
|
||||
Always use the same labels for metadata:
|
||||
```markdown
|
||||
**Definition:** ...
|
||||
**Synonyms:** ...
|
||||
**Related Terms:** ...
|
||||
```
|
||||
|
||||
### 2. Write Clear Definitions
|
||||
|
||||
- Start with the term's primary meaning
|
||||
- Use 10-200 words
|
||||
- Be self-contained (don't require reading other terms)
|
||||
- Avoid circular definitions
|
||||
|
||||
### 3. Group Related Terms
|
||||
|
||||
Organize terms into logical categories:
|
||||
- Core Concepts
|
||||
- Document Types
|
||||
- Process Terms
|
||||
- Quality Attributes
|
||||
- Deprecated Terms
|
||||
|
||||
### 4. Include Examples
|
||||
|
||||
Add practical examples for complex terms:
|
||||
```markdown
|
||||
**Example:**
|
||||
\`\`\`markdown
|
||||
# Heading
|
||||
Paragraph text
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### 5. Link Related Terms
|
||||
|
||||
Use **Related Terms:** to create a terminology graph:
|
||||
```markdown
|
||||
**Related Terms:** Parser, Token, Node
|
||||
```
|
||||
|
||||
## Extending the Schema
|
||||
|
||||
You can customize the schema for your project:
|
||||
|
||||
### Add Custom Field Labels
|
||||
|
||||
Extend the `bold_text` enum:
|
||||
```json
|
||||
"enum": [
|
||||
"Definition:",
|
||||
"Synonyms:",
|
||||
"Your Custom Label:"
|
||||
]
|
||||
```
|
||||
|
||||
### Adjust Quality Metrics
|
||||
|
||||
Modify content quality requirements:
|
||||
```json
|
||||
"content_quality": {
|
||||
"min_words_per_definition": 20,
|
||||
"max_words_per_definition": 300,
|
||||
"readability_target": "business"
|
||||
}
|
||||
```
|
||||
|
||||
### Add Domain-Specific Validation
|
||||
|
||||
Include specialized validation rules:
|
||||
```json
|
||||
"x-markitect-validation-rules": {
|
||||
"domain_specific": {
|
||||
"require_acronym_expansion": true,
|
||||
"require_source_citations": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Documentation Projects
|
||||
|
||||
- Software project glossaries
|
||||
- API terminology reference
|
||||
- Architecture decision records (ADR) glossary
|
||||
- Domain-driven design (DDD) ubiquitous language
|
||||
|
||||
### Technical Writing
|
||||
|
||||
- Standards documentation
|
||||
- Compliance documentation (ISO, SOC2)
|
||||
- Technical specifications
|
||||
- Research papers
|
||||
|
||||
### Knowledge Management
|
||||
|
||||
- Company wikis
|
||||
- Team handbooks
|
||||
- Onboarding documentation
|
||||
- Training materials
|
||||
|
||||
## Integration with CI/CD
|
||||
|
||||
### Pre-commit Hook
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-commit
|
||||
markitect validate docs/glossary.md --schema schemas/terminology-schema.json
|
||||
```
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
name: Validate Terminology
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Install MarkiTect
|
||||
run: pip install markitect
|
||||
- name: Validate Glossary
|
||||
run: |
|
||||
markitect validate docs/glossary.md \
|
||||
--schema schemas/terminology-schema.json \
|
||||
--detailed-errors
|
||||
```
|
||||
|
||||
## Related Examples
|
||||
|
||||
- **manpages/** - Manual page documentation validation
|
||||
- **templates/** - Document template examples
|
||||
- **design-patterns/** - Software pattern documentation
|
||||
|
||||
## Learn More
|
||||
|
||||
- [Schema Extensions Specification](../../docs/specifications/schema-extensions-spec.md)
|
||||
- [MarkiTect Documentation](../../README.md)
|
||||
- [JSON Schema Documentation](https://json-schema.org/)
|
||||
|
||||
## Contributing
|
||||
|
||||
To improve this example:
|
||||
|
||||
1. Add more terms to demonstrate edge cases
|
||||
2. Enhance the schema with additional validation rules
|
||||
3. Create alternative terminology document styles
|
||||
4. Add multilingual terminology examples
|
||||
|
||||
## License
|
||||
|
||||
This example is part of the MarkiTect project and follows the same license.
|
||||
91
examples/terminology/terminology-example.md
Normal file
91
examples/terminology/terminology-example.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# Project Terminology
|
||||
|
||||
A glossary of key terms and concepts for this project.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Abstract Syntax Tree
|
||||
|
||||
**Definition:** A tree representation of the abstract syntactic structure of source code or markup, where each node represents a construct occurring in the source.
|
||||
|
||||
**Synonyms:** AST, Parse Tree
|
||||
|
||||
**Related Terms:** Parser, Token, Node
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
# Heading
|
||||
Paragraph text
|
||||
```
|
||||
|
||||
The AST representation would include nodes for heading (level 1) and paragraph elements.
|
||||
|
||||
### Schema Validation
|
||||
|
||||
**Definition:** The process of verifying that a document's structure conforms to a predefined schema specification.
|
||||
|
||||
**Synonyms:** Structural Validation, Schema Conformance
|
||||
|
||||
**Related Terms:** JSON Schema, Validator, Metaschema
|
||||
|
||||
**Use Cases:**
|
||||
- Ensuring documentation completeness
|
||||
- Enforcing content standards
|
||||
- Automated quality checks
|
||||
|
||||
## Document Types
|
||||
|
||||
### Manpage
|
||||
|
||||
**Definition:** A manual page document following Unix/Linux documentation conventions, typically including sections like SYNOPSIS, DESCRIPTION, and OPTIONS.
|
||||
|
||||
**Format:** Markdown with specific heading structure
|
||||
|
||||
**Related Terms:** Documentation, Manual, Help Text
|
||||
|
||||
### Blueprint
|
||||
|
||||
**Definition:** A template specification that combines schemas, content instructions, and data templates for generating documents.
|
||||
|
||||
**Components:**
|
||||
- Schema references
|
||||
- Content model
|
||||
- Data schema
|
||||
- Generation rules
|
||||
|
||||
## Process Terms
|
||||
|
||||
### Schema Refinement
|
||||
|
||||
**Definition:** The process of transforming a rigid, auto-generated schema into a flexible, classification-aware schema with content guidance.
|
||||
|
||||
**Steps:**
|
||||
1. Analyze existing schema for rigidity
|
||||
2. Loosen exact constraints to ranges
|
||||
3. Add classification metadata
|
||||
4. Include content instructions
|
||||
|
||||
**Tools:** `markitect schema-analyze`, `markitect schema-refine`
|
||||
|
||||
## Quality Attributes
|
||||
|
||||
### Classification Levels
|
||||
|
||||
**Definition:** A hierarchical system for categorizing document elements based on their importance and requirements.
|
||||
|
||||
**Levels:**
|
||||
- **Required**: Must be present (validation fails if missing)
|
||||
- **Recommended**: Should be present (warning if missing)
|
||||
- **Optional**: May be present (no impact)
|
||||
- **Discouraged**: Should not be present (warning if present)
|
||||
- **Improper**: Must not be present (validation fails if present)
|
||||
|
||||
## Deprecated Terms
|
||||
|
||||
### Rigid Schema
|
||||
|
||||
**Status:** DEPRECATED - Use "Unrefined Schema" instead
|
||||
|
||||
**Definition:** A schema with exact count constraints that make it unusable as a pattern.
|
||||
|
||||
**Migration:** Use schema refinement tools to convert to flexible schemas.
|
||||
214
examples/terminology/terminology-schema.json
Normal file
214
examples/terminology/terminology-schema.json
Normal file
@@ -0,0 +1,214 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"$id": "https://markitect.dev/schemas/terminology-v1.json",
|
||||
"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
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user