The form definition

What you need to know

• A form is one JSON object with the top-level keys below. Every save sends all of them.
• Every question, choice, row, rule and calculation has an id: a lowercase UUIDv7, unique within the form.
• Titles and descriptions are small rich-text documents, not strings. Choice, row and button labels are plain strings.
• Images and logos are uploaded in trulyform, not over MCP. Keep the asset IDs get_form returns, and use null for new questions. See Design and theme.
• A key the format does not define makes the save fail, wherever it appears. A known setting that a question type does not use is ignored.

Top-level keys

A new form, as create_form returns it:

{
    "schemaVersion": 2,
    "mediaDefaults": {
        "assetId": null,
        "layout": "above",
        "altText": ""
    },
    "welcome": {
        "enabled": true,
        "title": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Welcome!"}]}]},
        "description": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"We would love to hear from you."}]}]},
        "button": "Start"
    },
    "ending": {
        "title": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Thank you!"}]}]},
        "description": {"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Your response has been received."}]}]}
    },
    "fields": [
        {
            "id": "01990000-0000-7000-8000-000000000001",
            "kind": "short_text",
            "title": {"type":"doc","content":[{"type":"paragraph","content":[]}]},
            "description": {"type":"doc","content":[{"type":"paragraph","content":[]}]},
            "required": false,
            "options": [],
            "rows": [],
            "settings": {"nextButton":"Next"},
            "media": {"inherit":true,"assetId":null,"layout":"above"}
        }
    ],
    "theme": {
        "preset": "paper",
        "background": "#ffffff",
        "foreground": "#111827",
        "primary": "#2563eb",
        "buttonText": "#ffffff",
        "font": "Inter",
        "radius": 12,
        "density": "comfortable",
        "logoAssetId": null,
        "backgroundAssetId": null
    },
    "settings": {
        "allowReanswer": true,
        "hiddenFields": [],
        "fillLimit": null
    },
    "rules": [],
    "calculations": []
}

Identifiers

• Format: 32 lowercase hexadecimal digits in groups of 8-4-4-4-12. The third group starts with 7 (version 7) and the fourth with 8, 9, a or b. For example 01990000-0000-7000-8000-000000000001.
• Unique within the form, across all questions, choices, rows, rules and calculations together. Two choices in different questions cannot share an ID.
• Keep existing IDs when you edit. Responses, logic rules and piped answers refer to them; a question with a new ID is a new question.
• New IDs: generate a UUIDv7, or call list_field_types with id_count to receive fresh ones. The timestamp part of a UUIDv7 is not checked. The IDs in these docs are readable placeholders; make sure none of them collides with an ID already in the form.
• The mutation_id of save_form_draft is a UUIDv7 too, new for every save.

Questions

Each entry in fields is one question:

What each kind accepts is in Question types.

Rich text

Question titles and descriptions, and the titles and descriptions of the welcome and ending screens, are rich-text documents: a doc holding paragraphs, which hold text.

{
    "type": "doc",
    "content": [
        {
            "type": "paragraph",
            "content": [
                { "type": "text", "text": "What is your " },
                { "type": "text", "text": "work", "marks": [{ "type": "bold" }] },
                { "type": "text", "text": " email address?" }
            ]
        }
    ]
}

An empty description is {"type": "doc", "content": [{"type": "paragraph", "content": []}]}.

Text marks: bold, italic, underline, strike, written as "marks": [{"type": "bold"}]. Up to 4 marks per text node and 10,000 characters per text node.

Use several paragraphs for several lines of text. There is no link mark: to point people to a page, write its address as text, for example in the description. Do not add a required marker such as an asterisk: trulyform shows one for required questions.

Piped answers

An answerToken node shows an earlier answer or a calculation result inside text, with a fallback for when there is nothing to show. Piped answers explains where tokens may appear.

Welcome and ending

• welcome: {enabled, title, description, button}. Set enabled to false to start with the first question. When it is enabled, button must not be blank.
• ending: {title, description}, shown after the last question.

Form settings

Theme and images

The theme, mediaDefaults and each question's media are described in Design and theme. Over MCP, keep asset IDs exactly as get_form returns them and give new questions {"inherit": true, "assetId": null, "layout": "above"}.