Canonical standard text

The section below is the full normative publication rendered directly from the canonical repository source. Use it for exact wording, implementation details, and citation.

Version 1.0.0

Status

This document is the canonical public contract for the Cuddler Template Document domain in release 1.0.0. Artifact Definitions classified into this domain MUST conform to both this Document Role and the shared Artifact Specification.

This versioned Document Role is intentionally self-contained. It includes the complete normative contract for release 1.0.0, and linked schemas, manifests, examples, or tests are supplementary rather than required reading.

1. Notational conventions

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.

2. Purpose and scope

Cuddler Template v1.0.0 standardizes a markdown-compliant JSON template document that targets CommonMark, GitHub Flavored Markdown (GFM), and Markdig.

A conforming template flow keeps roles separate:

1. data.schema.json validates the structured source facts,
2. template.schema.json validates the authored template document JSON,
3. the template document JSON is rendered only after that template JSON passes validation.

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.

In scope (v1.0.0):

• the canonical template-document envelope
• Template Schema authoring rules for markdown-compliant template JSON
• CommonMark plus GFM block and inline structures aligned to Markdig
• renderer option constraints
• table and reference-style semantic validation
• diagnostics, security, accessibility, and release artifacts

Out of scope (v1.0.0):

• model binding
• template expressions
• loops and conditionals
• component registries
• editor UX
• transport protocols

3. Key terms

• Template document: a concrete JSON document that models the final reader-visible template structure as markdown AST data.
• Template Schema: a JSON Schema that validates one template-document family and constrains its headings, paragraphs, tables, lists, quotations, images, and related markdown content.
• Report: the final emitted output artifact produced from a validated template document, for example HTML or PDF.
• Markdown AST: the semantic JSON structure that represents CommonMark plus GFM content rather than raw markdown source text.
• Renderer options: authored preferences such as renderer and flavor that describe the intended markdown interpretation but do not change document semantics.

4. Conformance classes

4.1 Conforming template document

A conforming template document MUST:

• match the canonical envelope defined in Section 6
• pass JSON Schema validation against its Template Schema
• stay within the CommonMark plus GFM markdown surface defined by this release
• pass the semantic validation rules in Section 8
• remain aligned with schema-level metadata and output declarations

4.2 Conforming Template Schema

A conforming Template Schema MUST:

• use JSON Schema Draft 2020-12
• follow the published Template authoring-profile schema
• anchor the instance contract to the published commonmark-gfm-markdig.schema.1.0.0.json schema or the equivalent MarkdownDocument definition in the base definitions bundle
• satisfy the published lint rules
• author renderer-visible guidance for every instance-visible schema node in for-ai Alpaca arrays
• remain aligned with exactly one Data Schema family and one output family

4.3 Conforming renderer

A conforming renderer MUST:

• validate the template document against the Template Schema before rendering
• run semantic checks after schema validation succeeds
• honor the declared markdown flavor and renderer constraints
• reject unsupported content types or invalid template documents with deterministic diagnostics
• refuse silent fallback to a different output target when the declared primary target is unsupported

5. Normative dependencies

Implementations MUST support JSON Schema Draft 2020-12, including contains, minContains, unevaluatedProperties, and prefixItems when an authored Template Schema uses them.

Implementations MUST enforce required format assertions such as uri, uri-reference, and date-time either through JSON Schema format assertion support or by running equivalent deterministic semantic checks after schema validation.

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.

6. Canonical template-document envelope

A Cuddler template document MUST be a JSON object with exactly these top-level properties:

• $schema (required)
• type (required and equal to document)
• children (required)
• options (optional but standardized)

No other top-level properties are required by the interoperable surface, although a Template Schema MAY allow stricter family-specific rules.

$schema MUST equal the validating Template Schema $id exactly.

children 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.

7. Markdown structure model

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.

The interoperable block surface includes:

• paragraph
• heading
• thematicBreak
• codeBlock
• rawHtmlBlock
• linkReferenceDefinition
• table
• blockQuote
• list

The interoperable inline surface includes:

• text
• softBreak
• hardBreak
• codeSpan
• emphasis
• strong
• strikethrough
• link
• image
• autolink
• rawHtmlInline

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.

8. Semantic validation and diagnostics

Schema validation alone is not sufficient. Conforming validators MUST also run deterministic semantic checks after schema success.

The minimum public semantic checks for v1.0.0 are:

• align.length == header.cells.length for every table
• every table body row width equals the header width
• reference-style links and images resolve to a matching linkReferenceDefinition

Diagnostics emitted by validators and renderers MUST conform to the published diagnostics schema for this release.

9. Security, privacy, and safety considerations

Implementations MUST treat template JSON, examples, raw HTML nodes, linked destinations, and schema-node for-ai guidance as untrusted input.

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.

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.

10. Authoring profile summary

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.

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.

11. Published v1.0.0 artifacts

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.

These supporting artifacts aid authoring, validation, and interoperability testing. They do not add normative requirements beyond the ones stated in this document.