markitect-main/markitect/schemas/markitect-metaschema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://markitect.io/schemas/markitect-metaschema.json",
  "type": "object",
  "title": "MarkiTect Extended JSON Schema Metaschema",
  "description": "Metaschema for MarkiTect JSON schemas that extends standard JSON Schema with MarkiTect-specific features for document structure analysis and generation",
  "allOf": [
    {
      "$ref": "http://json-schema.org/draft-07/schema#"
    },
    {
      "properties": {
        "x-markitect-heading-text": {
          "type": "string",
          "description": "Preserve actual heading text from source document for validation and template generation"
        },
        "x-markitect-content-instructions": {
          "type": "string",
          "description": "Instructions for content authors about what should go in this section"
        },
        "x-markitect-outline-mode": {
          "type": "boolean",
          "description": "Indicates if this schema was generated in outline mode, focusing on structural hierarchy"
        },
        "x-markitect-outline-depth": {
          "type": "integer",
          "minimum": 1,
          "description": "Maximum heading depth captured in outline mode"
        },
        "x-markitect-instruction-type": {
          "type": "string",
          "enum": ["description", "example", "constraint", "template"],
          "description": "Type of content instruction provided"
        },
        "x-markitect-generated-from": {
          "type": "string",
          "description": "Source file or document this schema was generated from"
        },
        "x-markitect-generation-mode": {
          "type": "string",
          "enum": ["outline", "full"],
          "description": "Mode used to generate this schema"
        },
        "x-markitect-sections": {
          "type": "object",
          "description": "Section classification and content control for document sections",
          "patternProperties": {
            "^[A-Z][A-Z0-9_ ]*$": {
              "type": "object",
              "description": "Section definition with classification and constraints",
              "properties": {
                "classification": {
                  "type": "string",
                  "enum": ["required", "recommended", "optional", "discouraged", "improper"],
                  "description": "Classification level determining validation behavior"
                },
                "heading_level": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 6,
                  "description": "Expected heading level (H1-H6) for this section"
                },
                "position": {
                  "type": "string",
                  "enum": ["after_title", "before_section_name", "after_section_name", "anywhere"],
                  "description": "Where this section should appear in the document"
                },
                "content_instruction": {
                  "type": "string",
                  "description": "Human-readable instruction for section content"
                },
                "min_paragraphs": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Minimum number of paragraphs in this section"
                },
                "max_paragraphs": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Maximum number of paragraphs in this section"
                },
                "min_code_blocks": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Minimum number of code blocks in this section"
                },
                "max_code_blocks": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Maximum number of code blocks in this section"
                },
                "min_lists": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Minimum number of lists in this section"
                },
                "max_lists": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Maximum number of lists in this section"
                },
                "warning_if_missing": {
                  "type": "string",
                  "description": "Custom warning message for missing recommended sections"
                },
                "error_message": {
                  "type": "string",
                  "description": "Custom error message for required/improper section violations"
                },
                "alternatives": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Alternative section names that satisfy the requirement"
                }
              },
              "required": ["classification"]
            }
          }
        },
        "x-markitect-content-control": {
          "type": "object",
          "description": "Content validation rules including patterns and quality metrics",
          "patternProperties": {
            "^[a-z][a-z0-9_]*$": {
              "type": "object",
              "description": "Content control rules for a specific section",
              "properties": {
                "required_patterns": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Regex patterns that must appear in section content"
                },
                "discouraged_patterns": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Regex patterns that should not appear in content (warning)"
                },
                "forbidden_patterns": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Regex patterns that must not appear in content (error)"
                },
                "content_quality": {
                  "type": "object",
                  "description": "Quality metrics for section content",
                  "properties": {
                    "min_words": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Minimum word count"
                    },
                    "max_words": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Maximum word count"
                    },
                    "readability_target": {
                      "type": "string",
                      "enum": ["simple", "general", "technical", "advanced"],
                      "description": "Target readability level"
                    },
                    "min_sentences": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Minimum sentence count"
                    },
                    "max_sentences": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Maximum sentence count"
                    }
                  }
                },
                "content_instructions": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "Array of human-readable content creation instructions"
                },
                "link_validation": {
                  "type": "object",
                  "description": "Link checking configuration",
                  "properties": {
                    "check_internal": {
                      "type": "boolean",
                      "description": "Validate internal document links"
                    },
                    "check_external": {
                      "type": "boolean",
                      "description": "Validate external URLs"
                    },
                    "allow_fragments": {
                      "type": "boolean",
                      "description": "Allow fragment-only links like #section"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "patternProperties": {
        "^x-markitect-": {
          "description": "MarkiTect extension properties"
        }
      }
    }
  ]
}