Form Schema Reference

The form schema is the canonical definition of an AgentsForms form. It is written as a JSON document, validated server-side, and versioned on publish.

Schema overview

A form definition is a JSON object with these top-level properties:

Property	Type	Required	Description
name	string	yes	Human-readable form name.
slug	string	yes	URL-safe identifier matching ^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$.
description	string	no	Short description of the form’s purpose.
fields	Field[]	yes	Array of field definitions. Minimum 1, maximum 100.
settings	Settings	no	Form-level settings (submit label, success message, retention).

Field properties

Every field in the fields array shares these base properties:

Property	Type	Required	Constraints	Description
id	string	yes	Regex ^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$, unique within the form	Stable developer-defined field identifier. Used in webhook payloads and submissions.
label	string	yes	Minimum 1 character	Human-readable label rendered above the input.
type	string	yes	One of 13 field types (see below)	Controls the input widget presented to the user.
required	boolean	no	Default false	If true, the user must provide a value before submitting.
description	string	no	—	Helper text shown below the field.
agentHint	string	no	—	Natural-language hint for AI agents about what value to provide. Not shown to the end user.
options	Option[]	conditional	Required for select, multi_select, radio; minimum 1 option	Array of { "label": string, "value": string } pairs. Both must be non-empty.
defaultValue	unknown	no	Type must match the field type	Prefill value shown when the form first loads.
hidden	boolean	no	Default false	If true, the field is not shown to the human user (agent-only). The value is still collected and included in submissions.

Field types

All 13 supported field types, with example JSON snippets:

text

Single-line text input.

{ "id": "name", "label": "Full name", "type": "text", "required": true }

textarea

Multi-line text area for longer input.

{ "id": "message", "label": "Description", "type": "textarea", "required": true }

email

Email input with client-side validation.

{ "id": "email", "label": "Email address", "type": "email", "required": true }

url

URL input with client-side validation.

{ "id": "website", "label": "Website", "type": "url" }

number

Numeric input with optional min/max (define via description or agent-specific context).

{ "id": "age", "label": "Age", "type": "number" }

boolean

Toggle / checkbox for true/false values.

{ "id": "agreed", "label": "I agree to the terms", "type": "boolean", "required": true }

date

Date picker (ISO 8601 date string).

{ "id": "due_date", "label": "Due date", "type": "date" }

select

Single-select dropdown.

{
  "id": "priority",
  "label": "Priority",
  "type": "select",
  "required": true,
  "options": [
    { "label": "Low", "value": "low" },
    { "label": "Medium", "value": "medium" },
    { "label": "High", "value": "high" }
  ]
}

multi_select

Multi-select allowing multiple choices.

{
  "id": "categories",
  "label": "Categories",
  "type": "multi_select",
  "options": [
    { "label": "Bug", "value": "bug" },
    { "label": "Feature", "value": "feature" },
    { "label": "Question", "value": "question" }
  ]
}

checkbox

Single checkbox (boolean with a label — distinct from boolean which renders as a toggle).

{ "id": "subscribe", "label": "Subscribe to updates", "type": "checkbox" }

radio

Radio button group.

{
  "id": "plan",
  "label": "Plan",
  "type": "radio",
  "required": true,
  "options": [
    { "label": "Starter", "value": "starter" },
    { "label": "Pro", "value": "pro" }
  ]
}

hidden

Field not displayed to the user. Value provided by the agent or system.

{ "id": "session_id", "type": "hidden", "defaultValue": "sess_xxx" }

file

File upload field.

{ "id": "attachment", "label": "Screenshot", "type": "file" }

Settings

The settings object configures form-level behavior:

Property	Type	Default	Description
allowPartial	boolean	false	Allow the user to submit partial (incomplete) responses.
submitLabel	string	"Submit"	Custom label for the submit button.
successMessage	string	—	Message shown after successful submission.
retentionDays	number	—	Number of days to retain submissions. Integer, positive, max 3650 (10 years).

Full schema example

A complete form definition with every property used:

{
  "name": "Support Intake",
  "slug": "support-intake",
  "description": "Collect missing info from users for support agents.",
  "fields": [
    {
      "id": "email",
      "label": "Email",
      "type": "email",
      "required": true,
      "description": "We'll use this to follow up.",
      "agentHint": "User's verified email address"
    },
    {
      "id": "priority",
      "label": "Priority",
      "type": "select",
      "required": true,
      "options": [
        { "label": "Low", "value": "low" },
        { "label": "Medium", "value": "medium" },
        { "label": "High", "value": "high" }
      ],
      "defaultValue": "medium"
    },
    {
      "id": "message",
      "label": "What do you need help with?",
      "type": "textarea",
      "required": true,
      "description": "Include steps to reproduce if reporting a bug."
    },
    {
      "id": "session_id",
      "type": "hidden",
      "defaultValue": "sess_placeholder"
    }
  ],
  "settings": {
    "submitLabel": "Send to agent",
    "successMessage": "Thanks — an agent will continue with this.",
    "retentionDays": 90
  }
}

Validation rules

Forms are validated server-side using Zod schemas (source: packages/schemas/src/index.ts). Violations produce a 422 response with detailed error paths.

Rule	Error code	Description
Field id must start with a letter and contain only [a-zA-Z0-9_.-], max 64 chars	invalid_string	The id is used as a stable key in API responses and webhook payloads.
Field id must be unique within the form	duplicate_field_id	Two fields cannot share the same id.
slug must match ^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$	invalid_string	Lowercase alphanumeric, optional hyphens, must not start or end with a hyphen.
select, multi_select, and radio fields require at least one option	select_options_required	These field types are meaningless without choices.
Maximum 100 fields per form	too_big	Forms are not designed for unbounded field counts.
options array entries must have non-empty label and value	invalid_string	Each { label, value } pair must be complete.

Tip

When validation fails, the API returns a structured error body — see REST API → for the error response shape.