markitect-main/examples/terminology/README.md

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:

# 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

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:

markitect schema-ingest markitect/schemas/terminology-schema.json

Generate Schema from Example

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:

**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 schemas/terminology-schema.json

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 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
• 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.