markitect-main/markitect/schemas/terminology-schema-v1.0.md

---
description: Schema for validating terminology and glossary documents with consistent
  structure
domain: terminology
schema-id: https://markitect.dev/schemas/terminology/v1.0
status: stable
version: 1.0.0
---

# Terminology Document Schema v1.0.0

## Overview

Schema for validating terminology and glossary documents with consistent structure

## Usage

```bash
markitect validate document.md --schema v1.0
```

## Schema Definition

```json
{
  "$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