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 the app dashboard.

Top-level properties

When you create a new action, the best way to start building the input schema is to use the Generate from Sample Data button and enter a sample JSON object. This automatically creates a JSON schema for you, with the correct formatting and keywords.

If you already have your own sample data, feel free to enter that. Otherwise, press the tab key to use the data that already appears in the modal:

Once you add sample data, click Convert to schema. This generates a schema like the following:

If you used your own sample data, you’ll have different key-object pairs inside the properties object. But for now, let’s ignore the nested objects and look only at the top-level.

Every input schema that you generate has 3 top-level keys:

• type: This designates the type of the overall schema object, and always has a value of "object". This key is required, so don’t remove it and don’t change its value.
• properties: This object contains a set of nested objects that define your action’s input fields. properties is a required top-level key.
• required: This is an optional, but recommended array that lists the properties that your action must always receive in the payload. If the payload passed to your action is missing any of the fields listed in required, the action won’t run.

The table below summarizes these top-level keys:

The properties object

The properties object is responsible for defining your action’s input. The object contains one or more key-object pairs, each of which corresponds to an input field. For example, assume you have the following key-object pairs in properties:

The action will have two input fields:

• A string field called "Customer name".
• An integer field called "Total previous sessions".

Both input fields are required, so if one is missing from the received payload, the action won’t run.

Property key names can include only alphanumeric characters or underscores (A-Z, a-z, 0-9, _). They cannot start with underscores. Every paired object must contain the following two keys:

• type: Defines the field data type. Accepted values include standard JSON types or Wix custom types. The table below summarizes these types and we discuss them in detail in the following section.
• title: Sets the field title. Users see this title when they set up your action in the Automations Builder.

In addition to these 2 required keys, we recommend adding the description key. The value of description is a string that briefly describes the field. Including a description also allows you to add a note to the field.

The example input schema above shows two very simple properties. Most properties you add to your input schema include more keywords. In the next section, we discuss each data type and its possible keywords.

The table below lists the possible keys for each data type:

The items object

items is an object that contains an array schema.

The oneOf array

Using oneOf as a property defines a field in which a user can choose one of multiple options. Note that this is different from the use of oneOf in schema composition.

Define a multiple choice field by creating a property containing a oneOf array. Each option you want to display is an object in this array. The table below shows the expected structure of these objects.

Data types

This section details each of the possible data types you can assign to properties, explains how to define each one, and gives examples of available keywords for the property.

String property

To define an input schema property as a string, set its type key to "string".

String properties support all the JSON schema built-in formats. To format a string, add the optional format key to the property object.

Below are 2 examples of string properties. The first is a simple string with no format specified. The second specifies the uuid format:

The first property creates a field in the action UI that accepts any kind of string input. The second property also creates a field that accepts string input, but ensures that the input is formatted as a UUID. If a user tries to input the input other than a UUID into Customer ID, they’ll get an error:

Number property

To define a number property, set type to "number".

Here’s an example:

This creates a basic input field that accepts numerical input from the user.

Integer property

To define an integer property, set type to "integer".

Here’s an example:

This creates a basic input field that accepts integer input from the user.

Boolean property

To define a boolean property, set type to "boolean".

Here’s an example:

This creates a toggle button for the field.

Array property

To define an array property, set type to "array".

In addition to the type and title keys, an array property must include an items key. The value of the items key is an object that defines the data type of the elements in the array. If the elements are objects, it also defines the following:

• A nested properties object. This defines the properties of the array objects and is mandatory.
• A nested required array. This defines the properties that each element in the array must contain. At this level, required is optional.

Here’s a simple example of an array property:

In this case the array elements are numbers, so items only needs to define the type key. The luckyNumbers array creates an array field that allows users to add new fields in the action UI:

Here’s a more complex example that uses objects as array elements:

Here items defines the expected properties of each object in the array. It also defines the required array. This tells Wix that when the action receives an array of guest objects, it expects each of those objects to contain at least the guest name and email. If the action receives an array of objects, and one or more of those objects is missing a required field, the action won’t run.

The example above creates an array field that looks like this:

Object property

To define an object property, set type to "object".

In addition to type and title, you’re required to define a properties object for the object property. This nested properties object defines the fields inside your object property.

Optionally, you can define a required array to indicate which nested object properties are mandatory.

Here’s an example of an object property:

An object property creates a field for each nested property in the action UI. You can set individual fields within the object as dynamic.

OneOf property

You can use a oneOf to define a dropdown field in which a user can choose one of multiple options. Use a oneOf field instead of the JSON enum.

To define a oneOf, set type to "string"and add an array called oneOf to the property. Each object in oneOf must contain a "title" key. title defines the label of the choice in the dropdown.

If the dropdown options are strings, each object also requires a "const" key. This key defines a name for the option that is used in the backend and for translations.

In addition to title and const, you may also add a description key to give a brief explanation of the property. However, the description will only be displayed if the multiple choice element is in a radio button format.

Here’s an example of using oneOf to create a dropdown:

The property above creates a dropdown field like this:

Using advanced JSON schema features

In addition to basic JSON schema types and keywords, the action input schema supports more advanced features. This allows you to build more complex schemas, which in turn gives users greater control and customization over the action.

Schema composition

You can apply the following keywords to the input schema:

• allOf
• anyOf
• oneOf

Be aware that Wix doesn’t validate breaking changes to an input schema that uses composition. To ensure the user doesn’t make errors when configuring an action that uses composition in its schema, we recommend validating the schema on your end.

Conditionals

The input schema supports the use of conditional keywords if, then, and else. These keywords allow you to alter parts of your schema depending on user input.

Typically, if-then-else subschemas result in users seeing different fields depending on the selections they make while configuring your action.

Consider this example:

When a user configures the action based on the above schema, they can select either Card or Bank transfer as an option. If they select Card, they see the following fields:

However, if the user instead selects Bank transfer, they see a different set of fields:

Using if-then-else structures allow your schema and its corresponding UI to respond more dynamically to user input.

Wix-specific keywords

The input schema accepts custom keywords made by Wix. We go over these special keywords below and explain how to apply them to the input schema.

identityType

Add the identityType key to a property to connect it to a contact ID. Specify either "contact" or "visitor" as the value.

You can only add the identityType key to fields with type string and format uuid.

Here’s an example:

Full schema example

Below is an example of a complete action input schema. You can copy all or part of the example to get started creating your own schema.