Form definition schema

Stored in ad_form_forms.definition as JSON. REST exposes it as an object, never as a raw string.

Field id values are stable. Moving, renaming or duplicating a form must not regenerate existing IDs.

Document

{
  "schema_version": 1,
  "settings": {
    "ajax": true,
    "honeypot": true,
    "require_login": false,
    "confirmation_type": "message",
    "confirmation_message": "",
    "redirect_url": ""
  },
  "fields": [
    {
      "id": "field_email",
      "type": "email",
      "key": "email",
      "label": "Email",
      "required": true,
      "step": "",
      "settings": {},
      "conditions": {
        "enabled": false,
        "effect": "show",
        "logic": "all",
        "rules": []
      }
    }
  ],
  "layout": { "rows": [] },
  "steps": [
    {
      "id": "step_intro",
      "title": "About you",
      "description": "",
      "next_label": "",
      "prev_label": ""
    },
    {
      "id": "step_message",
      "title": "Message",
      "description": "",
      "next_label": "",
      "prev_label": ""
    }
  ],
  "actions": [
    {
      "id": "action_a1b2c3d4",
      "type": "email",
      "enabled": true,
      "settings": {
        "to": "{admin:email}",
        "cc": "",
        "bcc": "",
        "from_name": "",
        "from_email": "",
        "reply_to": "",
        "subject": "New submission: {form:title}",
        "message": "{all_fields}"
      },
      "conditions": {
        "enabled": false,
        "effect": "show",
        "logic": "all",
        "rules": []
      }
    }
  ],
  "conditions": [],
  "styles": {}
}

Field rules

• id: ^[A-Za-z][A-Za-z0-9_-]{1,63}$, unique per form
• type: registered field type (text, email, number, textarea, select, checkbox, calculation, submit; add-ons may add more)
• key: unique sanitize_key value used in merge tags and submissions
• step: optional step id (same pattern). Empty or unknown values render on the first step. Submit fields always render on the last step. See STEPS.md.
• Unknown keys are preserved for add-ons

Common settings keys: admin_label, placeholder, default_value, description, css_class, width (100|75|66|50|33|25). Select fields store options as {label, value} pairs. Checkbox fields use checkbox_label and default_checked. Submit uses button_label. Number fields add min, max, step. Calculation fields add formula, decimals, prefix, suffix — see CALCULATIONS.md.

Steps

See STEPS.md. steps is a list of {id, title, description, next_label, prev_label}. Fewer than two entries is a single-page form. Duplicate IDs are regenerated on sanitize.

Conditions

See CONDITIONS.md. Field and action conditions is a group object (enabled, effect, logic, rules). A legacy list of {field, operator} rules is wrapped into an enabled show / all group on sanitize.

Actions

See ACTIONS.md. Each action needs a stable id and a type. Unknown types are preserved so add-ons can store settings; the runner skips types that are not registered. Email settings allow merge tags in to / cc / bcc / reply_to / subject / message. from_email must be a literal address (or empty). Optional conditions decide whether the action runs.

Machine-readable schema: GET /wp-json/ad-form/v1/forms/schema

PHP: Dingfelder\AdForm\Forms\FormJsonSchema::definition()