About the Action Input Schema
When an automation is triggered, Wix passes data from the trigger payload to your service so it can perform your action. You tell Wix exactly what data your action requires by defining the input schema. The input schema is a JSON Schema that allows you to define the data types your action needs. You must provide the input schema when you configure your action in your app's dashboard.
If the trigger payload fields do not match the fields in your input schema, your action will not run when the automation is triggered.
Schema types and structure
The input schema supports the following data types:
- Strings. You can also format strings as emails, dates, etc.
- Numbers
- Integers
- Booleans
- Arrays
- Objects
Each key-value pair in the schema defines a field or set of fields in the action UI. The basic schema below shows a string, integer, and boolean property:
1
The default UI created by the properties defined above looks like this:
All input schema must have a top-level type key with a value ”object”, a properties object that contains all the field definitions, and a required array that contains the fields which are required for the action configuration (such as the name and age fields in the example above). Each key in properties must have, at minimum, a type and title key defined. Object and array fields require additional keys.
See the tables below for the expected input schema structure.
Tip: To create a starter schema using sample values and required properties, use the Generate from Sample Data option. You can then fill in the rest of the schema as needed.
Root-level properties
These properties are at the schema's root level.
The input schema supports schema composition keywords such as allOf, anyOf, and oneOf.
Important: Wix does not validate breaking changes to an input schema that uses composition. To ensure the user does not make errors when configuring an action that uses composition in its schema, we recommend performing the validation on your end.
| Property | Data Type | Description |
|---|---|---|
$schema | string | When you save the action configuration, Wix overrides this property to set it to "http://json-schema.org/draft-07/schema". |
type | string | Required. Must be "object". |
properties | object | Required. Object containing the key-object pairs that define the fields in the action configuration. See the properties object below for details. |
required | array | List of property keys that must be provided to the action. In the action configuration UI on the user's site, these will be marked as required fields. |
additionalProperties | boolean | When you save the action configuration, Wix overrides this property to set the value to true, which allows additional, unspecified properties to be sent in the payload. |
The properties object
The properties object contains the key-object pairs that make up the bulk of the data passed to the action. The key name can include only alphanumeric characters or underscores (A-Z, a-z, 0-9, _). It cannot start with an underscore.
Each paired object contains display and validation metadata. This table gives the expected data structure for an object in properties:
| Property | Data Type | Description |
|---|---|---|
type | string | Required. Supported values: "string", "number", "integer", "boolean", "array", "object".Expected data type of the payload property. See the input schema Storybook for more details about each type. |
title | string | Required. Display name for the property. Shown to users when they create or edit an automation. |
examples | array | Example values, displayed as placeholders when users test certain automation actions. Must be the same data type defined in type. |
format | string | Validated string format. Used only when type is "string". See built-in formats (from the JSON Schema 2020-12 docs) for supported formats.If set to "uuid", the property can be connected to a site's contacts. |
identityType | string | Supported values: "contact", "member", "visitor".If you add this property to the input schema, the action becomes available for triggers that use contactID, and its icon appears in the list of actions available when such a trigger is selected. If you do not add this property, the action is not available for these triggers and does not appear in the possible list of actions. Max: 1 payload property. |
items | object | Required if type is "array". Omitted for other data types. Object that contains array metadata. See the items object below for details. |
oneOf | array | Creates a field that lets a user select one from multiple options. See the oneOf object below for details. |
properties | object | Required if type is "object". Omitted for other data types.Contains key-object pairs that define the properties of the nested object. Accepts the same data as the 1st-level properties object and may contain strings, numbers, integers, booleans, or nested objects. |
required | array | Used only when the type is "object" or "array". List of property keys that must be provided to the action service. |
uniqueItems | boolean | Used only when the type is "array". Allows a field to be added only once to the action configuration UI. |
The items object
items is an object that contains an array schema.
| Property | Data Type | Description |
|---|---|---|
type | string | Required. Defines the expected data type of the array. |
properties | object | Required if type is "object". Contains key-object pairs that define the properties of the array objects. Accepts the same data as the 1st-level properties object, but can contain only strings, numbers, integers, or booleans. |
required | array | Used only when the type is "object". List of property keys that must be provided to the action service. |
The oneOf object
oneOf is an array of objects. It defines a field in which a user can choose one of multiple options.
| Property | Data Type | Description |
|---|---|---|
type | string | Required. Defines the expected data type of the option. Must match the parent type defined for the entire field. |
title | string | Required. The option value displayed to users. This value can be translated into another language. |
const | varies | Required if type is "string". Strings must be in English. The option value that is sent to the backend for validation. |
description | string | Provides more information about an option. This value can be translated into another language. |
Editing a saved input schema
Once you publish the action with your app, Wix enforces the following limits on changes you can make to the action's input schema. Once the action is saved, you can't:
- Add required fields to the schema.
- Mark existing non-required fields as required.
- Change a field’s type.
- Change a field’s format.
- Remove or change a field’s identity type.