Cuddler Data Specification

Version 1.0.0-draft.5 defines a data-only document standard. A Cuddler document is JSON that validates against JSON Schema Draft 2020-12 and then passes required semantic checks before any export pipeline treats it as valid.

Data-only scope

Templates, UI layout, styling, pagination, and runtime renderer APIs are out of scope for v1.

Intentful schemas

Document Type schemas MUST define both machine constraints and generator-readable intent.

Deterministic validity

Validators and exporters MUST reject invalid instances and MUST NOT silently fall back.

Conformance Targets

Conforming document instance: matches the canonical envelope, passes JSON Schema validation, and passes semantic checks.
Conforming Document Type schema: follows the v1 authoring profile, including required intent documentation and section intent modeling.
Conforming validator: enforces Draft 2020-12 validation plus semantic rules, and returns deterministic pass/fail results.
Conforming exporter: validates input first and follows no-silent-fallback behavior when validation fails.

Canonical Envelope and Identity

A conforming document instance MUST be a strict top-level object with only these properties:

{
  "$schema": "optional absolute URI",
  "meta": {},
  "content": {},
  "assets": {},
  "references": [],
  "annotations": []
}

Identity semantics are strict:

IDs are UUID strings (RFC 4122): for meta.documentId, block.blockId, asset IDs, and reference IDs.
Keys are kebab-case stable identifiers: for meta.documentTypeId, section.key, and table column keys.
Kebab-case normalization MUST follow the six-step algorithm in Section 6.2 and match ^[a-z][a-z0-9-]{2,62}$.

Document Structures

Structure	Requirements	Notes
`meta`	Strict object with required identity/version/timestamps/authorship fields.	`schemaVersion` and `documentTypeId` MUST be constrained via `const` in Document Type schemas.
`content`	Strict object with required `sections[]`; optional typed `documentModel`.	If `documentModel` exists, it MUST be strict and MUST NOT be an unconstrained dictionary.
`sections[]`	Each section requires `key`, `heading`, `blocks[]`; optional `subsections[]`.	Top-level required section keys MUST be enforced using `contains` + `minContains`.
`blocks[]`	Each block requires `kind` and `blockId` (UUID).	v1 kinds are fixed: `text`, `bullets`, `table`, `asset`.
`assets`	Strict object with `library[]` of typed Asset objects.	Visual assets MUST include `altText`.
`references`	Array of reference objects with required `id`, `title`, `locator`.	Optional `kind` and `notes`.
`annotations`	Optional integration metadata array.	Values are scalar only; namespaced keys are recommended.

Validation and Failure Rules

Validation is two-phase and normative:

Run JSON Schema validation first (Draft 2020-12, including contains, minContains, and unevaluatedProperties behavior where composition is used).
Treat date-time, email, uri, and uri-reference as assertions, not informational annotations.
Only after schema success, run required semantic checks.

Required semantic checks:

Asset integrity: every asset block assetId exists in assets.library[].id.
Identifier uniqueness: asset IDs, reference IDs, and all blockId values are unique (including nested subsections).
Section-key uniqueness within each sibling sections[] array.
Table coherence: each row length equals columns length.
Timestamp consistency: meta.updatedAt (if present) must be greater than or equal to meta.createdAt.

If any schema or semantic rule fails, validators MUST return failure and exporters MUST NOT emit normal output artifacts.

Document Type Schema Authoring Profile

Use Draft 2020-12 and an immutable versioned schema $id: https://www.cuddler.dev/schemas/<documentTypeId>/<schemaVersion>/data.schema.json.
Enforce strictness on all instance-visible objects with additionalProperties: false and preserve strictness through composition.
Enforce canonical envelope shape and const constraints for meta.documentTypeId and meta.schemaVersion.
Require non-empty generator-readable description values for all instance-visible properties (directly or via $ref target).
Model section intent using a oneOf union of section variants, each with a key const, non-empty title/description, and optional block restrictions.

Security Considerations

Exporters MUST treat all text as untrusted input.
When rendering markdown text blocks, exporters MUST sanitize output and disable raw HTML by default.
Exporters SHOULD NOT fetch remote asset URIs by default; if enabled, they MUST apply scheme and host allowlists.
Exporters MUST NOT execute active content from document fields (scripts, event handlers, iframes, or similar content).

Draft 5 Artifacts

The source draft folder specification/v1/d5/ includes:

cuddler.spec.1.0.0-draft.5.md (normative specification text)
cuddler.base.defs.schema.1.0.0-draft.5.json (base $defs library)
data.schema.prompt.1.0.0-draft.5.txt and data.example.prompt.1.0.0-draft.5.txt (prompt assets)
example.simple-memo.data.schema.draft5.json and example.simple-memo.data.example.draft5.json (example schema + instance)

Base definitions URI for this draft: https://www.cuddler.dev/spec/1.0.0-draft.5/cuddler.base.defs.schema.json.