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

schema-id, version, status, domain, description

schema-id	version	status	domain	description
https://markitect.dev/schemas/schema/v1.0	1.0.0	stable	schema	Metaschema for validating MarkiTect schema files

Schema-for-Schemas v1.0

Overview

This metaschema validates that MarkiTect schema files follow conventions and standards. It ensures schemas are well-formed, properly versioned, and include required MarkiTect extensions.

Purpose: Quality assurance for schema authors

Validates:

• Core JSON Schema fields (title, description, $schema, $id)
• Version format (SemVer: major.minor.patch)
• $id URL format (HTTPS with version)
• MarkiTect extensions (x-markitect-*)
• Section classification structures
• Content control patterns

Schema Conventions

Required Fields

Every MarkiTect schema MUST include:

1. $schema: JSON Schema version (draft-07)
2. $id: Canonical HTTPS URL with version
3. title: Human-readable schema name
4. description: Brief explanation of what the schema validates
5. version: SemVer version string (major.minor.patch)

Recommended Fields

Schemas SHOULD include:

• type: Root schema type (usually "object")
• properties: Object properties definition
• required: Array of required property names

MarkiTect Extensions

x-markitect-sections

Defines document sections with classifications and content rules.

Structure:

{
  "SECTION_NAME": {
    "classification": "required|recommended|optional|discouraged|improper",
    "heading_level": 2,
    "content_instruction": "What this section should contain",
    "min_paragraphs": 1,
    "max_paragraphs": 10,
    "min_code_blocks": 0,
    "max_code_blocks": 5,
    "alternatives": ["ALTERNATIVE_NAME"],
    "error_message": "Error if validation fails",
    "warning_if_missing": "Warning if section absent"
  }
}

Classifications:

• required: Section must be present
• recommended: Section should be present (warning if missing)
• optional: Section may be present
• discouraged: Section should be avoided (warning if present)
• improper: Section must not be present (error if present)

x-markitect-content-control

Defines content patterns and quality metrics.

Structure:

{
  "section_name": {
    "required_patterns": ["regex1", "regex2"],
    "discouraged_patterns": ["regex3"],
    "forbidden_patterns": ["regex4"],
    "content_quality": {
      "min_words": 50,
      "max_words": 1000,
      "readability_target": "technical|general",
      "min_sentences": 3
    },
    "content_instructions": ["instruction1", "instruction2"],
    "link_validation": {
      "check_internal": true,
      "check_external": false,
      "allow_fragments": true
    }
  }
}

x-markitect-metadata

Additional schema metadata.

Structure:

{
  "status": "stable|draft|deprecated",
  "authors": ["Author Name <email@example.com>"],
  "created": "2026-01-04",
  "updated": "2026-01-04",
  "tags": ["tag1", "tag2"]
}

x-markitect-source

Automatically added by schema loader (not in schema file).

Structure:

{
  "file": "/path/to/schema-v1.0.md",
  "filename": "schema-v1.0.md",
  "format": "markdown",
  "frontmatter": {...}
}

Validation Rules

$id Format

Must be HTTPS URL with version:

https://markitect.dev/schemas/{domain}/v{major}

Examples:

• ✅ https://markitect.dev/schemas/manpage/v1.0
• ✅ https://markitect.dev/schemas/api-documentation/v2.0
• ❌ http://example.com/schema (not HTTPS)
• ❌ https://markitect.dev/schemas/manpage (no version)

Version Format

Must be SemVer (major.minor.patch):

{major}.{minor}.{patch}

Examples:

• ✅ 1.0.0
• ✅ 2.5.3
• ❌ 1.0 (missing patch)
• ❌ v1.0.0 (has 'v' prefix)

Title Format

Should be descriptive and end with "Schema":

Examples:

• ✅ "Unix Manual Page Schema"
• ✅ "API Documentation Schema"
• ❌ "Schema" (too generic)

Usage

Validating a Schema

# Validate a schema file
markitect schema-validate manpage-schema-v1.0.md

# Show detailed errors
markitect schema-validate manpage-schema-v1.0.md --detailed-errors

Programmatic Usage

from pathlib import Path
from markitect.schema_loader import MarkdownSchemaLoader

# Load schema to validate
loader = MarkdownSchemaLoader()
schema_data = loader.load_schema(Path("my-schema-v1.0.md"))

# Check structure
issues = loader.validate_schema_structure(schema_data['schema'])
if issues:
    for issue in issues:
        print(f"⚠️  {issue}")

Common Validation Errors

Missing Required Fields

Error: Missing required field: $schema

Solution: Add $schema field:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  ...
}

Invalid $id Format

Error: $id should be a full HTTPS URL

Solution: Use proper format:

{
  "$id": "https://markitect.dev/schemas/my-domain/v1.0",
  ...
}

Invalid Version Format

Error: version must be in SemVer format (major.minor.patch)

Solution: Use three-part version:

{
  "version": "1.0.0",
  ...
}

Invalid Section Classification

Error: Invalid classification value: 'mandatory'

Solution: Use valid classification:

{
  "x-markitect-sections": {
    "SYNOPSIS": {
      "classification": "required",
      ...
    }
  }
}

Valid values: required, recommended, optional, discouraged, improper

Schema Definition

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://markitect.dev/schemas/schema/v1.0",
  "title": "MarkiTect Schema-for-Schemas",
  "description": "Metaschema for validating MarkiTect schema files",
  "version": "1.0.0",
  "type": "object",
  "required": ["$schema", "$id", "title", "description", "version"],
  "properties": {
    "$schema": {
      "type": "string",
      "const": "http://json-schema.org/draft-07/schema#",
      "description": "JSON Schema version (must be draft-07)"
    },
    "$id": {
      "type": "string",
      "pattern": "^https://[a-z0-9.-]+/schemas/[a-z0-9-]+/v[0-9]+\\.[0-9]+$",
      "description": "Canonical schema URI with HTTPS and version"
    },
    "title": {
      "type": "string",
      "minLength": 5,
      "maxLength": 200,
      "description": "Human-readable schema name"
    },
    "description": {
      "type": "string",
      "minLength": 10,
      "maxLength": 500,
      "description": "Brief explanation of what this schema validates"
    },
    "version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "description": "Semantic version (major.minor.patch)"
    },
    "type": {
      "type": "string",
      "enum": ["object", "array", "string", "number", "boolean", "null"],
      "description": "Root schema type"
    },
    "properties": {
      "type": "object",
      "description": "Object property definitions"
    },
    "required": {
      "type": "array",
      "items": {"type": "string"},
      "description": "Required property names"
    },
    "x-markitect-sections": {
      "type": "object",
      "description": "Section definitions with classifications",
      "patternProperties": {
        "^[A-Z][A-Z0-9_ ]*$": {
          "type": "object",
          "required": ["classification", "heading_level"],
          "properties": {
            "classification": {
              "type": "string",
              "enum": ["required", "recommended", "optional", "discouraged", "improper"],
              "description": "Section requirement level"
            },
            "heading_level": {
              "type": "integer",
              "minimum": 1,
              "maximum": 6,
              "description": "Markdown heading level (1-6)"
            },
            "position": {
              "type": "string",
              "enum": ["after_title", "before_title", "anywhere"],
              "description": "Section position constraint"
            },
            "content_instruction": {
              "type": "string",
              "description": "What this section should contain"
            },
            "min_paragraphs": {
              "type": "integer",
              "minimum": 0,
              "description": "Minimum paragraph count"
            },
            "max_paragraphs": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum paragraph count"
            },
            "min_code_blocks": {
              "type": "integer",
              "minimum": 0,
              "description": "Minimum code block count"
            },
            "max_code_blocks": {
              "type": "integer",
              "minimum": 0,
              "description": "Maximum code block count"
            },
            "alternatives": {
              "type": "array",
              "items": {"type": "string"},
              "description": "Alternative section names"
            },
            "error_message": {
              "type": "string",
              "description": "Error message if validation fails"
            },
            "warning_if_missing": {
              "type": "string",
              "description": "Warning message if section absent"
            }
          }
        }
      }
    },
    "x-markitect-content-control": {
      "type": "object",
      "description": "Content pattern and quality rules",
      "patternProperties": {
        "^[a-z_]+$": {
          "type": "object",
          "properties": {
            "required_patterns": {
              "type": "array",
              "items": {"type": "string"},
              "description": "Required regex patterns"
            },
            "discouraged_patterns": {
              "type": "array",
              "items": {"type": "string"},
              "description": "Patterns to warn about"
            },
            "forbidden_patterns": {
              "type": "array",
              "items": {"type": "string"},
              "description": "Patterns that cause errors"
            },
            "content_quality": {
              "type": "object",
              "properties": {
                "min_words": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Minimum word count"
                },
                "max_words": {
                  "type": "integer",
                  "minimum": 1,
                  "description": "Maximum word count"
                },
                "readability_target": {
                  "type": "string",
                  "enum": ["technical", "general"],
                  "description": "Target readability level"
                },
                "min_sentences": {
                  "type": "integer",
                  "minimum": 1,
                  "description": "Minimum sentence count"
                }
              }
            },
            "content_instructions": {
              "type": "array",
              "items": {"type": "string"},
              "description": "Content writing guidelines"
            },
            "link_validation": {
              "type": "object",
              "properties": {
                "check_internal": {
                  "type": "boolean",
                  "description": "Validate internal links"
                },
                "check_external": {
                  "type": "boolean",
                  "description": "Validate external links"
                },
                "allow_fragments": {
                  "type": "boolean",
                  "description": "Allow fragment identifiers"
                }
              }
            }
          }
        }
      }
    },
    "x-markitect-metadata": {
      "type": "object",
      "description": "Additional schema metadata",
      "properties": {
        "status": {
          "type": "string",
          "enum": ["stable", "draft", "deprecated"],
          "description": "Schema lifecycle status"
        },
        "authors": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Schema authors"
        },
        "created": {
          "type": "string",
          "format": "date",
          "description": "Creation date (ISO 8601)"
        },
        "updated": {
          "type": "string",
          "format": "date",
          "description": "Last update date (ISO 8601)"
        },
        "tags": {
          "type": "array",
          "items": {"type": "string"},
          "description": "Schema tags for categorization"
        }
      }
    },
    "x-markitect-source": {
      "type": "object",
      "description": "Source file metadata (added by loader)",
      "properties": {
        "file": {
          "type": "string",
          "description": "Full file path"
        },
        "filename": {
          "type": "string",
          "description": "File name only"
        },
        "format": {
          "type": "string",
          "enum": ["markdown", "json"],
          "description": "Source file format"
        },
        "frontmatter": {
          "type": "object",
          "description": "YAML frontmatter from markdown"
        }
      }
    }
  },
  "additionalProperties": true
}

Version History

v1.0.0 (2026-01-04)

• Initial metaschema version
• Validates core JSON Schema fields
• Validates MarkiTect extensions
• Supports section classifications
• Supports content control patterns
• SemVer version validation
• HTTPS $id URL validation

Related Documentation

• Schema Naming Specification
• Schema Loader Guide
• Schema Management Workplan