Cuddler Data Specification

Version 1.0.0-draft.7 is the first draft written so an autonomous assistant can author a new data.schema.json and matching data.example.json from the public spec URL without relying on hidden repository context.

Data-first contract

Templates validate document data first. Exporters only run after successful validation.

Intentful schemas

Every instance-visible field must explain meaning, expected content, and generator guidance.

Linked-schema aware

Draft 7 adds explicit schema-link metadata so tools can reason about graphs of related Cuddler document types.

Authoring Workflow

The required authoring sequence is:

Choose the document type, purpose, audience, and exported artifact.
Determine the minimum top-level sections the document must always contain.
Decide whether reusable facts belong in a typed documentModel.
Write a strict data.schema.json using Draft 2020-12 and the canonical envelope.
Add generator-readable description text for every instance-visible property.
If the document links to other Cuddler documents, model the link records explicitly and declare matching schema links.
Generate a data.example.json instance that validates against the schema.

What changed in d7

The public page now explains the authoring workflow directly. The downloadable prompt assets remain available, but they are no longer the only place where the schema-authoring rules are described.

Canonical Envelope

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

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

Draft 7 makes instance $schema required so validators and linked-document tooling can resolve the intended schema deterministically.

Field	Status	Notes
`$schema`	Required	Absolute URI of the validating Document Template schema.
`meta`	Required	Identity and authorship metadata.
`content`	Required	Section tree plus optional typed `documentModel`.
`assets`	Required	Asset library for asset blocks.
`references`	Required	Bibliographic or standards references; may be empty.
`annotations`	Optional	Scalar extension metadata.

d7 Block Model

Block kinds stay fixed in v1, but d7 aligns the canonical names and optional fields with real authoring usage.

Kind	Required fields	Notes
`text`	`kind`, `blockId`, `format`, `text`	Draft 7 uses `text`, not `value`.
`bullets`	`kind`, `blockId`, `items[]`	Optional `style` and `intro` are part of the canonical d7 shape.
`table`	`kind`, `blockId`, `columns[]`, `rows[]`	Table columns use `heading` and `description`.
`asset`	`kind`, `blockId`, `assetId`	References an asset declared in `assets.library[]`.

Schema Metadata And Authoring Profile

A conforming d7 data.schema.json MUST use Draft 2020-12, a versioned immutable $id, strict objects, section variants, and generator-readable descriptions for every instance-visible field.

Every schema MUST include top-level cuddler metadata:

"cuddler": {
  "specVersion": "1.0.0-draft.7",
  "documentTypeId": "<kebab-case>",
  "schemaVersion": "<semver>",
  "output": {
    "primaryContentType": "application/pdf",
    "supportedContentTypes": ["application/pdf"]
  },
  "profile": {
    "id": "<optional-kebab-case>",
    "version": "<optional-semver>",
    "description": "<optional-description>"
  },
  "schemaLinks": [
    {
      "rel": "related",
      "targetSchema": "https://www.cuddler.dev/schemas/other-doc/1.0.0/data.schema.json",
      "targetDocumentTypeId": "other-doc",
      "description": "Why this schema is linked."
    }
  ]
}

Required description rule

Every instance-visible property schema must include a non-empty description that tells a future autonomous assistant what the field means, what belongs there, and how specific the content should be.

Linked Documents And Linked Schemas

Draft 7 formalizes the metadata pattern for related schemas. When a document type links to other generated Cuddler documents, the schema should model those link records explicitly and declare the target schema graph in cuddler.schemaLinks.

Concept	Where it lives	Expectation
Linked document record	Instance data model	Should carry the target document locator plus `schemaUri`; may also carry `schemaPath` for offline or repository-local validation.
Schema link	`cuddler.schemaLinks`	Should carry `rel`, `targetSchema`, and a non-empty explanation of the relationship.
Profile metadata	`cuddler.profile`	Optional family/profile identifier for stricter schema sets layered on top of core d7.

Recommended relation names include related, base, catalog-entry, entrypoint, profile, and dependency.

Authoring Recipe

An autonomous assistant should follow this exact recipe when creating a new schema:

Compute documentTypeId from the human template name using kebab-case normalization.
Choose the minimum viable required top-level section keys.
Decide whether a typed documentModel is necessary for reusable facts.
Write the strict root schema and constrain $schema, meta.documentTypeId, and meta.schemaVersion via const.
Define content.sections.items as a oneOf of Section Variant schemas.
Give every instance-visible property a generator-readable description.
If the document links to other Cuddler documents, model those link objects explicitly and require schemaUri.
Declare matching cuddler.schemaLinks entries.
Generate a matching data.example.json.
Run schema validation and semantic checks.

Starter pattern

Use the base defs library for canonical envelope, blocks, assets, references, and typed primitives, then narrow the document type with section variants and document-type-specific fields. The d7 example schema below demonstrates the expected pattern.

Schema Lint Checklist

The schema uses Draft 2020-12 and a versioned immutable $id.
The schema includes cuddler.specVersion = "1.0.0-draft.7".
The root instance requires $schema and matches the canonical envelope.
Every instance-visible object is strict and composition preserves strictness.
Every instance-visible property has a non-empty, generator-readable description.
content.sections.items is a oneOf union of section variants.
Required top-level sections are enforced via contains + minContains.
Text blocks use text, not value.
Table columns use heading and description.
Linked-document records use schemaUri when they point at generated Cuddler documents.
Every declared cuddler.schemaLinks[].targetSchema resolves in the validation environment.

Draft 7 Artifacts

The source draft folder specification/v1/d7/ includes these downloadable artifacts:

cuddler.spec.1.0.0-draft.7-document-templates.md (normative specification text)
cuddler.base.defs.schema.1.0.0-draft.7-document-templates.json (base $defs library)
data.schema.prompt.1.0.0-draft.7-document-templates.txt (copyable schema-author prompt)
data.example.prompt.1.0.0-draft.7-document-templates.txt (copyable example-instance prompt)
example.simple-memo.data.schema.draft7.json (worked example schema)
example.simple-memo.data.example.draft7.json (worked example instance)

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