tegwick
6df9b5df05
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>
2.5 KiB
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:
# 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:
- Analyze existing schema for rigidity
- Loosen exact constraints to ranges
- Add classification metadata
- 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.