> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Payload Schema

## Article: Payload Schema

## Article Link: https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/automations/triggers/payload-schema.md

## Article Content:

# Payload Schema

When you configure your app's triggers, you must provide a payload schema.
The payload schema defines the required and validated fields in your event payloads,
and it's used to display available options to your users
when they configure their automations.

A payload schema allows you to define scheduled events
and can give your users enriched payloads
by linking your trigger to a site contact.
Wix also uses the payload schema
to determine the available actions for a trigger.

The payload schema must be a [JSON Schema](https://json-schema.org/) object.
See the tables in [Schema Properties](#schema-properties) (below)
for the expected structure.

<blockquote class="tip">

__Tip:__
To create a starter schema with sample values and required properties,
use the **Convert from Payload** option.
You can then fill in the rest of the schema as needed.

![Screen shot of the "Configure the payload schema" section of the trigger configuration page. The "Convert from Payload" button is highlighted.](https://wixmp-833713b177cebf373f611808.wixmp.com/images/payload-schema-md_build-apps-portal_develop-your-app_extensions_backend-extensions_automations_triggers_assets_automations__json-schema-convert-from-payload.png)

</blockquote>

## Connecting payload schema properties

When you configure your trigger to connect a contact ID or a scheduled event,
you're indicating that Wix can handle your trigger in a specialized way
and present additional automation configuration options to users.
The requirements for each property, as well as how Wix handles these changes,
are covered in this section.

### Contact ID property

You can connect a payload property to a contact ID
when the property's value will always be a contact ID from Wix.
You can retrieve the relevant contact ID using the
[Contacts API](https://dev.wix.com/docs/rest/crm/members-contacts/contacts/introduction.md).

**Requirements**: <br />
This option is available only for properties where the type is `"string"`
and the format is `"uuid"`.

**Effect on your user's automations**: <br />
Connecting a payload property to a contact ID
allows users to use the related contact information
(such as name, emails, or phone numbers) in their automation actions.
It also allows them to email the contact as an automation action.

### Scheduled event property

You can set a payload property as a scheduled event
when the property's date-time will always be at some point in the future,
relative to the time the event is reported.
Some examples of scheduled event properties are
an invoice due date or a session start time.
For more information, see
[Overview of events](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/automations/triggers/about-triggers.md).

**Requirements**: <br />
This option is available only for properties
where the type is `"string"` and the format is `"date-time"`.

**Effect on your user's automations**: <br />
Setting a payload property as a scheduled event
allows users to configure automations to run before,
at the time of, or after the time specified in the payload.

## Schema properties

These properties are at the schema's root level:

| Property               | Data type | Description                                                                                                                                                                 |
| ---------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$schema`              | string    | When you save the trigger 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 payload property metadata as key-object pairs. See [the `properties` object](#the-properties-object) below for details.                       |
| `required`             | array     | List of property keys that are required to be present in the [reported event](https://dev.wix.com/docs/rest/business-management/automations/triggers/triggered-events/report-event.md) payload.          |
| `additionalProperties` | boolean   | When you save the trigger 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

`properties` is an object that contains key-object pairs.

The key name can include only alphanumeric characters or underscores
(`A-Z`, `a-z`, `0-9`, `_`).
It cannot start with an underscore.

The paired object contains display and validation metadata.
This table gives the expected data structure:

| Property       | Data type | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`         | string    | <p>Supported values: `string`, `number`, `integer`, `boolean`, `array`, `object`.</p> <p>_Required_. Expected data type of the payload property.</p> <p>**Note**: Only the 1st-level `properties` object supports `"object"` and `"array"` types.</p>                                                                                                                                                                                                                                                                                                         |
| `title`        | string    | _Required_. Display name for the property. Shown to users when they create or edit an automation.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `examples`     | array     | <p>Example values, displayed as placeholders when users test certain automation actions. Must be the same data type defined in `type`.</p> <p>Required in the 1st-level `properties` object. Omitted in the 2nd-level `properties` object.</p>                                                                                                                                                                                                                                                                                                                |
| `format`       | string    | <p>Validated string format. Used only when `type` is `"string"`. See [built-in formats](https://json-schema.org/understanding-json-schema/reference/string.html#built-in-formats) (from the JSON Schema 2020-12 docs) for supported formats.</p> <p>If set to `"uuid"`, the property can be connected to a site's contacts. This allows Wix to enrich the payload with contact data and allows the site owner to use actions that work with their contacts.</p> <p>If set to `"date-time"`, the property can be used to add support for scheduled events.</p> |
| `identityType` | string    | <p>Supported value: `contact`</p> <p>If the property is specified with **Connect a property to a contactId**, `identityType` is automatically set to `"contact"`. In all other cases, `identityType` is omitted.</p> <p>Limited to 1 payload property.</p>                                                                                                                                                                                                                                                                                                    |
| `futureDate`   | boolean   | <p>If the property is specified with **Allow scheduled events with predefined date & time**, `futureDate` is automatically set to `true`. In all other cases, `futureDate` is omitted.</p> <p>Limited to 1 payload property.</p>                                                                                                                                                                                                                                                                                                                              |
| `items`        | object    | <p>Object that contains a list of array items.</p> <p>Required if `type` is `"array"`. Omitted for other data types. See [the `items` object](#the-items-object) below for details.</p>                                                                                                                                                                                                                                                                                                                                                                       |
| `properties`   | object    | <p>Object containing 2nd-level payload property metadata as key-object pairs. Accepts the same data as the 1st-level `properties` object, but can contain only strings, numbers, integers, or booleans.</p> <p>Required if `type` is `"object"`. Omitted for other data types.</p>                                                                                                                                                                                                                                                                            |
| `required`     | array     | <p>List of property keys that are required to be present in the [reported event](https://dev.wix.com/docs/rest/business-management/automations/triggers/triggered-events/report-event.md) payload.</p> <p>Used only  when `type` is `"object"` or `"array"`.</p>                                                                                                                                                                                                                                                                                                                           |

### The `items` object

`items` is an object that contains an array schema.

| Property     | Data type | Description                                                                                                                                                                                                                                                                               |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`       | string    | _Required_. Must be set to `"object"`.                                                                                                                                                                                                                                                    |
| `properties` | object    | _Required_. Object containing 2nd-level payload property metadata as key-object pairs. Accepts the same data as the 1st-level `properties` object. See [the `properties` object](#the-properties-object) above for details. |
| `required`   | array     | List of property keys that are required to be present in the [reported event](https://dev.wix.com/docs/rest/business-management/automations/triggers/triggered-events/report-event.md) payload.                                                                                                                        |