markitect-main/examples/terminology

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
• Schema: terminology-schema-v1.0.md (in markitect/schemas/)
• README.md - This file

The terminology schema now follows the schema-of-schemas standard with markdown format and embedded JSON.

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

List Available Schemas

View all registered schemas (including terminology schema):

markitect schema-list

You should see terminology-schema-v1.0.md listed with a number.

Validate Using the Schema

The terminology schema is registered in MarkiTect's database. You can validate using multiple methods:

# By schema number (if terminology schema is #4 in the list)
markitect schema-validate 4

# By schema filename (from registry)
markitect schema-validate terminology-schema-v1.0.md

# Validate a specific document file
markitect validate my-glossary.md --schema terminology-schema-v1.0.md

# Or use the local file path directly
markitect validate my-glossary.md --schema ./markitect/schemas/terminology-schema-v1.0.md

Validate with Detailed Errors

markitect schema-validate terminology-schema-v1.0.md --detailed-errors

Batch Validation

Validate multiple schemas at once:

# Validate all schemas
markitect schema-validate --all

# Validate a range
markitect schema-validate 1-4

# Validate specific schemas
markitect schema-validate 2,4

View the Schema

Examine the terminology schema:

# Get from registry
markitect schema-get terminology-schema-v1.0.md

# Or view the markdown file directly
cat markitect/schemas/terminology-schema-v1.0.md

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:

**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:

**Example:**
\`\`\`markdown
# Heading
Paragraph text
\`\`\`

5. Link Related Terms

Use Related Terms: to create a terminology graph:

**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:

"enum": [
  "Definition:",
  "Synonyms:",
  "Your Custom Label:"
]

Adjust Quality Metrics

Modify content quality requirements:

"content_quality": {
  "min_words_per_definition": 20,
  "max_words_per_definition": 300,
  "readability_target": "business"
}

Add Domain-Specific Validation

Include specialized validation rules:

"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

#!/bin/bash
# .git/hooks/pre-commit
markitect validate docs/glossary.md --schema terminology-schema-v1.0.md

GitHub Actions

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 terminology-schema-v1.0.md \
            --detailed-errors

Related Examples

• manpages/ - Manual page documentation validation
• templates/ - Document template examples
• design-patterns/ - Software pattern documentation

Learn More

• Schema Extensions Specification
• MarkiTect Documentation
• JSON Schema Documentation

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.