@polotno/schema

@polotno/schema

TypeScript types, default values, validation, and a JSON Schema for the Polotno design JSON format — the document shape used across Polotno and its import/export packages.

Use it to validate and normalize design JSON anywhere, without running the editor.

npm install @polotno/schema

What it's for

• Validate a design — before saving it, or when accepting it over the wire.
• Fill in defaults so partial JSON becomes a complete, canonical document.
• Check converter output. The import packages emit design JSON with defaults omitted; this validates and completes it. See @polotno/pdf-import, @polotno/svg-import, @polotno/psd-import.

Validate

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

validateDesign(json, { mode: 'partial' });   // lenient — defaults may be missing
validateDesign(json, { mode: 'canonical' });  // strict — rejects unknown keys
// → { valid: boolean, errors: { path: string, message: string }[] }

assertValidDesign(json); // throws on invalid

The exported designSchemaLenient / designSchemaCanonical implement the Standard Schema interface, so they interoperate with zod, Effect Schema, Valibot, and other Standard-Schema tools.

Normalize (fill defaults)

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

const complete = normalizeDesign(partial);
// every default filled in, unknown keys stripped

Idempotent and exact for current-format input. It does not migrate old schemaVersion documents, and it leaves render-derived values (e.g. text auto-height) for the editor to compute.

JSON Schema

A language-neutral JSON Schema (draft 2020-12) ships at @polotno/schema/design.schema.json — validate from any language or tooling.

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

Types

import type { Design, Page, Element, TextElement } from '@polotno/schema';

Related

• Polotno — the design editor SDK these documents come from.
• Import/export packages that produce or consume this JSON: pdf-import, svg-import, psd-import, pdf-export.

License

Part of the Polotno SDK — not open source; production use requires a valid Polotno subscription. See LICENSE.md · full terms.