# Form definition schema | OneForm > The OneForm form definition as JSON Schema: question types, logic, hidden fields, endings and reports, with a browsable schema, a download, and a small… Source: https://oneform.si/developers/form-schema/ --- 1. [Home](https://oneform.si/) 2. [Developers](https://oneform.si/developers/) 3. Form schema [View as Markdown](https://oneform.si/developers/form-schema.md) Developers # Form schema A OneForm form is a JSON definition: its questions, logic and screens. This is the JSON Schema (draft 2020-12) OneForm checks every save against, generated from the same code. [Download form-schema.json](https://oneform.si/developers/form-schema.json) ## Structure | fields | The questions, in order: each with a unique id, a type, a title and required. | | ------------ | ---------------------------------------------------------------------------------------- | | welcome | The first screen, if any. | | thankYou | The default thank-you screen. | | endings | Other thank-you screens, chosen by conditions. | | variables | Numbers and text that logic can change, for scores. | | hiddenFields | Values the form takes from its link or embed: \[{ key, label }\]. | | settings | Languages and other form settings. | | translations | Text in other languages. | | report | The document OneFormAI writes from each submission: { enabled, title, prompt, docType }. | Questions can carry `visibleIf` conditions and `jumps`; operators are `is`, `is_not`, `contains`, `not_contains`, `any_of`, `none_of`, `all_of`, `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `before`, `after`, `answered`, `not_answered`. A `role` (first\_name, last\_name, full\_name, email, phone, company) tells OneForm who the respondent is, for names in reports and emails and for Leads. ## Question types | type | Shown as | Collects | | ---------------- | --------------- | ---------------------------------------------------------------------------------------------------- | | short\_text | Short text | One line of text. | | long\_text | Long text | A paragraph. | | multiple\_choice | Multiple choice | One or several of choices: \[{ id, label }\]. multiple allows several, allowOther adds an Other box. | | yes\_no | Yes / No | Yes or no. | | email | Email | An email address. | | phone | Phone number | A phone number. | | number | Number | A number. | | date | Date | A date. | | contact\_group | Contact info | Several contact details on one screen, in fields of type short\_text, email, phone, number. | | line\_items | Line items | Rows of items, such as receipts or expenses. | | statement | Statement | Text to read. Asks nothing. | ## The schema Open a property to see what it holds. Required properties are marked. form-schema.json - `welcome`object - `enabled`booleandefault true - `title`stringrequired - `description`string - `layout`string `"classic"` `"card"` `"image-top"` `"banner"` `"background"` `"background-dark"` `"split-left"` `"split-right"` `"side-third"` `"avatar"` - `image`object - `url`stringrequired - `alt`string - `overlay`number≥ 0≤ 0.9 - `showLogo`boolean - `links`object\[\]at most 10 - `kind`stringrequired `"website"` `"linkedin"` `"x"` `"facebook"` `"instagram"` `"youtube"` `"tiktok"` `"email"` `"phone"` `"booking"` - `url`stringrequiredmax length 2000 - `label`string - `buttonText`stringdefault "Start" - `imageUrl`string - `badge`string - `headline`string - `fields`object\[\]required - `id`stringrequiredmin length 1 - `title`stringrequired - `description`string - `required`booleandefault false - `placeholder`string - `role`string `"first_name"` `"last_name"` `"full_name"` `"email"` `"phone"` `"company"` - `type`stringrequired `"short_text"` `"long_text"` `"multiple_choice"` `"yes_no"` `"email"` `"phone"` `"number"` `"date"` `"contact_group"` `"line_items"` `"statement"` - `choices`object\[\] - `id`stringrequiredmin length 1 - `label`stringrequired - `allowOther`boolean - `multiple`boolean - `fields`object\[\] - `id`stringrequiredmin length 1 - `title`stringrequired - `description`string - `required`booleandefault false - `placeholder`string - `role`string `"first_name"` `"last_name"` `"full_name"` `"email"` `"phone"` `"company"` - `type`stringrequired `"short_text"` `"email"` `"phone"` `"number"` - `media`object - `kind`stringrequired `"image"` `"video"` - `url`stringrequired - `alt`string - `layout`string `"stack"` `"split-left"` `"split-right"` - `buttonText`string - `visibleIf`object - `match`stringrequired `"all"` `"any"` - `conditions`object\[\]required - `id`stringrequired - `left`object | object | objectrequired - `op`stringrequired `"is"` `"is_not"` `"contains"` `"not_contains"` `"any_of"` `"none_of"` `"all_of"` `"eq"` `"neq"` `"gt"` `"gte"` `"lt"` `"lte"` `"before"` `"after"` `"answered"` `"not_answered"` - `value`string | number | boolean | string\[\] - `jumps`object\[\] - `id`stringrequired - `when`objectrequired - `match`stringrequired `"all"` `"any"` - `conditions`object\[\]required - `id`stringrequired - `left`object | object | objectrequired - `op`stringrequired `"is"` `"is_not"` `"contains"` `"not_contains"` `"any_of"` `"none_of"` `"all_of"` `"eq"` `"neq"` `"gt"` `"gte"` `"lt"` `"lte"` `"before"` `"after"` `"answered"` `"not_answered"` - `value`string | number | boolean | string\[\] - `goto`object | objectrequired - `otherwise`object | object - `calc`object\[\] - `id`stringrequired - `var`stringrequired - `op`stringrequired `"add"` `"subtract"` `"multiply"` `"set"` `"add_answer"` - `amount`numberrequired - `when`object - `match`stringrequired `"all"` `"any"` - `conditions`object\[\]required - `id`stringrequired - `left`object | object | objectrequired - `op`stringrequired `"is"` `"is_not"` `"contains"` `"not_contains"` `"any_of"` `"none_of"` `"all_of"` `"eq"` `"neq"` `"gt"` `"gte"` `"lt"` `"lte"` `"before"` `"after"` `"answered"` `"not_answered"` - `value`string | number | boolean | string\[\] - `leadPoints`{ \[key\]: number } - `lineItems`object - `currency`string - `showDate`boolean - `showCategory`boolean - `showQuantity`boolean - `categories`string\[\] - `taxRate`number - `maxRows`integer≥ -9007199254740991≤ 9007199254740991 - `pin`string `"first"` `"last"` - `thankYou`objectrequired - `id`string - `title`stringrequired - `description`string - `layout`string `"classic"` `"card"` `"image-top"` `"banner"` `"background"` `"background-dark"` `"split-left"` `"split-right"` `"side-third"` `"avatar"` - `image`object - `url`stringrequired - `alt`string - `overlay`number≥ 0≤ 0.9 - `showLogo`boolean - `links`object\[\]at most 10 - `kind`stringrequired `"website"` `"linkedin"` `"x"` `"facebook"` `"instagram"` `"youtube"` `"tiktok"` `"email"` `"phone"` `"booking"` - `url`stringrequiredmax length 2000 - `label`string - `cta`object - `text`stringrequired - `url`stringrequiredmax length 2000 - `redirect`object - `url`stringrequired - `delaySec`number≥ 0≤ 30 - `params`string\[\] - `when`object - `match`stringrequired `"all"` `"any"` - `conditions`object\[\]required - `id`stringrequired - `left`object | object | objectrequired - `op`stringrequired `"is"` `"is_not"` `"contains"` `"not_contains"` `"any_of"` `"none_of"` `"all_of"` `"eq"` `"neq"` `"gt"` `"gte"` `"lt"` `"lte"` `"before"` `"after"` `"answered"` `"not_answered"` - `value`string | number | boolean | string\[\] - `hideOffer`boolean - `scheduler`object - `provider`stringrequired `"calendly"` `"calcom"` `"tidycal"` `"acuity"` `"savvycal"` `"youcanbookme"` `"hubspot"` `"zoho"` `"msbookings"` `"google"` `"other"` `"oneform"` - `url`stringmax length 500 - `display`string `"inline"` `"button"` - `height`integer≥ 400≤ 1600 - `prefill`boolean - `label`stringmax length 60 - `endings`object\[\] - `id`stringrequired - `title`stringrequired - `description`string - `layout`string `"classic"` `"card"` `"image-top"` `"banner"` `"background"` `"background-dark"` `"split-left"` `"split-right"` `"side-third"` `"avatar"` - `image`object - `url`stringrequired - `alt`string - `overlay`number≥ 0≤ 0.9 - `showLogo`boolean - `links`object\[\]at most 10 - `kind`stringrequired `"website"` `"linkedin"` `"x"` `"facebook"` `"instagram"` `"youtube"` `"tiktok"` `"email"` `"phone"` `"booking"` - `url`stringrequiredmax length 2000 - `label`string - `cta`object - `text`stringrequired - `url`stringrequiredmax length 2000 - `redirect`object - `url`stringrequired - `delaySec`number≥ 0≤ 30 - `params`string\[\] - `when`object - `match`stringrequired `"all"` `"any"` - `conditions`object\[\]required - `id`stringrequired - `left`object | object | objectrequired - `op`stringrequired `"is"` `"is_not"` `"contains"` `"not_contains"` `"any_of"` `"none_of"` `"all_of"` `"eq"` `"neq"` `"gt"` `"gte"` `"lt"` `"lte"` `"before"` `"after"` `"answered"` `"not_answered"` - `value`string | number | boolean | string\[\] - `hideOffer`boolean - `scheduler`object - `provider`stringrequired `"calendly"` `"calcom"` `"tidycal"` `"acuity"` `"savvycal"` `"youcanbookme"` `"hubspot"` `"zoho"` `"msbookings"` `"google"` `"other"` `"oneform"` - `url`stringmax length 500 - `display`string `"inline"` `"button"` - `height`integer≥ 400≤ 1600 - `prefill`boolean - `label`stringmax length 60 - `variables`object\[\] - `name`stringrequired - `label`string - `initial`number - `hiddenFields`object\[\] - `key`stringrequired - `label`string - `settings`object - `showQuestionNumbers`boolean - `languages`object - `enabled`booleanrequired - `default`string `"en"` `"fr"` `"es"` - `available`string\[\] - `autoDetect`boolean - `voice`object - `enabled`booleanrequired - `maxSeconds`number - `mode`string `"offer"` `"native"` - `voice`string - `fillMany`boolean - `goal`string - `colors`string\[\]at most 3 - `personalization`object - `enabled`booleanrequired - `consultation`object - `enabled`booleanrequired - `title`stringmax length 120 - `description`stringmax length 600 - `durationMin`integer≥ 5≤ 480 - `price`object - `amount`integerrequired≥ 0≤ 1000000 - `currency`stringrequiredmin length 3max length 3 - `location`object - `kind`stringrequired `"zoom"` `"meet"` `"teams"` `"phone"` `"in_person"` `"custom"` - `phoneMode`string `"firm_calls"` `"invitee_calls"` - `phone`stringmax length 40 - `address`stringmax length 300 - `url`stringmax length 500 - `bufferBeforeMin`integer≥ 0≤ 240 - `bufferAfterMin`integer≥ 0≤ 240 - `minNoticeMin`integer≥ 0≤ 43200 - `maxDaysAhead`integer≥ 1≤ 365 - `maxPerDay`integer≥ 1≤ 50 - `hours`{ \[key\]: object\[\] } - `reminders`boolean - `changeHours`integer≥ 0≤ 720 - `refundHours`integer≥ 0≤ 720 - `confirmation`stringmax length 600 - `kind`string `"booking"` - `dynamic`object - `enabled`booleanrequired - `maxQuestions`integer≥ -9007199254740991≤ 9007199254740991 - `minQuestions`integer≥ -9007199254740991≤ 9007199254740991 - `goal`string - `translations`{ \[key\]: { \[key\]: object } } - `report`object - `enabled`booleanrequired - `title`stringdefault "Your personalized report" - `prompt`stringdefault "" - `idea`string - `kind`string `"report"` `"document"` - `docType`string `"report"` `"onboarding"` `"engagement_letter"` `"proposal"` `"invoice"` `"bill"` `"checklist"` `"hr_record"` `"tax_organizer"` `"document_request"` `"memo"` `"scope"` `"task_list"` - `audience`string `"respondent"` `"internal"` - `useAi`boolean - `pdfStyle`string `"classic"` `"modern"` `"executive"` `"minimal"` - `delivery`string `"ai"` `"file"` - `file`object - `id`stringrequired - `name`stringrequired - `bytes`integerrequired≥ -9007199254740991≤ 9007199254740991 - `fileSummary`stringmax length 600 - `autoSend`boolean - `autoSendAck`string - `nextStep`object - `kind`stringrequired `"none"` `"booking"` `"form"` - `formId`string - `label`stringmax length 60 - `pricing`object - `enabled`booleanrequired - `amount`integerrequired≥ 0≤ 1000000 - `currency`stringrequiredmin length 3max length 3 - `headline`stringmax length 120 - `bullets`string\[\]at most 5 - `buttonLabel`stringmax length 60 ## Example A small, valid form: five questions, one shown only to business owners, and a report. definition.json ```json { "welcome": { "enabled": true, "title": "Let's find your tax savings", "description": "Two minutes, five questions.", "buttonText": "Start" }, "fields": [ { "id": "name", "type": "short_text", "title": "What's your first name?", "required": true, "role": "first_name" }, { "id": "business", "type": "yes_no", "title": "Do you own a business?", "required": true }, { "id": "entity", "type": "multiple_choice", "title": "How is it set up?", "required": true, "choices": [ { "id": "sole", "label": "Sole proprietor" }, { "id": "llc", "label": "LLC" }, { "id": "scorp", "label": "S corporation" } ], "visibleIf": { "match": "all", "conditions": [ { "id": "c1", "left": { "kind": "field", "fieldId": "business" }, "op": "is", "value": true } ] } }, { "id": "income", "type": "number", "title": "Roughly what did you earn last year?", "required": false }, { "id": "contact", "type": "contact_group", "title": "Where should we send your report?", "required": true, "fields": [ { "id": "email", "type": "email", "title": "Email", "required": true, "role": "email" }, { "id": "phone", "type": "phone", "title": "Phone", "required": false, "role": "phone" } ] } ], "thankYou": { "title": "Thanks, {{first_name|there}}!", "description": "We'll email your report once a CPA has reviewed it." }, "report": { "enabled": true, "title": "Your tax opportunities", "prompt": "Write a short, friendly report of the tax-saving opportunities that fit these answers." }} ``` ## Checking a definition AI agents connected to [OneForm's MCP server](https://oneform.si/developers/mcp/) can read this schema with `get_form_schema` (or the `oneform://docs/form-schema` resource), check a draft with `validate_form_definition`, and then create it with `create_form`. New forms are drafts until someone publishes them. In your own code, any JSON Schema 2020-12 validator can check a definition against [form-schema.json](https://oneform.si/developers/form-schema.json). OneForm also checks what a schema can't: that uploaded files and booking links work, and logic rules that point nowhere or can never be true (warnings). That's what `validate_form_definition` reports. [← PreviousZapier](https://oneform.si/developers/zapier/) Questions about the API, webhooks or embeds? [Ask a developer](https://oneform.si/contact/?topic=developers). DevelopersForm schema - [Overview](https://oneform.si/developers/) - [REST API](https://oneform.si/developers/api/) - [Webhooks](https://oneform.si/developers/webhooks/) - [Embed](https://oneform.si/developers/embed/) - [AI agents (MCP)](https://oneform.si/developers/mcp/) - [OAuth](https://oneform.si/developers/oauth/) - [Zapier](https://oneform.si/developers/zapier/) - [Form schema](https://oneform.si/developers/form-schema/) Developers - [Overview](https://oneform.si/developers/) - [REST API](https://oneform.si/developers/api/) - [Webhooks](https://oneform.si/developers/webhooks/) - [Embed](https://oneform.si/developers/embed/) - [AI agents (MCP)](https://oneform.si/developers/mcp/) - [OAuth](https://oneform.si/developers/oauth/) - [Zapier](https://oneform.si/developers/zapier/) - [Form schema](https://oneform.si/developers/form-schema/) [OpenAPI spec](https://oneform.si/developers/openapi.json)[Ask a developer](https://oneform.si/contact/?topic=developers)