Configuring the Workflow Trigger Input Schema

Overview

The trigger input schema defines what data a workflow expects when it starts — and what happens when that data doesn't match. For manual triggers, it controls the form your team fills out at launch. For event, webhook, and schedule triggers, it validates incoming payloads before any nodes run.

In this article, we'll be covering what the input schema is, how to configure it, the supported field types, and how validation works at execution time.

Understanding what the input schema does

The input schema is a JSON Schema object attached to a workflow's trigger. It serves two purposes depending on the trigger type:

• Manual triggers — the schema generates the launch form your team sees when they start the workflow from a record. Each field in the schema becomes an input in that form. Required fields must be filled in before the workflow can be launched; optional fields show (optional) next to their label.
• Webhook triggers — the schema validates the incoming payload before any nodes run. If the payload doesn't match, the execution is rejected and no workflow run is created.

Finding and editing the input schema

The input schema can be configured on the trigger node in the workflow builder.

1. Open the workflow and click the trigger node at the top of the graph.
2. In the configuration panel, locate the Input JSON schema section.
3. Click the edit icon to open the JSON editor.
4. Edit the schema and save.

Changes to the input schema take effect immediately for all new executions. If you add a required field to a workflow already in use, anyone launching the workflow — from the UI, via the API, or through the Start Workflow node — must provide that field or the launch will fail.

Writing the schema

The input schema follows standard JSON Schema structure. The top-level object must have type: "object" and a properties map defining each input field. Fields listed in the required array must be provided at launch.

Each field supports the following properties:

• type — the field's data type (see field types below)
• title — the label shown above the field in the manual trigger launch form; defaults to the field key if omitted
• description — placeholder text shown inside the input field in the launch form

Choosing the right field type

The supported standard types are:

• string — a plain text value
• integer — a whole number
• number — an integer or decimal
• boolean — true or false
• object — a JSON object; renders as a section label in the launch form with no editable input

• array — a JSON array; can define items to type the array's contents

   

Using custom field types

Beyond standard JSON Schema types, gaiia supports two custom field types that control both validation and how the field renders in the manual trigger launch form.

Date fields

Use customType: "date" with type: "string" to validate that a value is a date in YYYY-MM-DD format. In the manual trigger form, this renders as a date picker.

{
    "activationDate": {
      "type": "string",
      "customType": "date",
      "title": "Activation Date",
      "description": "Enter Activation Date"
    }
  }

Workflow-populated dropdowns

Use customType: "enumFromWorkflow" to populate a field's options from a workflow's output. In the manual trigger form, this renders as a dropdown whose options are fetched by running the referenced workflow at launch time. This lets you drive dynamic option lists — such as pending billing subscriptions, available product versions, or open work orders — directly from live gaiia data rather than hardcoding values in the schema.

{
    "pendingBillingSubscriptions": {
      "type": "array",
      "customType": "enumFromWorkflow",
      "workflowId": "workflow_wXiEcAgypX6nHDLBHiwHyp",
      "title": "Pending billing subscriptions",
      "items": {
        "type": "object",
        "required": ["id", "value", "label"],
        "properties": {
          "id": { "type": "string" },
          "label": { "type": "string" },
          "value": { "type": "object" }
        }
      }
    }
  }

The workflowId is the Global ID of the workflow that provides the options. You can find it in the URL when viewing that workflow's overview — it begins with workflow_.

Use type: "array" to allow selecting multiple options, or type: "object" for a single selection. The items structure should match whatever the source workflow returns.

Putting it together

Here's a complete example combining a date picker and a workflow-populated multi-select. When this workflow is launched, the team picks an activation date and selects one or more pending billing subscriptions from a dropdown populated in real time by a separate workflow — ensuring only valid, current data enters the workflow before any nodes run.

{
    "type": "object",
    "required": ["activationDate", "pendingBillingSubscriptions"],
    "properties": {
      "activationDate": {
        "type": "string",
        "customType": "date",
        "title": "Activation Date"
      },
      "pendingBillingSubscriptions": {
        "type": "array",
        "customType": "enumFromWorkflow",
        "workflowId": "workflow_wXiEcAgypX6nHDLBHiwHyp",
        "title": "Pending billing subscriptions",
        "items": {
          "type": "object",
          "required": ["id", "value", "label"],
          "properties": {
            "id": { "type": "string" },
            "label": { "type": "string" },
            "value": { "type": "object" }
          }
        }
      }
    }
  }

Understanding validation behavior

The schema is validated before any nodes run. If validation fails, the execution is not created — no partial run, no node executions, no entry in execution history.

The error returned describes what failed:

• Missing required field: must have required property 'fieldName'
• Wrong type: must be integer
• Invalid date format: must be a valid date in the YYYY-MM-DD format

For manual triggers, the launch form enforces required fields in the UI before submission. For webhook and API-triggered executions, the caller receives an error response and should handle it accordingly.

Knowing when to define an input schema

Input schemas are optional, but they're worth defining when:

• The workflow acts on data passed in at launch — formalizing the expected shape makes the workflow easier to call correctly, whether from the UI, the API, or the Start Workflow node
• You want to prevent bad data from reaching your nodes — catching a missing or malformed field at the trigger is cleaner than handling it inside node logic
• The workflow is called by another workflow via the Start Workflow node — a defined schema on the manual trigger documents the expected inputs and makes the contract between workflows explicit
• The manual trigger form needs clear labels — title and description make the launch form readable for team members who didn't build the workflow