{
  "$schema": "https://www.cuddler.dev/standards/specification-root-1.0.0.json",
  "meta": {
    "standardId": "specification-root",
    "standardVersion": "1.0.0",
    "documentType": "document-role-specification",
    "version": "1.0.0",
    "title": "Template Document Role",
    "status": "Public normative publication",
    "publishedAt": "2026-03-20T00:00:00Z",
    "updatedAt": "2026-04-02T00:00:00Z",
    "canonicalVersionUrl": "https://www.cuddler.dev/standards/document-role/template/",
    "canonicalDocumentRoleSpecificationUrl": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/document-role-specification.json",
    "summary": "Template Document Role is the official Cuddler Document Role for release 1.0.0, defining the governing rules for this artifact domain and the Template-specific authoring summary Artifact Definitions in this domain must satisfy alongside the shared Artifact Specification, including markdown-compliant template JSON, renderer expectations, validation, diagnostics, security, and publication guidance.",
    "authors": [
      {
        "name": "Matt Edwards",
        "url": "https://www.cuddler.dev/standards/authors/matt-edwards/"
      }
    ],
    "license": "© 2026 IdeaTilt. This work is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). See https://www.cuddler.dev/license/ for the site license summary. You are free to share, use, adapt, and modify this material, including for commercial purposes, provided you give appropriate attribution and include a link to the original source URL and the CC BY 4.0 license at https://creativecommons.org/licenses/by/4.0/.",
    "copyright": "© 2026 IdeaTilt.",
    "domainSpecificationId": "template"
  },
  "content": {
    "abstract": "This release defines the full Template Document Role v1.0.0 in one self-contained publication. It governs the Template Document domain, classifies Template-oriented Artifact Definitions into that domain, and sets the domain-level summary for markdown-compliant template JSON, validation, diagnostics, renderer expectations, security, and publication rules those Artifact Definitions must satisfy alongside the shared Artifact Specification.",
    "documentMediaType": "text/html",
    "documentHtml": "<h2>Version 1.0.0</h2>\n<h3>Status</h3>\n<p>This document is the canonical public contract for the Cuddler Template Document domain in release <code>1.0.0</code>. Artifact Definitions classified into this domain MUST conform to both this Document Role and the shared Artifact Specification.</p>\n<p>This versioned Document Role is intentionally self-contained. It includes the complete normative contract for release <code>1.0.0</code>, and linked schemas, manifests, examples, or tests are supplementary rather than required reading.</p>\n<h3>1. Notational conventions</h3>\n<p>The key words \"MUST\", \"MUST NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this document are to be interpreted as described in BCP 14 (RFC 2119 and RFC 8174) when, and only when, they appear in all capitals.</p>\n<hr />\n<h3>2. Purpose and scope</h3>\n<p>Cuddler Template v1.0.0 standardizes a markdown-compliant JSON template document that targets CommonMark, GitHub Flavored Markdown (GFM), and Markdig.</p>\n<p>A conforming template flow keeps roles separate:</p>\n<ol>\n<li><code>data.schema.json</code> validates the structured source facts,</li>\n<li><code>template.schema.json</code> validates the authored template document JSON,</li>\n<li>the template document JSON is rendered only after that template JSON passes validation.</li>\n</ol>\n<p>This Document Role governs the template document contract itself. It does not define a binding language, placeholder system, loops, conditionals, partials, slots, or a reusable component graph. If an implementation needs those authoring conveniences, it must add them outside the interoperable Template v1.0.0 surface and still emit a valid markdown-compliant template document that satisfies this contract.</p>\n<p><strong>In scope (v1.0.0):</strong></p>\n<ul>\n<li>the canonical template-document envelope</li>\n<li>Template Schema authoring rules for markdown-compliant template JSON</li>\n<li>CommonMark plus GFM block and inline structures aligned to Markdig</li>\n<li>renderer option constraints</li>\n<li>table and reference-style semantic validation</li>\n<li>diagnostics, security, accessibility, and release artifacts</li>\n</ul>\n<p><strong>Out of scope (v1.0.0):</strong></p>\n<ul>\n<li>model binding</li>\n<li>template expressions</li>\n<li>loops and conditionals</li>\n<li>component registries</li>\n<li>editor UX</li>\n<li>transport protocols</li>\n</ul>\n<hr />\n<h3>3. Key terms</h3>\n<ul>\n<li><strong>Template document:</strong> a concrete JSON document that models the final reader-visible template structure as markdown AST data.</li>\n<li><strong>Template Schema:</strong> a JSON Schema that validates one template-document family and constrains its headings, paragraphs, tables, lists, quotations, images, and related markdown content.</li>\n<li><strong>Report:</strong> the final emitted output artifact produced from a validated template document, for example HTML or PDF.</li>\n<li><strong>Markdown AST:</strong> the semantic JSON structure that represents CommonMark plus GFM content rather than raw markdown source text.</li>\n<li><strong>Renderer options:</strong> authored preferences such as <code>renderer</code> and <code>flavor</code> that describe the intended markdown interpretation but do not change document semantics.</li>\n</ul>\n<hr />\n<h3>4. Conformance classes</h3>\n<h4>4.1 Conforming template document</h4>\n<p>A conforming template document MUST:</p>\n<ul>\n<li>match the canonical envelope defined in Section 6</li>\n<li>pass JSON Schema validation against its Template Schema</li>\n<li>stay within the CommonMark plus GFM markdown surface defined by this release</li>\n<li>pass the semantic validation rules in Section 8</li>\n<li>remain aligned with schema-level metadata and output declarations</li>\n</ul>\n<h4>4.2 Conforming Template Schema</h4>\n<p>A conforming Template Schema MUST:</p>\n<ul>\n<li>use JSON Schema Draft 2020-12</li>\n<li>follow the published Template authoring-profile schema</li>\n<li>anchor the instance contract to the published <code>commonmark-gfm-markdig.schema.1.0.0.json</code> schema or the equivalent <code>MarkdownDocument</code> definition in the base definitions bundle</li>\n<li>satisfy the published lint rules</li>\n<li>author renderer-visible guidance for every instance-visible schema node in <code>for-ai</code> Alpaca arrays</li>\n<li>remain aligned with exactly one Data Schema family and one output family</li>\n</ul>\n<h4>4.3 Conforming renderer</h4>\n<p>A conforming renderer MUST:</p>\n<ul>\n<li>validate the template document against the Template Schema before rendering</li>\n<li>run semantic checks after schema validation succeeds</li>\n<li>honor the declared markdown flavor and renderer constraints</li>\n<li>reject unsupported content types or invalid template documents with deterministic diagnostics</li>\n<li>refuse silent fallback to a different output target when the declared primary target is unsupported</li>\n</ul>\n<hr />\n<h3>5. Normative dependencies</h3>\n<p>Implementations MUST support JSON Schema Draft 2020-12, including <code>contains</code>, <code>minContains</code>, <code>unevaluatedProperties</code>, and <code>prefixItems</code> when an authored Template Schema uses them.</p>\n<p>Implementations MUST enforce required format assertions such as <code>uri</code>, <code>uri-reference</code>, and <code>date-time</code> either through JSON Schema format assertion support or by running equivalent deterministic semantic checks after schema validation.</p>\n<p>Markdown behavior is defined by CommonMark, GitHub Flavored Markdown, and Markdig as constrained by this contract. Markdig is the normative renderer target for the interoperable v1.0.0 surface.</p>\n<hr />\n<h3>6. Canonical template-document envelope</h3>\n<p>A Cuddler template document MUST be a JSON object with exactly these top-level properties:</p>\n<ul>\n<li><code>$schema</code> (required)</li>\n<li><code>type</code> (required and equal to <code>document</code>)</li>\n<li><code>children</code> (required)</li>\n<li><code>options</code> (optional but standardized)</li>\n</ul>\n<p>No other top-level properties are required by the interoperable surface, although a Template Schema MAY allow stricter family-specific rules.</p>\n<p><code>$schema</code> MUST equal the validating Template Schema <code>$id</code> exactly.</p>\n<p><code>children</code> MUST contain only supported block nodes. Block containers contain block nodes, inline containers contain inline nodes, table cells contain inline nodes only, and list items contain block nodes rather than raw inline arrays.</p>\n<hr />\n<h3>7. Markdown structure model</h3>\n<p>The published markdown AST support schema defines the interoperable node families for v1.0.0. Template Artifact Definitions narrow that base markdown surface to the exact document family they publish.</p>\n<p>The interoperable block surface includes:</p>\n<ul>\n<li><code>paragraph</code></li>\n<li><code>heading</code></li>\n<li><code>thematicBreak</code></li>\n<li><code>codeBlock</code></li>\n<li><code>rawHtmlBlock</code></li>\n<li><code>linkReferenceDefinition</code></li>\n<li><code>table</code></li>\n<li><code>blockQuote</code></li>\n<li><code>list</code></li>\n</ul>\n<p>The interoperable inline surface includes:</p>\n<ul>\n<li><code>text</code></li>\n<li><code>softBreak</code></li>\n<li><code>hardBreak</code></li>\n<li><code>codeSpan</code></li>\n<li><code>emphasis</code></li>\n<li><code>strong</code></li>\n<li><code>strikethrough</code></li>\n<li><code>link</code></li>\n<li><code>image</code></li>\n<li><code>autolink</code></li>\n<li><code>rawHtmlInline</code></li>\n</ul>\n<p>Template Schemas in this domain should convert family knowledge into exact markdown structure. When headings, table headers, section order, or list presence are knowable, the authored schema should fix them directly rather than leaving them open to examples.</p>\n<hr />\n<h3>8. Semantic validation and diagnostics</h3>\n<p>Schema validation alone is not sufficient. Conforming validators MUST also run deterministic semantic checks after schema success.</p>\n<p>The minimum public semantic checks for v1.0.0 are:</p>\n<ul>\n<li><code>align.length == header.cells.length</code> for every table</li>\n<li>every table body row width equals the header width</li>\n<li>reference-style links and images resolve to a matching <code>linkReferenceDefinition</code></li>\n</ul>\n<p>Diagnostics emitted by validators and renderers MUST conform to the published diagnostics schema for this release.</p>\n<hr />\n<h3>9. Security, privacy, and safety considerations</h3>\n<p>Implementations MUST treat template JSON, examples, raw HTML nodes, linked destinations, and schema-node <code>for-ai</code> guidance as untrusted input.</p>\n<p>Renderers SHOULD sanitize rendered HTML output, preserve safe defaults for raw HTML handling, and reject unsafe URI schemes or unsupported output targets with deterministic diagnostics.</p>\n<p>Template guidance, examples, and extracted content may contain confidential or personal data. Public examples SHOULD avoid real sensitive content, and real Artifact Documents remain confidential by default unless intentionally published as examples.</p>\n<hr />\n<h3>10. Authoring profile summary</h3>\n<p>A conforming Template Schema MUST be definitive. If a language, status value, date rule, content type, section count, markdown block inventory, or published bundle file can be fixed by the governing standards, it MUST be fixed directly in schema constraints instead of inferred from examples.</p>\n<p>Template Schemas SHOULD treat user-provided examples as business-domain evidence only. They may inform family-specific titles, labels, wording style, row semantics, or section narratives that the governing standards do not already define, but they MUST NOT widen the core markdown contract.</p>\n<hr />\n<h3>11. Published v1.0.0 artifacts</h3>\n<p>The release materials for template authoring, validation, and implementation include the document-role-specification, the base definitions bundle, the CommonMark plus GFM Markdig schema, the Template authoring-profile schema, the lint rules, the diagnostics schema, the conformance manifest, the release manifest, and informative examples such as the published markdown AST example and worked Artifact Definition families.</p>\n<p>These supporting artifacts aid authoring, validation, and interoperability testing. They do not add normative requirements beyond the ones stated in this document.</p>",
    "execution": {
      "implementerRequirements": [
        "Treat this Document Role as the governing contract for the Template Document domain. The shared Artifact Specification defines how Template Artifact Definitions are authored, while this document supplies the Template-specific drafting brief.",
        "Author well-informed <code>for-ai</code> arrays on schema nodes. Consumers of Cuddler standards should parse and follow that guidance when preparing Data, Template, and Process values, and each Alpaca-format entry should carry <code>instruction</code>, <code>input</code>, and <code>output</code> fields.",
        "Prefer definitive Template Schema constraints whenever a rule is knowable: fix language, meta.status, date or date-time handling, content types, exact section or component counts, exact published schema files, and markdown-structure limits in schema logic instead of leaving them open to examples.",
        "Do not infer optionality, alternate component shapes, or broader output targets from missing or conflicting examples; keep those conflicts in a brief unresolved-assumptions note outside the schema.",
        "Ensure every Artifact Definition in this domain also conforms to the shared Artifact Specification and exposes its governing Document Role and Artifact Specification version explicitly.",
        "Publish template-document JSON that models the final reader-visible markdown structure and never treat the public Template role as a binding language, placeholder system, or component graph."
      ],
      "validationWorkflow": [
        "Validate the Template Schema contract, then validate the template document instance against that schema, then run markdown semantic checks, then render.",
        "Fail authoring-profile validation when a required schema-node <code>for-ai</code> array is missing, malformed, or empty where the governing standards require one.",
        "Fail when markdown tables, reference-style links, renderer options, or metadata declarations drift from the v1.0.0 contract.",
        "Use the published diagnostics schema, lint rules, and conformance manifest to keep validation and renderer behavior deterministic, and let user-provided examples shape business-domain detail rather than override the contract."
      ],
      "publicationNotes": [
        "Publish the canonical self-contained normative document as document-role-specification.json and keep the paper-style page aligned to that same JSON source.",
        "Publish AI-facing schema-node guidance in <code>for-ai</code> Alpaca arrays instead of relying on JSON Schema <code>description</code> as the instruction channel.",
        "State the exact canonical schema-file inventory and what each published file validates whenever a Template Artifact Definition bundle contains multiple machine-readable files.",
        "Do not publish the Template v1.0.0 interoperable surface as a binding cookbook, component registry, or alternate template language; publish markdown AST guidance instead.",
        "Preserve attribution and include the original public URL when this Document Role, the Artifact Specification, or domain-classified Artifact Definitions are reused or adapted."
      ]
    },
    "artifactGroups": [
      {
        "key": "normative-artifacts",
        "title": "Normative Artifacts",
        "items": [
          {
            "id": "document-role-specification-document",
            "title": "Document Role document",
            "role": "document-role-specification",
            "publicationClass": "normative",
            "mediaType": "application/json",
            "url": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/document-role-specification.json"
          },
          {
            "id": "base-definitions",
            "title": "Template base definitions schema",
            "role": "base-defs",
            "publicationClass": "normative",
            "mediaType": "application/schema+json",
            "url": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/cuddler.template.base.defs.schema.1.0.0.json"
          },
          {
            "id": "markdown-schema",
            "title": "CommonMark + GFM Markdig schema",
            "role": "markdown-schema",
            "publicationClass": "normative",
            "mediaType": "application/schema+json",
            "url": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/commonmark-gfm-markdig.schema.1.0.0.json"
          },
          {
            "id": "authoring-profile-schema",
            "title": "Authoring-profile meta-schema",
            "role": "meta-schema",
            "publicationClass": "normative",
            "mediaType": "application/schema+json",
            "url": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/cuddler.template.authoring-profile.schema.1.0.0.json"
          },
          {
            "id": "lint-rules",
            "title": "Lint rules",
            "role": "lint-rules",
            "publicationClass": "normative",
            "mediaType": "application/json",
            "url": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/cuddler.template.lint.rules.1.0.0.json"
          },
          {
            "id": "diagnostics-schema",
            "title": "Diagnostics schema",
            "role": "diagnostics-schema",
            "publicationClass": "normative",
            "mediaType": "application/schema+json",
            "url": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/cuddler.template.diagnostics.schema.1.0.0.json"
          },
          {
            "id": "conformance-manifest",
            "title": "Conformance manifest",
            "role": "conformance-manifest",
            "publicationClass": "normative",
            "mediaType": "application/json",
            "url": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/cuddler.template.conformance.manifest.1.0.0.json"
          }
        ]
      },
      {
        "key": "supporting-artifacts",
        "title": "Supporting Artifacts",
        "items": [
          {
            "id": "markdown-example",
            "title": "CommonMark + GFM example",
            "role": "example",
            "publicationClass": "supporting",
            "mediaType": "application/json",
            "url": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/commonmark-gfm-markdig.example.1.0.0.json"
          },
          {
            "id": "release-manifest",
            "title": "Release manifest",
            "role": "release-manifest",
            "publicationClass": "supporting",
            "mediaType": "application/json",
            "url": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/cuddler.template.release.manifest.1.0.0.json"
          }
        ]
      },
      {
        "key": "schema-artifacts",
        "title": "Schema Artifacts",
        "items": [
          {
            "id": "brand-guide-template-schema",
            "title": "Brand Guide template schema",
            "role": "example",
            "publicationClass": "example",
            "mediaType": "application/schema+json",
            "url": "https://www.cuddler.dev/standards/artifact-definitions/brand-guide/1.0.0/template.schema.json"
          },
          {
            "id": "brand-guide-data-schema",
            "title": "Brand Guide data schema",
            "role": "paired-example",
            "publicationClass": "example",
            "mediaType": "application/schema+json",
            "url": "https://www.cuddler.dev/standards/artifact-definitions/brand-guide/1.0.0/data.schema.json"
          },
          {
            "id": "workflow-catalog-template-schema",
            "title": "Workflow Catalog template schema",
            "role": "example",
            "publicationClass": "example",
            "mediaType": "application/schema+json",
            "url": "https://www.cuddler.dev/standards/artifact-definitions/workflow-catalog/1.0.0/template.schema.json"
          },
          {
            "id": "workflow-catalog-data-schema",
            "title": "Workflow Catalog data schema",
            "role": "paired-example",
            "publicationClass": "example",
            "mediaType": "application/schema+json",
            "url": "https://www.cuddler.dev/standards/artifact-definitions/workflow-catalog/1.0.0/data.schema.json"
          }
        ]
      }
    ],
    "sectionSummaries": [
      {
        "key": "overview",
        "title": "Overview",
        "summary": "Defines the Template-governed authoring brief as a single self-contained normative publication for markdown-compliant template JSON, validation, and renderer interoperability."
      },
      {
        "key": "scope",
        "title": "Scope",
        "summary": "Explains the template-document envelope, the markdown AST surface, renderer options, validation boundaries, publication rules, and fixed schema constraints a Template Artifact Definition must express, including explicit metadata values and exact cardinality rules when knowable."
      },
      {
        "key": "implementation",
        "title": "Implementation",
        "summary": "Tells Template Schema authors, validators, and renderers how to draft or enforce Template-governed Artifact Definitions with strict schema rules and without widening the contract to absorb example drift."
      },
      {
        "key": "validation",
        "title": "Validation",
        "summary": "Requires template-document schema validation plus deterministic markdown semantic checks before rendering, with stable diagnostics for unsupported or malformed template content."
      },
      {
        "key": "artifacts",
        "title": "Artifacts",
        "summary": "Identifies the supporting schemas, manifests, examples, and worked Artifact Definition families that guide drafting without replacing the integrated specification."
      },
      {
        "key": "security",
        "title": "Security",
        "summary": "Includes sanitization, URI handling, privacy, and safety expectations needed for interoperable rendering without requiring separate external prose pages."
      },
      {
        "key": "change-management",
        "title": "Change Management",
        "summary": "Captures the stable Template v1.0.0 boundaries, the release artifact inventory, and the rule that later authoring conveniences must still emit valid markdown AST output."
      },
      {
        "key": "references",
        "title": "References",
        "summary": "Provides the CommonMark, GFM, Markdig, RFC, and JSON Schema references required to interpret the template contract and its dependencies."
      }
    ],
    "references": {
      "normative": [
        {
          "title": "BCP 14 / RFC 2119 / RFC 8174",
          "locator": "Requirement language"
        },
        {
          "title": "JSON Schema Draft 2020-12 Core",
          "locator": "Core vocabulary"
        },
        {
          "title": "JSON Schema Draft 2020-12 Validation",
          "locator": "Validation vocabulary"
        },
        {
          "title": "RFC 3339",
          "locator": "Date and time on the Internet"
        },
        {
          "title": "RFC 3986",
          "locator": "URI Generic Syntax"
        },
        {
          "title": "RFC 7763",
          "locator": "text/markdown media type"
        },
        {
          "title": "CommonMark Specification",
          "locator": "Core markdown semantics"
        },
        {
          "title": "GitHub Flavored Markdown Spec",
          "locator": "GFM extensions"
        },
        {
          "title": "Markdig",
          "locator": "Normative renderer target for the interoperable surface"
        }
      ],
      "informative": [
        {
          "title": "IANA Media Type Registry",
          "locator": "Content-type registration reference"
        }
      ]
    }
  }
}