Data Structures
The Unlayer design JSON is the single shape every part of the platform speaks — the embedded builder reads and writes it, the Cloud API exports, converts, and validates it, and the AI Assistant produces it. This section is the reference for the objects involved.
If you've used Stripe's API reference, you'll feel at home — each object gets its own page, every field is typed, and the inline examples are runnable.
Top-level objects
- Design object — the root JSON object the editor reads and writes. Wraps a single
body, plus counters and a schema version. - Block object — the containers inside a body: rows, columns, and the content items inside them.
- Content types — the leaf content blocks: text, image, button, heading, divider, HTML, video, social, menu, timer, and the
customslot for embedder-defined tools.
Two schema forms
Every design exists in two interchangeable forms, designed for different jobs:
| Form | When you'll see it |
|---|---|
| Full | What the embedded editor manipulates in memory. Every option, every computed default, every internal property. Verbose but lossless. |
| Simple | What Unlayer stores and ships over the wire. Strips defaults and editor-only metadata, keeping the parts an external consumer needs. |
The two convert into each other via the Cloud API convert endpoints. Round-trip safely by passing includeConversion: true on the way out — the embedded _conversion metadata restores original values without data loss.
Validation
Use POST /v3/templates/validate to check whether a payload conforms to the schema before it lands in storage or in front of the editor — much better DX than letting a malformed design crash a render.
Related
- Cloud API — the REST surface that consumes and produces these structures.
- Cloud API reference — the v2 export and template APIs that operate on designs.
- AI Assistant — generates and edits these structures in place inside the embedded editor.