Documents

A Typograph document (also called a template when saved in the file service) is the versioned JSON structure that the editor reads, the validator checks, and the publisher renders. This page covers the top-level shape; the remaining pages in this section zoom in on pages, elements, and swatches.

Top-Level Shape

{
  "version": "1.0.0",
  "type": "template",
  "metaData": { ... },
  "fontData": [ ... ],
  "swatches": [ ... ],
  "pages": [ ... ],
  "activePageIndex": 0
}

Property	Type	Required	Description
version	string	yes	Schema version — must match the Typograph schema, currently 1.0.0
type	string	yes	Either template (a reusable design) or clip (a fragment)
metaData	object	yes	Title, author, timestamps, and other descriptive fields
fontData	array	yes	Fonts referenced by the document's text elements
swatches	array of Swatch	yes	Color swatches used for fills, strokes, shadows, gradients. At least 4 required.
pages	array of Page	yes	Pages in the document; see Pages
activePageIndex	number	no	Page to open first in the editor
brandColors	object	deprecated	Legacy alias for swatches — new documents should use swatches

Use the Document Service (POST /v1/document/validate) to confirm a payload conforms to the schema before sending it to the publisher.

Type: template vs clip

• template — a complete, renderable document. This is what the editor opens, what the publisher turns into PDFs/images, and what the file service stores under /v1/file/templates.
• clip — a reusable fragment (e.g. a logo block, a call-out) that can be dropped into a template.

Swatch-Based Color System

Typograph does not embed raw colors in individual elements. Instead, the document defines a palette of swatches (at the document level), and elements refer to them by UUID for fills, strokes, shadows, and gradients. This lets a color change in one place propagate throughout the document. See Styles for the swatch model.

Font Data

fontData is the authoritative list of fonts the document uses. Each entry names a font and references the font asset. The editor fetches font files through the file service's font presigned-URL endpoints — see File Service.

Schema Versioning and Upgrade

Schema versions are semver-tagged and incompatible across major versions. The Document Service exposes:

• POST /v1/document/validate — check whether a payload conforms to the current schema
• POST /v1/document/upgrade — migrate a payload from an older schema to the current version

Always validate a document before sending it to the publisher — the publisher rejects invalid documents outright.