---
schema-id: "https://markitect.dev/schemas/schema/v1.0"
version: "1.0.0"
status: "stable"
domain: "schema"
description: "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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

```bash
# 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

```python
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:
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  ...
}
```

### Invalid $id Format

**Error**: `$id should be a full HTTPS URL`

**Solution**: Use proper format:
```json
{
  "$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:
```json
{
  "version": "1.0.0",
  ...
}
```

### Invalid Section Classification

**Error**: `Invalid classification value: 'mandatory'`

**Solution**: Use valid classification:
```json
{
  "x-markitect-sections": {
    "SYNOPSIS": {
      "classification": "required",
      ...
    }
  }
}
```

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

## Schema Definition

```json
{
  "$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](../../roadmap/schema-of-schemas/SCHEMA_NAMING_SPEC.md)
- [Schema Loader Guide](../../roadmap/schema-of-schemas/SCHEMA_LOADER_GUIDE.md)
- [Schema Management Workplan](../../roadmap/schema-of-schemas/WORKPLAN.md)