Skip to content

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.

src/forms/contact.seaforms.json
{
"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"
}
schemaVersion1required
The format’s version.
idfrm_…required
The form’s ID.
revisionnumberrequired
The published revision. 0 in 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, payment or booking. Checked against the site’s plan.
presentationobjectrequired
How it’s shown: mode (steps, single or conversational), progress, button labels, requiredMarker and badge.
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.

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 onFeatures
Freesteps, logic, checks, priced, payment, coupons
Starterfiles
Procalculations, summary, conversational, save-resume, booking
Step
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".
Ending
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, total and anything starting sf_ are reserved.
Was this helpful?

Your answer goes straight to the person who wrote it.

Thanks. We read every note and update the article.

Thanks, that helps us keep these useful.

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