The form file
A published form is one JSON document, the FormDefinition. It’s what npx seaforms pull saves, what getForm returns, and what <Form schema={…} /> draws.
{ "schemaVersion": 1, "id": "frm_7f3kq2m4xa", "revision": 3, "locale": "en-AU", "timezone": "Australia/Adelaide", "presentation": { "mode": "steps", "progress": { "bar": false, "time": true }, "labels": { "next": "Continue", "back": "Back", "submit": "Send message" }, "estimatedSeconds": 60, "requiredMarker": "optional-label", "badge": false }, "steps": [ { "id": "get-in-touch", "title": "Get in touch", "blocks": [ { "kind": "field", "key": "name", "label": "Name", "placeholder": "Maya Chen", "required": true, "autocomplete": "name", "type": "text" }, { "kind": "field", "key": "email", "label": "Email", "placeholder": "maya@northwind.co", "required": true, "autocomplete": "email", "type": "email" }, { "kind": "field", "key": "topic", "label": "What’s it about?", "required": true, "type": "choice", "display": "chips", "options": [ { "value": "sales", "label": "Sales" }, { "value": "support", "label": "Support" }, { "value": "press", "label": "Press" }, { "value": "something-else", "label": "Something else" } ] }, { "kind": "field", "key": "message", "label": "Message", "placeholder": "How can we help?", "required": true, "type": "textarea" } ] } ], "endings": [ { "id": "thanks", "title": "Thanks, {name}.", "body": "Your message is with the right person. We usually reply the same day." } ], "features": [], "initial": { "hidden": [], "alwaysRequired": [ "name", "email", "topic", "message" ] }, "hash": "3096824560e56c78"}Top-level keys
Section titled “Top-level keys”schemaVersion1required- The format’s version.
idfrm_…required- The form’s ID.
revisionnumberrequired- The published revision.
0in a draft. hashstring- Set on publish: the first 16 hex characters of the SHA-256 of the form. It’s how the server knows a page runs a version it published.
localestringrequired- A language tag, such as
en-AU. It sets number and date formats, and the default messages. timezonestringrequired- An IANA zone, such as
Australia/Adelaide. It’s what “today” means in date rules. featuresstring[]- Set on publish: what the form uses, such as
steps,logic,files,paymentorbooking. Checked against the site’s plan. presentationobjectrequired- How it’s shown:
mode(steps,singleorconversational),progress, buttonlabels,requiredMarkerandbadge. stepsStep[]required- At least one. A one-page form is one step.
variablesVariable[]- Calculations the visitor sees or that drive logic. Pro.
pricingobject- The currency and how a total is worked out.
endingsEnding[]required- The thank-yous. At least one, and the last has no condition.
messagesobject- Your own wording for validation messages.
assetsobject- Images, with their width and height so their space is kept.
initialobject- Set on publish: what shows before anyone answers, so the first render needs no script.
Features and plans
Section titled “Features and plans”Publishing a form that uses something its site’s plan doesn’t include answers 403 plan_required. Each value of features is first included on:
| First on | Features |
|---|---|
| Free | steps, logic, checks, priced, payment, coupons |
| Starter | files |
| Pro | calculations, summary, conversational, save-resume, booking |
Steps and blocks
Section titled “Steps and blocks”interface Step { id: string; title?: string; description?: string; blocks: Block[]; // at least one visibleWhen?: Condition; // false: the step is skipped checks?: Check[]; // rules across answers, run on Continue nextLabel?: string;}
type Block = Field | Group | Content;- A field is a question:
kind: "field". - A group is a fieldset that shows and hides as one:
kind: "group". - Content is text, an image, a divider, a price summary, a review of the answers or a discount code box:
kind: "content".
Endings
Section titled “Endings”interface Ending { id: string; when?: Condition; // the first match wins title: string; // "Thanks, {name}." body?: string; showSummary?: boolean;}Text can include an answer with a token, such as {name}. Rich text allows **bold**, *italic*, links and paragraphs, and nothing else.
A question’s key is its answer’s name in webhooks, the API and your types.
- It’s made from the question’s first label: “Work email” becomes
work_email. - It can be changed until the form’s first publish, then it’s frozen, so your code keeps working when someone rewords a question.
- Option
values work the same way: relabelling an option keeps its value. - Keys start with a letter, then lower-case letters, digits and underscores, up to 48 characters. Names like
id,meta,answers,files,payment,tags,totaland anything startingsf_are reserved.
- Questions: every type and its properties.
- Show when and Required when: the conditions.
- JSON Schema: the exact format, for your editor or a validator.
ChatGPT is a trademark of OpenAI, and Claude and Claude Code are trademarks of Anthropic. Other product names and logos belong to their owners. None of them makes or endorses Seaforms. Trademarks