About the Data Extension Schema API

A data extension schema allows you to define and validate the structure of custom fields that can be added to Wix objects. A data extension schema acts as a blueprint, describing the properties, data types, and constraints of custom fields. For example, a data extension schema can describe custom shipping data added to the Wix eCommerce Checkout object.

The Data Extension Schema API enables you to:

• Retrieve all the data extension schemas installed on a specific site.
• Create and update user-defined schemas for a specific site.
• Delete fields from user-defined schemas.

Before you begin

• App schema plugin extensions, including their JSON schemas, are created and maintained in the app dashboard. You can use the Data Extension Schema API to retrieve schema plugins. However, the Data Extension Schema API doesn't support creating and updating schema plugins. Learn more about when to use Schema plugins.
• Before creating a data extension schema, check the object to make sure you don’t add fields that already exist. Only use the data extension schema when an object doesn’t have a field to support your data.

Supported objects

You can extend the following objects:

Extended fields behave like native fields. However, not all objects support operations such as filtering. To learn more, see The JSON Schema.

How extended fields work

Supported objects contain an extendedFields property. When you create a data extension schema, you define extended fields that are stored in extendedFields. Extended fields can exist at the following levels:

• Root level: Extended fields appear directly in the object's extendedFields property.
• Nested in an existing field: Extended fields appear in the extendedFields property of items in an array. For example, each line item in an order has its own extendedFields property.

FQDNs

A Fully Qualified Domain Name (FQDN) is a unique identifier for a Wix object type. When creating or managing data extension schemas, you use the FQDN to specify which object type to extend.

FQDNs follow this pattern: wix.<service>.<version>.<object>

For example:

• wix.ecom.v1.order identifies the eCommerce Order object
• wix.bookings.v2.booking identifies the Bookings object

Use a wildcard (*) in place of the version number:

This ensures your schema remains valid even if Wix releases a new version of the API.

Namespaces

The extendedFields property contains a nested namespaces object that keeps extended fields from different sources separate:

• _user_fields: Contains extended fields from user-defined schemas, created through this API or the site dashboard.
• App namespaces: Contains extended fields defined using a schema plugin extension.

For example, a Checkout object might have extended fields from both sources:

When reading or writing extended field data, always reference the correct namespace.

Use cases

• Retrieve a list of all data extension schemas for the Wix eCommerce Checkout object
• Add a field to a user-defined data extension schema

Terminology

• Data extension schema: A JSON Schema defining the data structure of the custom fields to add to a Wix object.
• Extended fields: Custom fields defined by a schema added to the extendedFields field of an object.
• User-defined schema: The schema created when a Wix user creates extended fields for a specific site. This schema uses the _user_fields namespace.
• Schema plugin extension: Specific functionality that extends a Wix object with custom fields for a specific app.
• FQDN: Fully qualified domain name, a unique identifier for a Wix object. Learn more about FQDNs.
• Namespace: A unique identifier for your app or project. Learn more about namespaces.