{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/commonmark-gfm-markdig.schema.1.0.0.json",
  "title": "CommonMark + GFM Markdown AST (Markdig target)",
  "description": "A strict semantic AST schema for JSON documents that can be rendered as CommonMark + GitHub Flavored Markdown (GFM) using Markdig. This models the Markdown feature surface, not byte-for-byte source trivia.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "$schema",
    "type",
    "children"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri"
    },
    "type": {
      "const": "document"
    },
    "children": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/blockNode"
      }
    },
    "options": {
      "type": "object",
      "description": "Optional renderer-oriented preferences. These do not change the semantic meaning of the document.",
      "additionalProperties": false,
      "properties": {
        "renderer": {
          "const": "Markdig"
        },
        "flavor": {
          "const": "CommonMark+GFM"
        },
        "preferReferenceLinks": {
          "type": "boolean",
          "default": false
        },
        "gfmTagFilterOnHtmlRender": {
          "type": "boolean",
          "default": true,
          "description": "If the Markdown is later rendered to HTML, apply GFM disallowed raw HTML filtering."
        }
      }
    }
  },
  "$defs": {
    "nonEmptyString": {
      "type": "string",
      "minLength": 1
    },
    "uriLikeString": {
      "type": "string",
      "minLength": 1
    },
    "titleValue": {
      "type": [
        "string",
        "null"
      ]
    },
    "alignment": {
      "enum": [
        "left",
        "center",
        "right",
        null
      ]
    },
    "inlineChildren": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/inlineNode"
      }
    },
    "blockChildren": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/blockNode"
      }
    },
    "textNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "text"
      ],
      "properties": {
        "type": {
          "const": "text"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "text": {
          "type": "string"
        }
      },
      "description": "Plain text content."
    },
    "softBreakNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "const": "softBreak"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        }
      },
      "description": "A soft line break."
    },
    "hardBreakNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "const": "hardBreak"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "syntax": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "kind": {
              "enum": [
                "backslash",
                "spaces"
              ]
            }
          }
        }
      },
      "description": "A hard line break."
    },
    "codeSpanNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "text"
      ],
      "properties": {
        "type": {
          "const": "codeSpan"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "text": {
          "type": "string"
        }
      },
      "description": "Inline code span."
    },
    "emphasisNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "children"
      ],
      "properties": {
        "type": {
          "const": "emphasis"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "children": {
          "$ref": "#/$defs/inlineChildren"
        }
      },
      "description": "Emphasis / italic content."
    },
    "strongNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "children"
      ],
      "properties": {
        "type": {
          "const": "strong"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "children": {
          "$ref": "#/$defs/inlineChildren"
        }
      },
      "description": "Strong / bold content."
    },
    "strikethroughNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "children"
      ],
      "properties": {
        "type": {
          "const": "strikethrough"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "children": {
          "$ref": "#/$defs/inlineChildren"
        }
      },
      "description": "GFM strikethrough content."
    },
    "rawHtmlInlineNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "raw"
      ],
      "properties": {
        "type": {
          "const": "rawHtmlInline"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "raw": {
          "type": "string",
          "minLength": 1
        }
      },
      "description": "Raw inline HTML."
    },
    "autolinkNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "destination",
        "text",
        "kind"
      ],
      "properties": {
        "type": {
          "const": "autolink"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "kind": {
          "enum": [
            "uri",
            "email",
            "extended"
          ]
        },
        "destination": {
          "$ref": "#/$defs/uriLikeString"
        },
        "text": {
          "type": "string"
        },
        "syntax": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "kind": {
              "enum": [
                "angle",
                "extended"
              ]
            }
          }
        }
      },
      "description": "Autolink node for angle-bracket autolinks or GFM extended autolinks."
    },
    "referenceLinkStyle": {
      "enum": [
        "inline",
        "fullReference",
        "collapsedReference",
        "shortcutReference"
      ]
    },
    "linkNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "children",
        "style"
      ],
      "properties": {
        "type": {
          "const": "link"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "children": {
          "$ref": "#/$defs/inlineChildren"
        },
        "style": {
          "$ref": "#/$defs/referenceLinkStyle"
        },
        "destination": {
          "$ref": "#/$defs/uriLikeString"
        },
        "title": {
          "$ref": "#/$defs/titleValue"
        },
        "referenceId": {
          "$ref": "#/$defs/nonEmptyString"
        }
      },
      "description": "Link inline.",
      "allOf": [
        {
          "if": {
            "properties": {
              "style": {
                "const": "inline"
              }
            },
            "required": [
              "style"
            ]
          },
          "then": {
            "required": [
              "destination"
            ]
          }
        },
        {
          "if": {
            "properties": {
              "style": {
                "enum": [
                  "fullReference",
                  "collapsedReference",
                  "shortcutReference"
                ]
              }
            },
            "required": [
              "style"
            ]
          },
          "then": {
            "required": [
              "referenceId"
            ]
          }
        }
      ]
    },
    "imageNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "children",
        "style"
      ],
      "properties": {
        "type": {
          "const": "image"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "children": {
          "$ref": "#/$defs/inlineChildren"
        },
        "style": {
          "$ref": "#/$defs/referenceLinkStyle"
        },
        "destination": {
          "$ref": "#/$defs/uriLikeString"
        },
        "title": {
          "$ref": "#/$defs/titleValue"
        },
        "referenceId": {
          "$ref": "#/$defs/nonEmptyString"
        }
      },
      "description": "Image inline.",
      "allOf": [
        {
          "if": {
            "properties": {
              "style": {
                "const": "inline"
              }
            },
            "required": [
              "style"
            ]
          },
          "then": {
            "required": [
              "destination"
            ]
          }
        },
        {
          "if": {
            "properties": {
              "style": {
                "enum": [
                  "fullReference",
                  "collapsedReference",
                  "shortcutReference"
                ]
              }
            },
            "required": [
              "style"
            ]
          },
          "then": {
            "required": [
              "referenceId"
            ]
          }
        }
      ]
    },
    "inlineNode": {
      "oneOf": [
        {
          "$ref": "#/$defs/textNode"
        },
        {
          "$ref": "#/$defs/softBreakNode"
        },
        {
          "$ref": "#/$defs/hardBreakNode"
        },
        {
          "$ref": "#/$defs/codeSpanNode"
        },
        {
          "$ref": "#/$defs/emphasisNode"
        },
        {
          "$ref": "#/$defs/strongNode"
        },
        {
          "$ref": "#/$defs/strikethroughNode"
        },
        {
          "$ref": "#/$defs/linkNode"
        },
        {
          "$ref": "#/$defs/imageNode"
        },
        {
          "$ref": "#/$defs/autolinkNode"
        },
        {
          "$ref": "#/$defs/rawHtmlInlineNode"
        }
      ]
    },
    "tableCellNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "children"
      ],
      "properties": {
        "type": {
          "const": "tableCell"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "children": {
          "$ref": "#/$defs/inlineChildren"
        }
      },
      "description": "A GFM table cell. Only inline content is allowed."
    },
    "tableRowNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "cells"
      ],
      "properties": {
        "type": {
          "const": "tableRow"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "cells": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/tableCellNode"
          }
        }
      },
      "description": "A GFM table row."
    },
    "paragraphNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "children"
      ],
      "properties": {
        "type": {
          "const": "paragraph"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "children": {
          "$ref": "#/$defs/inlineChildren"
        }
      },
      "description": "Paragraph block."
    },
    "headingNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "level",
        "children"
      ],
      "properties": {
        "type": {
          "const": "heading"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "level": {
          "type": "integer",
          "minimum": 1,
          "maximum": 6
        },
        "children": {
          "$ref": "#/$defs/inlineChildren"
        },
        "syntax": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "style": {
              "enum": [
                "atx",
                "setext"
              ]
            },
            "closingSequence": {
              "type": "boolean"
            },
            "setextMarker": {
              "enum": [
                "=",
                "-"
              ]
            }
          }
        }
      },
      "description": "ATX or Setext heading.",
      "allOf": [
        {
          "if": {
            "properties": {
              "syntax": {
                "type": "object",
                "properties": {
                  "style": {
                    "const": "setext"
                  }
                },
                "required": [
                  "style"
                ]
              }
            },
            "required": [
              "syntax"
            ]
          },
          "then": {
            "properties": {
              "level": {
                "enum": [
                  1,
                  2
                ]
              }
            }
          }
        }
      ]
    },
    "thematicBreakNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "const": "thematicBreak"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "syntax": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "marker": {
              "enum": [
                "-",
                "*",
                "_"
              ]
            },
            "count": {
              "type": "integer",
              "minimum": 3
            }
          }
        }
      },
      "description": "Thematic break / horizontal rule."
    },
    "codeBlockNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "text",
        "syntax"
      ],
      "properties": {
        "type": {
          "const": "codeBlock"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "text": {
          "type": "string"
        },
        "language": {
          "type": "string"
        },
        "info": {
          "type": "string"
        },
        "syntax": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "style"
          ],
          "properties": {
            "style": {
              "enum": [
                "fenced",
                "indented"
              ]
            },
            "fenceChar": {
              "enum": [
                "`",
                "~"
              ]
            },
            "fenceLength": {
              "type": "integer",
              "minimum": 3
            }
          }
        }
      },
      "description": "Fenced or indented code block.",
      "allOf": [
        {
          "if": {
            "properties": {
              "syntax": {
                "properties": {
                  "style": {
                    "const": "fenced"
                  }
                },
                "required": [
                  "style"
                ]
              }
            }
          },
          "then": {
            "properties": {
              "syntax": {
                "required": [
                  "style",
                  "fenceChar",
                  "fenceLength"
                ]
              }
            }
          }
        }
      ]
    },
    "rawHtmlBlockNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "raw"
      ],
      "properties": {
        "type": {
          "const": "rawHtmlBlock"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "raw": {
          "type": "string",
          "minLength": 1
        }
      },
      "description": "Raw HTML block."
    },
    "linkReferenceDefinitionNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "identifier",
        "destination"
      ],
      "properties": {
        "type": {
          "const": "linkReferenceDefinition"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "identifier": {
          "$ref": "#/$defs/nonEmptyString"
        },
        "destination": {
          "$ref": "#/$defs/uriLikeString"
        },
        "title": {
          "$ref": "#/$defs/titleValue"
        }
      },
      "description": "Link reference definition block. Use with link/image nodes whose style is fullReference, collapsedReference, or shortcutReference."
    },
    "tableNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "header",
        "align",
        "rows"
      ],
      "properties": {
        "type": {
          "const": "table"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "header": {
          "$ref": "#/$defs/tableRowNode"
        },
        "align": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/alignment"
          }
        },
        "rows": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/tableRowNode"
          }
        }
      },
      "description": "GFM table block. The schema enforces header/body structure and per-cell inline content. A runtime validator should also ensure that align length and every row's cell count match the header cell count."
    },
    "blockQuoteNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "children"
      ],
      "properties": {
        "type": {
          "const": "blockQuote"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "children": {
          "$ref": "#/$defs/blockChildren"
        }
      },
      "description": "Block quote container."
    },
    "listItemNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "children"
      ],
      "properties": {
        "type": {
          "const": "listItem"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "children": {
          "$ref": "#/$defs/blockChildren"
        }
      },
      "description": "Standard list item."
    },
    "taskListItemNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "checked",
        "children"
      ],
      "properties": {
        "type": {
          "const": "taskListItem"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "checked": {
          "type": "boolean"
        },
        "children": {
          "$ref": "#/$defs/blockChildren"
        }
      },
      "description": "GFM task list item."
    },
    "listItemLikeNode": {
      "oneOf": [
        {
          "$ref": "#/$defs/listItemNode"
        },
        {
          "$ref": "#/$defs/taskListItemNode"
        }
      ]
    },
    "listNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "ordered",
        "children"
      ],
      "properties": {
        "type": {
          "const": "list"
        },
        "meta": {
          "type": "object",
          "description": "Optional implementation metadata for downstream tooling.",
          "additionalProperties": true
        },
        "ordered": {
          "type": "boolean"
        },
        "tight": {
          "type": "boolean"
        },
        "start": {
          "type": "integer",
          "minimum": 0
        },
        "children": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/listItemLikeNode"
          }
        },
        "syntax": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "bulletMarker": {
              "enum": [
                "-",
                "+",
                "*"
              ]
            },
            "orderedDelimiter": {
              "enum": [
                ".",
                ")"
              ]
            }
          }
        }
      },
      "description": "Bullet or ordered list.",
      "allOf": [
        {
          "if": {
            "properties": {
              "ordered": {
                "const": true
              }
            },
            "required": [
              "ordered"
            ]
          },
          "then": {
            "properties": {
              "syntax": {
                "type": "object",
                "required": [
                  "orderedDelimiter"
                ]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "ordered": {
                "const": false
              }
            },
            "required": [
              "ordered"
            ]
          },
          "then": {
            "properties": {
              "syntax": {
                "type": "object",
                "required": [
                  "bulletMarker"
                ]
              }
            }
          }
        }
      ]
    },
    "blockNode": {
      "oneOf": [
        {
          "$ref": "#/$defs/paragraphNode"
        },
        {
          "$ref": "#/$defs/headingNode"
        },
        {
          "$ref": "#/$defs/thematicBreakNode"
        },
        {
          "$ref": "#/$defs/codeBlockNode"
        },
        {
          "$ref": "#/$defs/rawHtmlBlockNode"
        },
        {
          "$ref": "#/$defs/linkReferenceDefinitionNode"
        },
        {
          "$ref": "#/$defs/tableNode"
        },
        {
          "$ref": "#/$defs/blockQuoteNode"
        },
        {
          "$ref": "#/$defs/listNode"
        }
      ]
    }
  },
  "for-ai": [
    {
      "instruction": "Use this guidance when preparing a valid value for this schema node.",
      "input": "",
      "output": "Markdown document schema for Template Artifact Definitions. Use this AST when a template instance should be authored as structured CommonMark plus GFM content rendered through Markdig, and keep the authored JSON focused on final document structure rather than bindings, loops, or template expressions."
    }
  ]
}