FormResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/formasty-com/json-schema/formasty-com-form-response-schema.json",
  "title": "FormResponse",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/formasty-com-openapi.json#/components/schemas/FormResponse",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "draft_schema",
    "settings",
    "published_schema"
  ],
  "properties": {
    "data": {
      "$ref": "#/$defs/FormSummary"
    },
    "draft_schema": {
      "$ref": "#/$defs/DraftSchema"
    },
    "settings": {
      "type": "object",
      "additionalProperties": true,
      "description": "Complete operational settings for the current draft. Send this snapshot with draft_schema when changing both."
    },
    "published_schema": {
      "oneOf": [
        {
          "$ref": "#/$defs/DraftSchema"
        },
        {
          "type": "null"
        }
      ]
    },
    "draft_revision": {
      "type": "integer",
      "minimum": 0
    },
    "public_url": {
      "type": "string"
    }
  },
  "$defs": {
    "DraftSchema": {
      "type": "object",
      "properties": {
        "version": {
          "type": "integer",
          "enum": [
            1
          ],
          "description": "Current builder schema version."
        },
        "steps": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Stable step id. Supply one only when you need a caller-controlled id; otherwise Formasty can generate it."
              },
              "title": {
                "type": "string"
              },
              "backButtonLabel": {
                "type": "string"
              },
              "nextButtonLabel": {
                "type": "string"
              },
              "welcomeOverline": {
                "type": "string"
              },
              "showWelcomeStepInfo": {
                "type": "boolean"
              },
              "showWelcomeQuestionCount": {
                "type": "boolean"
              },
              "showWelcomeTimeEstimate": {
                "type": "boolean"
              },
              "welcomeIcon": {
                "type": "string",
                "enum": [
                  "none",
                  "sparkles",
                  "rocket",
                  "gem",
                  "heart_handshake",
                  "briefcase_business",
                  "building_2",
                  "store",
                  "landmark",
                  "globe_2",
                  "shield_check",
                  "graduation_cap"
                ]
              },
              "welcomeIconCustomUrl": {
                "type": "string",
                "description": "Absolute URL string. Prefer https URLs for public assets and integrations."
              },
              "coverImageUrl": {
                "type": "string",
                "description": "Absolute URL string. Prefer https URLs for public assets and integrations."
              },
              "coverImageAttribution": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "unsplash"
                    ]
                  },
                  "photographerName": {
                    "type": "string"
                  },
                  "photographerUrl": {
                    "type": "string",
                    "description": "Absolute URL string. Prefer https URLs for public assets and integrations."
                  },
                  "sourceName": {
                    "type": "string",
                    "enum": [
                      "Unsplash"
                    ]
                  },
                  "sourceUrl": {
                    "type": "string",
                    "description": "Absolute URL string. Prefer https URLs for public assets and integrations."
                  },
                  "photoUrl": {
                    "type": "string",
                    "description": "Absolute URL string. Prefer https URLs for public assets and integrations."
                  }
                },
                "required": [
                  "provider",
                  "photographerName",
                  "photographerUrl",
                  "sourceUrl"
                ],
                "description": "Linked attribution metadata for third-party images. Currently used for Unsplash photos.",
                "additionalProperties": false
              },
              "coverImageBrightness": {
                "type": "integer",
                "minimum": 40,
                "maximum": 140
              },
              "coverImageLayout": {
                "type": "string",
                "enum": [
                  "stack",
                  "split",
                  "wallpaper"
                ]
              },
              "coverImageSplitSide": {
                "type": "string",
                "enum": [
                  "left",
                  "right"
                ]
              },
              "fields": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Stable field id. Required when adding a field only if you need a caller-supplied id; ignored by update_field patches."
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "text",
                        "email",
                        "number",
                        "signature",
                        "scheduler",
                        "rating",
                        "nps",
                        "opinion_scale",
                        "matrix",
                        "file_upload",
                        "video_audio",
                        "address",
                        "date",
                        "textarea",
                        "statement",
                        "select",
                        "radio",
                        "picture_choice",
                        "ranking",
                        "checkbox"
                      ],
                      "description": "Builder field type. Reuse the exact type strings returned by formasty_get_form()."
                    },
                    "label": {
                      "type": "string",
                      "description": "Primary field label shown to respondents."
                    },
                    "required": {
                      "type": "boolean",
                      "description": "Whether the respondent must answer this field."
                    },
                    "hidden": {
                      "type": "boolean",
                      "description": "Whether the field is hidden from respondents and mainly used for workflow/data capture."
                    },
                    "helpText": {
                      "type": "string",
                      "description": "Helper copy shown below the label."
                    },
                    "description": {
                      "type": "string",
                      "description": "Alias for helpText accepted by MCP field mutations. Prefer helpText for canonical draft schemas."
                    },
                    "requiredMessage": {
                      "type": "string"
                    },
                    "defaultValue": {
                      "type": "string"
                    },
                    "urlParameter": {
                      "type": "string",
                      "description": "URL parameter name used for prefill when the field type supports it."
                    },
                    "placeholder": {
                      "type": "string"
                    },
                    "textSubtype": {
                      "type": "string",
                      "enum": [
                        "phone",
                        "website"
                      ]
                    },
                    "textareaSize": {
                      "type": "string",
                      "enum": [
                        "small",
                        "medium",
                        "large",
                        "extralarge"
                      ]
                    },
                    "statementEmbedUrl": {
                      "type": "string",
                      "description": "Absolute URL string. Prefer https URLs for public assets and integrations."
                    },
                    "statementAlign": {
                      "type": "string",
                      "enum": [
                        "left",
                        "center"
                      ]
                    },
                    "minNumber": {
                      "type": "number"
                    },
                    "maxNumber": {
                      "type": "number"
                    },
                    "minCharacters": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "maxCharacters": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "addressVisibility": {
                      "type": "object",
                      "properties": {
                        "line2": {
                          "type": "boolean"
                        },
                        "city": {
                          "type": "boolean"
                        },
                        "state": {
                          "type": "boolean"
                        },
                        "postalCode": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "boolean"
                        }
                      },
                      "description": "Address subfield visibility controls.",
                      "additionalProperties": false
                    },
                    "addressConfig": {
                      "type": "object",
                      "properties": {
                        "line1": {
                          "type": "object",
                          "properties": {
                            "label": {
                              "type": "string"
                            },
                            "placeholder": {
                              "type": "string"
                            },
                            "required": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "label",
                            "placeholder",
                            "required"
                          ],
                          "additionalProperties": false
                        },
                        "line2": {
                          "type": "object",
                          "properties": {
                            "label": {
                              "type": "string"
                            },
                            "placeholder": {
                              "type": "string"
                            },
                            "required": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "label",
                            "placeholder",
                            "required"
                          ],
                          "additionalProperties": false
                        },
                        "city": {
                          "type": "object",
                          "properties": {
                            "label": {
                              "type": "string"
                            },
                            "placeholder": {
                              "type": "string"
                            },
                            "required": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "label",
                            "placeholder",
                            "required"
                          ],
                          "additionalProperties": false
                        },
                        "state": {
                          "type": "object",
                          "properties": {
                            "label": {
                              "type": "string"
                            },
                            "placeholder": {
                              "type": "string"
                            },
                            "required": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "label",
                            "placeholder",
                            "required"
                          ],
                          "additionalProperties": false
                        },
                        "postalCode": {
                          "type": "object",
                          "properties": {
                            "label": {
                              "type": "string"
                            },
                            "placeholder": {
                              "type": "string"
                            },
                            "required": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "label",
                            "placeholder",
                            "required"
                          ],
                          "additionalProperties": false
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "label": {
                              "type": "string"
                            },
                            "placeholder": {
                              "type": "string"
                            },
                            "required": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "label",
                            "placeholder",
                            "required"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "description": "Per-subfield address labels, placeholders, and required flags.",
                      "additionalProperties": false
                    },
                    "maxStars": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "allowHalfStars": {
                      "type": "boolean"
                    },
                    "minScaleValue": {
                      "type": "integer",
                      "enum": [
                        0,
                        1
                      ]
                    },
                    "maxScale": {
                      "type": "integer",
                      "minimum": 2
                    },
                    "leftLabel": {
                      "type": "string"
                    },
                    "rightLabel": {
                      "type": "string"
                    },
                    "singleRowOnMobile": {
                      "type": "boolean"
                    },
                    "rows": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Stable option id. Reuse existing ids when editing an existing field; supply a new id when adding a new option."
                          },
                          "label": {
                            "type": "string",
                            "description": "Human-readable option label shown in the form."
                          },
                          "value": {
                            "type": "string",
                            "description": "Submitted option value. Keep it stable once the form is live unless you intend to change downstream data."
                          },
                          "imageUrl": {
                            "type": "string",
                            "description": "Optional image URL for picture choice options. Leave unset for text-only choices."
                          },
                          "calcValue": {
                            "type": "number",
                            "description": "Optional numeric value contributed to calculated variables when this option is selected (select, radio, picture_choice, checkbox only; not ranking/matrix). Finite, |value| <= 1e9; decimals allowed."
                          }
                        },
                        "required": [
                          "id",
                          "label",
                          "value"
                        ],
                        "description": "Choice option payload used by select, radio, checkbox, picture_choice, ranking, and matrix fields.",
                        "additionalProperties": false
                      }
                    },
                    "columns": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Stable option id. Reuse existing ids when editing an existing field; supply a new id when adding a new option."
                          },
                          "label": {
                            "type": "string",
                            "description": "Human-readable option label shown in the form."
                          },
                          "value": {
                            "type": "string",
                            "description": "Submitted option value. Keep it stable once the form is live unless you intend to change downstream data."
                          },
                          "imageUrl": {
                            "type": "string",
                            "description": "Optional image URL for picture choice options. Leave unset for text-only choices."
                          },
                          "calcValue": {
                            "type": "number",
                            "description": "Optional numeric value contributed to calculated variables when this option is selected (select, radio, picture_choice, checkbox only; not ranking/matrix). Finite, |value| <= 1e9; decimals allowed."
                          }
                        },
                        "required": [
                          "id",
                          "label",
                          "value"
                        ],
                        "description": "Choice option payload used by select, radio, checkbox, picture_choice, ranking, and matrix fields.",
                        "additionalProperties": false
                      }
                    },
                    "allowMultipleSelection": {
                      "type": "boolean"
                    },
                    "maxFileSizeMb": {
                      "type": "number",
                      "minimum": 1
                    },
                    "allowMultiple": {
                      "type": "boolean"
                    },
                    "allowedFileTypes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Allowed upload file type ids. Reuse values already supported by the Forms API/upload configuration."
                    },
                    "schedulerProvider": {
                      "type": "string",
                      "enum": [
                        "tidycal",
                        "calendly",
                        "savvycal",
                        "calcom"
                      ]
                    },
                    "schedulerUrl": {
                      "type": "string",
                      "description": "Public booking URL for scheduler fields. If omitted or empty, MCP returns a scheduler_url_missing notice that the agent must tell the user about."
                    },
                    "calendarOpenerLabel": {
                      "type": "string"
                    },
                    "randomizeOptions": {
                      "type": "boolean"
                    },
                    "horizontalOptions": {
                      "type": "boolean"
                    },
                    "optionColumns": {
                      "type": "integer",
                      "enum": [
                        1,
                        2,
                        3
                      ]
                    },
                    "checkboxMode": {
                      "type": "string",
                      "enum": [
                        "multi",
                        "single",
                        "yes_no"
                      ]
                    },
                    "includeOtherOption": {
                      "type": "boolean"
                    },
                    "selectionLimitMode": {
                      "type": "string",
                      "enum": [
                        "none",
                        "exact",
                        "range"
                      ]
                    },
                    "selectionLimitExact": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "selectionLimitMin": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "selectionLimitMax": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "options": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Stable option id. Reuse existing ids when editing an existing field; supply a new id when adding a new option."
                          },
                          "label": {
                            "type": "string",
                            "description": "Human-readable option label shown in the form."
                          },
                          "value": {
                            "type": "string",
                            "description": "Submitted option value. Keep it stable once the form is live unless you intend to change downstream data."
                          },
                          "imageUrl": {
                            "type": "string",
                            "description": "Optional image URL for picture choice options. Leave unset for text-only choices."
                          },
                          "calcValue": {
                            "type": "number",
                            "description": "Optional numeric value contributed to calculated variables when this option is selected (select, radio, picture_choice, checkbox only; not ranking/matrix). Finite, |value| <= 1e9; decimals allowed."
                          }
                        },
                        "required": [
                          "id",
                          "label",
                          "value"
                        ],
                        "description": "Choice option payload used by select, radio, checkbox, picture_choice, ranking, and matrix fields.",
                        "additionalProperties": false
                      },
                      "description": "Choice options. Required for select, radio, checkbox, picture_choice, and ranking fields."
                    }
                  },
                  "required": [
                    "type",
                    "label",
                    "required"
                  ],
                  "description": "Field payload for add_field and full draft schemas. MCP exposes every active builder field type except payment. Choice fields also require options with id, label, and value. Do not add respondent input fields to the leading welcome screen; add them to a later question step.",
                  "additionalProperties": false
                },
                "description": "Ordered field list for this step. Multiple respondent input fields are allowed when they belong together on the same screen, such as compact contact details or tightly related grouped follow-ups."
              }
            },
            "required": [
              "fields"
            ],
            "description": "Draft step payload. Use formasty_get_form() as the canonical source of current step ids and structure. The leading welcome screen must be a statement-only intro; respondent input fields belong in later steps and may be grouped when the form experience benefits from multiple fields on one screen.",
            "additionalProperties": false
          },
          "description": "Ordered draft steps. MCP supports a leading welcome screen as the first statement-only step. Later question steps may contain one or multiple fields when grouping improves the respondent experience."
        },
        "settings": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Form title shown across builder, dashboard, and public runtime."
            },
            "description": {
              "type": "string"
            },
            "slug": {
              "type": "string"
            },
            "searchEngineIndexing": {
              "type": "boolean",
              "description": "Legacy explicit discovery permission. Use discoveryMode for workspace inheritance. Live current-owner consent, publication and open access remain required. Imports/copies stay off. Responses and result-share URLs remain noindex."
            },
            "discoveryMode": {
              "type": "string",
              "enum": [
                "inherit",
                "on",
                "off"
              ],
              "description": "inherit follows the current owner's all/selected/none workspace default; on explicitly enables this form even with default none; off always disables it. Legacy schemas without this property use searchEngineIndexing as an explicit override. New ordinary forms inherit; imports/copies stay off. Google indexing/ranking is not guaranteed."
            },
            "successMessage": {
              "type": "string"
            },
            "redirectUrl": {
              "type": "string",
              "description": "Absolute URL string. Prefer https URLs for public assets and integrations."
            },
            "submitButtonLabel": {
              "type": "string"
            },
            "labels": {
              "type": "object",
              "properties": {
                "nextQuestionKeyboardInstruction": {
                  "type": "string"
                },
                "submitKeyboardInstruction": {
                  "type": "string"
                },
                "otherOptionLabel": {
                  "type": "string"
                },
                "otherOptionHint": {
                  "type": "string"
                },
                "uploadInstruction": {
                  "type": "string"
                },
                "uploadMaxFileSizeMessage": {
                  "type": "string"
                },
                "uploadInProgressMessage": {
                  "type": "string"
                },
                "uploadFinishingMessage": {
                  "type": "string"
                },
                "offlineErrorMessage": {
                  "type": "string"
                },
                "onlineRestoredMessage": {
                  "type": "string"
                },
                "serverErrorMessage": {
                  "type": "string"
                },
                "uploadErrorMessage": {
                  "type": "string"
                },
                "uploadFileSizeErrorMessage": {
                  "type": "string"
                },
                "uploadFileTypeErrorMessage": {
                  "type": "string"
                },
                "schedulerRequiredErrorMessage": {
                  "type": "string"
                },
                "duplicateSubmissionTitle": {
                  "type": "string"
                },
                "duplicateSubmissionDescription": {
                  "type": "string"
                }
              },
              "description": "Runtime copy labels shown across the live form and embeds.",
              "additionalProperties": false
            },
            "builder": {
              "type": "object",
              "properties": {
                "createStepPerField": {
                  "type": "boolean"
                },
                "requiresProPublish": {
                  "type": "boolean",
                  "readOnly": true,
                  "description": "Server-managed publish gate. Preserve a returned true value; do not set this property on new drafts."
                }
              },
              "description": "Builder-only editing preferences.",
              "additionalProperties": false
            },
            "hidden": {
              "type": "object",
              "properties": {
                "hiddenFields": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "key": {
                        "type": "string",
                        "description": "Hidden field key. Use only letters, numbers, and underscores."
                      },
                      "defaultValue": {
                        "type": "string",
                        "description": "Default hidden field value."
                      }
                    },
                    "required": [
                      "key",
                      "defaultValue"
                    ],
                    "additionalProperties": false
                  }
                },
                "variables": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Stable workflow variable id. Omit when creating a new variable, or provide an existing id to update that variable."
                      },
                      "name": {
                        "type": "string",
                        "description": "Workflow variable token name. Use only letters, numbers, and underscores."
                      },
                      "type": {
                        "type": "string",
                        "enum": [
                          "number",
                          "text"
                        ],
                        "description": "Variable value type used by workflow conditions and actions."
                      },
            

# --- truncated at 32 KB (114 KB total) ---
# Full source: https://artifacts.apis.io/formasty-com/json-schema/formasty-com-form-response-schema.json