Design Format

The Design Format is the JSON shape every Polotno design uses — the same object store.toJSON() produces and store.loadJSON() accepts. It's a flat, readable document: top-level width / height / dpi, a fonts array, and a pages array whose children are typed elements (text, image, svg, line, figure, gif, video, table, group).

You can work with this format without running the editor. The @polotno/schema package gives you TypeScript types, default values, validation, and a language-neutral JSON Schema — everything you need to generate, validate, or transform designs on a server, in an edge function, or inside an LLM pipeline.

npm install @polotno/schema

What it's for

• Validate a design before saving it, or when accepting it over the wire.
• Normalize partial or hand-authored JSON into a complete, canonical document (defaults filled in).
• Constrain LLM output — feed the JSON Schema to a model as a structured-output schema, then validate what comes back.

Validate

import { validateDesign } from '@polotno/schema';

// json from store.toJSON(), a converter, or an LLM
const result = validateDesign(json, { mode: 'canonical' });
if (!result.valid) {
  console.error(result.errors); // [{ path, message }, …]
}

Use mode: 'partial' to allow missing defaults, or mode: 'canonical' to reject unknown keys. assertValidDesign(json) throws instead of returning a result. The exported designSchemaLenient / designSchemaCanonical implement the Standard Schema interface (zod, Valibot, Effect Schema, …).

Normalize (fill defaults)

import { normalizeDesign } from '@polotno/schema';

const complete = normalizeDesign(partial); // fills defaults, strips unknown keys
store.loadJSON(complete);

Normalize is idempotent for current-format input. It does not migrate old schemaVersion documents, and it leaves render-derived values (such as text auto-height) for the editor to compute.

Types

import type { Design } from '@polotno/schema';

const design: Design = store.toJSON();

Also exported: Page, Element, TextElement, and every other type in the format.

JSON Schema & LLMs

A language-neutral JSON Schema (draft 2020-12) ships with the package — validate from any language, or hand it to a model as a structured-output schema and validate what comes back before rendering:

import schema from '@polotno/schema/design.schema.json' with { type: 'json' };
import { validateDesign } from '@polotno/schema';

// `schema` as your LLM client's structured-output / response schema
const design = await model.generate({ prompt, jsonSchema: schema });

if (validateDesign(design, { mode: 'partial' }).valid) {
  store.loadJSON(design);
}

Field reference

Every type in the format has a generated reference page with all properties, types, and defaults:

• Design — the root document
• Page and its Element children: Text, Image, SVG, Line, Figure, Gif, Video, Table, Group
• Font and Audio

Browse the full list in the sidebar. For the complete package API, see the @polotno/schema README on npm.