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 Report 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, cookbooks, examples, tests, or changelog files 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 is a paired-schema document standard for humans, AI assistants, validators, renderers, and exporters.

A conforming Cuddler report flow uses four aligned artifacts:

1. data.schema.json authored as a Data Schema
2. data.example.json authored as example document data
3. template.schema.json authored as a Template Schema
4. template.example.json authored as an example template file

A report engine validates the data instance against a Data Schema, validates the template file against a Template Schema, then combines the two validated inputs to emit a rendered report artifact such as PDF, HTML, or DOCX.

This strict-shape-plus-documented-render-intent requirement is normative throughout this Document Role. Structural constraints without interoperable renderer semantics are insufficient for Cuddler conformance.

In scope (v1.0.0):

• canonical template-file shape
• Template Schema authoring rules
• compatibility metadata
• binding and repeat semantics
• renderer processing order
• component behavior for the closed v1.0.0 component library
• validation, diagnostics, security, accessibility, and release artifacts

Out of scope (v1.0.0):

• product-specific editor UX
• typography engines
• CSS frameworks
• pagination internals beyond normative page/section semantics
• transport protocols
• proprietary extension registries

3. Key terms

• Data Schema: a JSON Schema that validates document data JSON.
• Template Schema: a JSON Schema that validates template JSON for one document type and schema version.
• Rendered Report: the final emitted output artifact produced from validated data plus a validated template.
• Template file: a concrete JSON document validated against a Template Schema.
• Binding path: an exact RFC 6901 JSON Pointer evaluated against validated data using the binding rules in Section 9.
• Node: one authored component declaration inside a template file.
• Render intent: the documented purpose of a template field, including what content it should represent and how a renderer should interpret it.
• Template asset: an auxiliary resource referenced by a template file, such as an image or stylesheet.
• Local key: a stable kebab-case identifier whose uniqueness is scoped to one template file.
• Global identifier: a UUID or canonical URI used when a value must remain globally unique outside one template file.

4. Paired-schema workflow

The Data Schema and Template Schema for a document type MUST share the same documentTypeId and schemaVersion.

A conforming authoring workflow is:

1. Author data.schema.json.
2. Author data.example.json that validates against it.
3. Author template.schema.json.
4. Author template.example.json that validates against it.
5. Validate the data file and template file independently.
6. Run semantic validation on both contracts.
7. Render only after both validations succeed and the paired metadata remains aligned.

Artifact Definitions in this domain validate template JSON only. They MUST NOT redefine, narrow, or override data-validation rules already owned by the paired Data Schema.

5. Conformance classes

5.1 Conforming template file

A conforming Cuddler template file MUST:

• match the canonical envelope defined in Section 7
• pass JSON Schema validation against its Template Schema
• use only the v1.0.0 component library defined in Section 11
• keep metadata aligned with the Template Schema and paired Data Schema
• pass the semantic validation rules in Section 14

5.2 Conforming Template Schema

A conforming Template Schema MUST:

• use JSON Schema Draft 2020-12
• follow the authoring-profile requirements in Section 17
• validate against the published authoring-profile meta-schema
• satisfy the published lint rules
• document renderer-visible behavior for every instance-visible field
• remain explicitly aligned with exactly one Data Schema family

5.3 Conforming renderer

A conforming renderer MUST:

• validate data JSON against the Data Schema before rendering
• validate template JSON against the Template Schema before rendering
• run semantic checks after both schema validations succeed
• honor the binding, repeat, visibility, graph, and component semantics in this Document Role
• reject unsupported components, invalid bindings, and unresolved required inputs with deterministic diagnostics
• refuse silent fallback to a different output target when the declared primary target is unsupported

5.4 Conforming validator

A conforming validator MUST:

• support JSON Schema Draft 2020-12
• enforce the required format assertions from Section 6
• run the semantic checks in Section 14 after schema success
• emit diagnostics that match the structure defined by the published diagnostics schema

6. Normative dependencies

Implementations MUST support JSON Schema Draft 2020-12, including:

• contains
• minContains
• unevaluatedProperties

Implementations MUST enforce date-time, email, uri, uri-reference, and uuid as assertions. A conforming implementation MAY do this by enabling the JSON Schema format-assertion vocabulary or by running equivalent deterministic semantic validation rules after schema validation. When a validator does not enable the format-assertion vocabulary directly, it MUST document the equivalent application-level checks it applies.

Binding paths use RFC 6901 JSON Pointer syntax.

Language tags MUST follow the simplified Cuddler language-tag profile published in the base definitions library. Implementations MAY perform fuller semantic checks against BCP 47 / RFC 5646.

Content types and asset media types SHOULD use registered IANA media types following RFC 6838.

7. Canonical template file envelope

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

• $schema (required)
• meta (required)
• template (required)
• assets (required)

No other top-level properties are allowed.

7.1 $schema

$schema MUST equal the Template Schema $id exactly.

7.2 meta

meta MUST be a strict object.

Required fields:

• schemaVersion
• documentTypeId
• templateId
• templateVersion
• title
• primaryContentType
• dataSchemaUri
• createdAt
• authors[]

Optional fields:

• supportedContentTypes
• updatedAt
• summary
• language
• intendedAudience
• usageGuidance
• tags[]
• textDirection

language MUST follow the simplified Cuddler language-tag profile published in the base definitions library.

7.3 template

template MUST be a strict object with:

• entryNodeId
• nodes[]

entryNodeId identifies the node where rendering begins.

nodes[] is the authored node list that defines the whole render graph.

7.4 assets

assets MUST be a strict object with library[].

assets.library[] MAY be empty.

8. Identifiers and metadata precedence

• Global identifiers MUST be UUIDs or canonical URIs when global uniqueness is required.
• Local keys MUST be stable kebab-case identifiers when uniqueness is scoped to one template file.

templateId, entryNodeId, and node.id are local keys, not global identifiers.

Schema-level metadata in template.schema.json is authoritative for:

• supported document family (documentTypeId)
• supported schema version (schemaVersion)
• aligned Data Schema URI (dataSchema.uri)
• maximum output capability set (output.primaryContentType, output.supportedContentTypes)

Instance-level metadata in template.example.json and production template files MUST remain consistent with schema-level metadata:

• meta.documentTypeId MUST equal the schema-level documentTypeId
• meta.schemaVersion MUST equal the schema-level schemaVersion
• meta.dataSchemaUri MUST equal the schema-level dataSchema.uri
• meta.primaryContentType MUST be one of the schema-level supported content types
• meta.supportedContentTypes, when present, MUST be a subset of the schema-level supported content types and MUST include meta.primaryContentType

8.1 Output target selection

Output target selection is deterministic in v1.0.0:

• if a caller does not request a specific output target, the renderer MUST use meta.primaryContentType
• if a caller requests a target explicitly, that target MUST match one declared content type exactly
• if the requested target is not declared, rendering MUST fail
• silent fallback to another declared or undeclared target is forbidden
• multi-output templates MUST use only node semantics that remain interoperable across every declared content type

9. Binding model

9.1 Syntax

A Cuddler binding path is an exact RFC 6901 JSON Pointer.

The following rules are normative:

• the empty pointer is not allowed in v1.0.0
• every path MUST begin with /
• array indices are allowed only as RFC 6901 path tokens
• relative paths are not part of v1.0.0

Template authors SHOULD avoid array-position bindings unless the paired Data Schema fixes the relevant order explicitly. The published linter rules define positional bindings against unordered schema shapes as a warning or error depending on context.

9.2 Scope

Path-evaluated constructs MAY declare scope with one of:

• document meaning evaluate from the validated data document root
• repeat-item meaning evaluate from the current repeated item

If scope is omitted, the default is document.

9.3 source

source.kind MAY be:

• static
• path

static supplies deterministic authored JSON values.

path reads from validated data only. It MUST NOT execute code, invoke helpers, or redefine validation rules.

If a required source.path cannot be resolved at render time, the renderer MUST fail the affected node with a diagnostic using E_TEMPLATE_MISSING_FIELD or another published rule-specific diagnostic code.

9.4 repeat

repeat.path MUST resolve to an array.

If repeat.path resolves to a non-array value, the renderer MUST fail validation before normal output generation.

Nested repeats are allowed only through explicit nested nodes. Repeat expansion does not change RFC 6901 syntax; it changes only the evaluation root when a child binding declares scope: "repeat-item".

9.5 visibleWhen

visibleWhen is equality-only in v1.0.0.

A conforming visibility rule compares one scalar value resolved from visibleWhen.path to one scalar visibleWhen.equals value.

Boolean composition, greater-than/less-than operators, and script expressions are not part of interoperable v1.0.0.

If visibleWhen.path is missing or resolves to a non-scalar value, the condition evaluates to false and the node does not render.

10. Template graph model

The template graph is a rooted ordered tree encoded as a flat node list plus child references.

The following rules are normative:

• every node.id MUST be unique
• template.entryNodeId MUST resolve to exactly one node
• child order is significant and MUST be preserved
• a node MAY have at most one parent
• cycles are forbidden
• duplicate child references within one parent are forbidden
• orphan nodes are forbidden
• disconnected subgraphs are forbidden

Validators MUST check graph integrity as part of semantic validation.

11. Closed v1.0.0 component library

The interoperable v1.0.0 component library is closed to the following component types:

• page
• section
• heading
• paragraph
• list
• table
• image

All other component names are outside the interoperable v1.0.0 surface and MUST NOT appear in conforming templates.

11.1 page

11.2 section

11.3 heading

11.4 paragraph

11.5 list

11.6 table

11.7 image

12. Assets, resolution, and packaging

Template asset objects MUST include:

• id
• kind
• name
• uri
• mimeType

The v1.0.0 asset-kind set is closed to:

• image
• stylesheet
• other

Assets of kind image MUST also include altText.

Template asset URIs are absolute in the v1.0.0 interoperable core.

Implementations:

• MAY satisfy remote asset resolution from a local cache or package registry
• SHOULD support offline validation when required assets are already cached
• MUST fail clearly when a required asset cannot be resolved inside the renderer trust boundary
• MUST NOT silently dereference local-file or loopback targets unless an explicit trusted runtime policy allows it

13. Processing model

Conforming implementations MUST process a render request in this order:

1. validate the data instance against the Data Schema
2. validate the template file against the Template Schema
3. run semantic validation on the template graph, bindings, assets, and compatibility metadata
4. evaluate bindings
5. expand repeats
6. evaluate visibility
7. build an abstract render tree
8. map the abstract render tree to the selected output target

Informative pseudo-code:

validate(data, dataSchema)
validate(template, templateSchema)
lint(template, templateSchema, dataSchema)
root = buildNodeMap(template.nodes, template.entryNodeId)
expanded = expandRepeats(root, data)
visible = filterVisibility(expanded, data)
bound = bindNodeValues(visible, data)
rendered = emitTarget(bound, template.meta.primaryContentType)

14. Validation and diagnostics

Validators and renderers MUST run these semantic checks after schema validation succeeds:

1. node-id uniqueness
2. entrypoint existence
3. child reference existence
4. graph reachability
5. cycle rejection
6. duplicate child reference rejection
7. single-parent enforcement
8. asset existence for referenced template assets
9. compatibility consistency across schema-level and instance-level metadata
10. supported-content-type subset enforcement
11. binding-path determinism checks
12. image-asset altText enforcement
13. component-library conformance
14. equality-only visibleWhen enforcement

Diagnostic objects MUST expose:

• code
• message
• path
• severity
• expected
• actual
• hint

The published diagnostics schema may additionally include ruleId, instancePath, schemaPath, templatePath, and dataPath.

Warnings about sanitized output or unsupported-but-ignored optional behavior MUST be surfaced separately from fatal validation errors.

The published conformance suite includes both positive and negative cases with expected diagnostics.

15. Security considerations

Implementations MUST treat Template Artifact Definitions, template files, and remote assets as untrusted unless an explicit trusted runtime policy says otherwise.

At minimum, conforming implementations MUST document or mitigate:

• SSRF and local-file access risks from asset or schema fetching
• oversized assets and denial-of-service risks
• HTML, Markdown, PDF, and DOCX injection risks
• malicious template graphs intended to trigger recursion or pathological repeat expansion
• unsupported output fallback behavior
• prompt-injection contamination when AI systems ingest remote descriptions, examples, or asset metadata

Renderers MUST fail closed rather than silently downgrading to a weaker or different output target.

16. Privacy considerations

Implementations and AI-assisted authoring systems SHOULD minimize the collection, retention, and propagation of personal or sensitive information carried by:

• template metadata such as author records and usage guidance
• asset metadata including accessible descriptions
• diagnostics, traces, and validator logs
• prompts, examples, and repair loops that quote document content

Diagnostics, traces, and cached artifacts SHOULD expose only the data needed to explain a failure or reproduce a conforming render path.

17. Accessibility and internationalization

Template authors and renderer implementations SHOULD preserve:

• semantic heading levels
• table header semantics and reading order
• alternative text for image assets
• authored list order
• document language tags using the simplified Cuddler language-tag profile

textDirection MAY be declared in metadata for ltr, rtl, or auto. Bidirectional layout beyond metadata declaration is reserved for a later version.

18. Template Schema authoring profile (template.schema.json)

A conforming v1.0.0 Template Schema MUST:

18.1 Use Draft 2020-12 and a versioned $id

• $schema MUST be https://json-schema.org/draft/2020-12/schema
• $id MUST be https://www.cuddler.dev/standards/artifact-definitions/<documentTypeId>/<schemaVersion>/template.schema.json

18.2 Declare canonical cuddler metadata

The schema MUST include:

"cuddler": {
  "specVersion": "1.0.0",
  "documentTypeId": "<kebab-case>",
  "schemaVersion": "<semver>",
  "dataSchema": {
    "uri": "https://www.cuddler.dev/standards/artifact-definitions/<documentTypeId>/<schemaVersion>/data.schema.json"
  },
  "output": {
    "primaryContentType": "application/pdf",
    "supportedContentTypes": ["application/pdf", "text/html"]
  }
}

18.3 Enforce strictness

• every instance-visible authored object MUST set additionalProperties: false
• unevaluatedProperties: false MUST be used when composition would otherwise reopen authored objects
• document-type schemas MUST replace the generic Node.props placeholder with constrained component-specific prop schemas

18.4 Enforce the canonical envelope

• template instances MUST require $schema, meta, template, and assets
• template-instance $schema MUST be constrained to const equal to the Template Schema $id
• meta.documentTypeId MUST be constrained via const
• meta.schemaVersion MUST be constrained via const
• meta.dataSchemaUri MUST be constrained via const
• meta.primaryContentType and meta.supportedContentTypes MUST use the canonical names from this specification

18.5 Document instance-visible intent

Every instance-visible property schema MUST include a non-empty description either directly or through its $ref target.

Each description MUST explain:

• what the field means in this template type
• what authored content belongs there
• what rendering role it serves
• what validated data it may bind to or reference
• any exclusions a generator or renderer should follow

18.6 Publish machine-readable conformance surfaces

The release package for v1.0.0 includes:

• an authoring-profile meta-schema
• a lint rules document with stable rule IDs
• a diagnostics schema
• a component registry
• a conformance suite manifest and expected outputs
• a binding cookbook
• a release manifest with hashes

Template Schema authors SHOULD use the machine-readable validation artifacts together with this document during implementation and verification, but the full normative contract is defined here rather than in linked companion files.

19. Extension, versioning, and deprecation policy

The v1.0.0 component library is closed.

Extensions are governed as follows:

• unregistered extensions are not conforming in interoperable v1.0.0
• experimental fields, when used outside conformance claims, SHOULD use an x- prefix
• backward-compatible clarifications MAY ship as 1.0.x errata when they do not expand the required interoperability surface
• new component types, new condition operators, and relative binding syntax require a later minor or major specification revision
• deprecated features MUST remain documented for one full minor release before removal from conformance guidance

Errata and release-package updates SHOULD publish stable artifact URIs plus hashes.

20. Published v1.0.0 artifacts

The release materials for report authoring, validation, and implementation include:

• Normative artifacts
• document-role-specification.json
• cuddler.report.base.defs.schema.1.0.0.json
• cuddler.report.authoring-profile.schema.1.0.0.json
• cuddler.report.lint.rules.1.0.0.json
• cuddler.report.diagnostics.schema.1.0.0.json
• cuddler.report.component-registry.1.0.0.json
• cuddler.report.conformance.manifest.1.0.0.json
• cuddler.report.release.manifest.1.0.0.json
• Informative artifacts
• integrated binding, processing, and release-history sections in document-role-specification.json
• worked Template Schema and template-example families such as brand-guide

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

21. Citation and archival guidance

For normative behavior, this document is the complete source of truth for release 1.0.0. The versioned repository source under data/document-role-specifications/report-document-role-specification-1.0.0.json and the published versioned HTTPS artifacts preserve the accompanying machine-readable release materials.

The release manifest provides immutable SHA-256 hashes for the published artifact set and is the canonical machine-readable artifact index for this release. It does not introduce additional normative requirements beyond this document.

22. References

22.1 Normative references

• BCP 14 / RFC 2119 / RFC 8174
• RFC 3339, date and time on the Internet
• RFC 3986, URI syntax
• RFC 6901, JSON Pointer
• RFC 5646 / BCP 47, language tags
• RFC 6838, media type registration procedures
• Semantic Versioning 2.0.0
• JSON Schema Draft 2020-12 core and validation specifications

22.2 Informative references

• IANA media type registry
• OASIS keyword guidance for specifications

Integrated Supporting Material

The following sections are part of the canonical self-contained Document Role document for this release. They remain supplementary in publication role, but they are integrated here so the versioned specification can be implemented without opening any additional prose documents.

Cuddler Report Binding Cookbook

This section is informative guidance for authors and tool builders working against Report Document Role v1.0.0.

Canonical patterns

1. Bind to stable document-model facts

Preferred:

{
  "kind": "path",
  "path": "/content/documentModel/summaryText"
}

Reason:

• the Data Schema can promise the field exists
• templates do not depend on section or block array positions
• validators can explain failures precisely

2. Bind to arrays only when the array is the intended value

Preferred list binding:

{
  "kind": "path",
  "path": "/content/documentModel/nextSteps"
}

The bound value should already be the list item array, not a section container that the renderer still has to reinterpret.

3. Use repeat-item scope explicitly

Preferred repeated node pattern:

{
  "repeat": {
    "path": "/content/documentModel/risks"
  }
}

Child binding inside the repeated node:

{
  "kind": "path",
  "scope": "repeat-item",
  "path": "/label"
}

4. Use equality-only visibility

Preferred:

{
  "path": "/content/documentModel/decisionRequested",
  "equals": true
}

Do not encode boolean expression trees in visibleWhen for v1.0.0.

Anti-patterns

1. Fragile positional section binding

Avoid:

{
  "kind": "path",
  "path": "/content/sections/1/blocks/2"
}

This is only safe when the paired Data Schema fixes both the section order and the block order. If the schema uses contains, optional blocks, or mixed block variants, use documentModel instead.

2. Optional-position list binding

Avoid:

{
  "kind": "path",
  "path": "/content/sections/2/blocks/0/items"
}

If introductory text is optional, the bullets block is no longer guaranteed to be at index 0.

Failure cases validators should flag

• positional array indices against non-fixed schema shapes
• repeat paths that resolve to non-arrays
• source paths that point to missing required values
• image nodes that resolve without accessible alternative text
• metadata content-type names that use legacy vocabulary

Cuddler Report Processing Model

This appendix is informative but written to be directly usable by implementers and AI assistants.

Processing order

1. Load the paired Data Schema and Template Schema.
2. Validate the data instance against the Data Schema.
3. Validate the template file against the Template Schema.
4. Run semantic checks: - metadata alignment - graph integrity - supported component set - asset integrity - binding determinism
5. Build the node map from template.nodes.
6. Expand repeated nodes in authored order.
7. Evaluate visibleWhen equality checks.
8. Resolve source values.
9. Build an abstract render tree.
10. Emit the selected target format.

Pseudo-code

function renderReport(data, dataSchema, template, templateSchema):
  validateSchema(data, dataSchema)
  validateSchema(template, templateSchema)
  diagnostics = lintTemplate(template, templateSchema, dataSchema)
  if diagnostics has errors:
    return fail(diagnostics)

  nodeMap = indexNodes(template.template.nodes)
  root = assertEntrypoint(nodeMap, template.template.entryNodeId)
  expandedRoot = expandRepeats(root, data)
  visibleRoot = applyVisibility(expandedRoot, data)
  boundRoot = resolveSources(visibleRoot, data, template.assets)
  abstractTree = buildRenderTree(boundRoot)
  return emit(template.meta.primaryContentType, abstractTree)

Notes

• Data validation always happens before template validation.
• Template validation always happens before rendering.
• Repeat expansion changes evaluation context, not path syntax.
• Renderers should fail closed on unsupported content types or unresolved required inputs.

Cuddler Report Changelog

Version 1.0.0

2026-03-21

• normalized the canonical output metadata names to primaryContentType and supportedContentTypes
• reduced the interoperable v1.0.0 component library to page, section, heading, paragraph, list, table, and image
• removed template-file fragments from the v1.0.0 interoperable surface
• formalized the node model as a rooted ordered tree with no cycles, no orphans, and exactly one parent per non-root node
• tightened binding semantics to exact RFC 6901 JSON Pointers with explicit document and repeat-item scopes
• required template-file and document-instance $schema to equal the validating schema $id
• simplified the shared asset-kind vocabulary to image, stylesheet, and other
• published a machine-readable component registry and expanded diagnostics metadata for tool builders
• classified worked examples as informative publication artifacts