A data extension schema is the JSON schema within a schema plugin extension defining extendedFields
that are added to a Wix API's service object. For example, a data extension schema might add custom shipping data to the Wix eCommerce Checkout object.
The Data Extension Schema API enables you to:
Learn more about reading and writing schema plugin fields
A user-defined data extension schema is created when a Wix user (site owner or collaborator) creates their own extended fields. For example, Wix users can add their own fields to the checkout flow in the site's dashboard under Settings > Checkout > Checkout form and editing the checkout form:
It’s important to note the following points before starting to code:
extendedFields
._user_fields
.This article shares some possible use cases you could support, as well as an example flow that could support each use case. You're certainly not limited to these use cases, but they can be a helpful jumping off point as you plan your implementation.
If your functionality requires access to fields that have been added to an object, you might want to retrieve all of the schemas at once. For example, displaying the returned fields in a widget.
entityFqdn
in most events. The Wix eCommerce Checkout FQDN is wix.ecom.v1.checkout
.Display a site-specific field, such as alcohol by volume (ABV) for whiskey orders, alongside fields from Wix eCommerce Orders, in a widget.
entityFqdn
in most events. The Wix eCommerce Order FQDN is wix.ecom.v1.order
.wix.ecom.v1.order
FQDN and _user_fields
namespace to check if a user-defined schema exists._user_fields
namespace, as relevant:
_user_fields
namespace schema exists, call Create Data Extension Schema with the wix.ecom.v1.order
FQDN, the _user_fields
namespace and the new JSON schema._user_fields
namespace schema already exists, call Update Data Extension Schema with the wix.ecom.v1.order
FQDN, the _user_fields
namespace and the updated JSON schema.Note: Once you have added at least one user-defined field, you should call List Data Extension Schemas every time a user navigates to your widget, to collect and display the user fields.
Schema ID.
FQDN of the entity this schema extends.
Namespace for this schema. For example, an app creating schemas might use their app name as a namespace.
When a site owner creates a user-defined schema, the namespace is: _user_fields
.
Schema definition in JSON schema format with the following vocab extension:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://wixapis.com/v1/json-schema/extensions",
"$vocabulary": {
"https://wixapis.com/v1/json-schema/extensions/vocab/data-extensions": true
},
"$dynamicAnchor": "meta",
"title": "Wix' data-extensions vocabulary meta schema",
"type": [
"object",
"boolean"
],
"properties": {
"x-wix-permissions": {
"type": "object",
"description": "list of identity types that are allowed reading schema properties",
"properties": {
"read": {
"type": "array",
"items": {
"type": "string",
"enum": [
"apps",
"owning-app",
"users",
"users-of-users"
]
}
},
"write": {
"type": "array",
"items": {
"type": "string",
"enum": [
"apps",
"owning-app",
"users",
"users-of-users"
]
}
}
}
},
"x-wix-display": {
"type": "object",
"description": "field display properties",
"schema": {
"properties": {
"placeholder": {
"type": "string",
"maxLength": 255,
"description": "placeholder text for input fields"
},
"label": {
"type": "string",
"maxLength": 255,
"description": "label of the input fields"
},
"hint": {
"type": "string",
"maxLength": 255,
"description": "a short explanation that appears next to the input field"
}
}
}
}
}
}
Date and time the schema was last updated.
Date and time the schema was created.
Revision number, which increments by 1 each time the schema is updated. To prevent conflicting changes, the existing revision must be used when updating a schema.
Maximum allowed schema size in bytes.
Current schema size in bytes.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates a user-defined data extension schema, overriding the existing data.
You can only call this method when authenticated as a Wix app or Wix user identity.
Schema to update.
Updated schema.
curl -X PUT \
'https://www.wixapis.com/schema-service/v1/schemas' \
-H 'Content-type: application/json' \
-H 'Authorization: <AUTH>' \
-d '
{
"dataExtensionSchema": {
"id": "01ea0c8d-80b8-46e3-bfda-611b3678545b",
"fqdn": "wix.ecom.*.order",
"namespace": "_user_fields",
"jsonSchema": {
"additionalProperties": false,
"properties": {
"myCustomField1": {
"maxLength": 75,
"type": "string",
"x-wix-created-date": "2024-10-08T12:13:38.592731806Z",
"x-wix-permissions": {
"read": [
"users-of-users",
"users",
"apps"
],
"write": [
"users"
]
}
},
"myCustomField2": {
"maxLength": 100,
"type": "string",
"x-wix-created-date": "2024-10-08T12:13:38.592731806Z",
"x-wix-permissions": {
"read": [
"users-of-users",
"users",
"apps"
],
"write": [
"users"
]
}
}
}
},
"revision": "2"
}
}
'
{
"dataExtensionSchema": {
"id": "01ea0c8d-80b8-46e3-bfda-611b3678545b",
"fqdn": "wix.ecom.*.order",
"namespace": "_user_fields",
"jsonSchema": {
"properties": {
"myCustomField1": {
"type": "string",
"maxLength": 75,
"x-wix-permissions": {
"read": ["users-of-users", "users", "apps"],
"write": ["users"]
},
"x-wix-created-date": "2024-10-08T12:13:38.592731806Z"
},
"myCustomField2": {
"type": "string",
"maxLength": 100,
"x-wix-permissions": {
"read": ["users-of-users", "users", "apps"],
"write": ["users"]
},
"x-wix-created-date": "2024-10-08T12:30:44.854371962Z"
}
},
"additionalProperties": false
},
"updatedDate": "2024-10-08T12:35:50.909Z",
"createdDate": "2024-10-08T12:13:38.639Z",
"revision": "3",
"maxLimitBytes": 10000,
"currentSizeBytes": 175,
"extensionPoint": "ROOT"
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of global and user-defined data extension schemas for a given FQDN.
Namespaces within the given entity.
Additional fields that are hidden by default. For example, fields with "x-wix-archived": true
.
Extension points within the given entity.
Requested schemas.
curl -X GET \
'https://www.wixapis.com/schema-service/v1/schemas?fqdn=wix.ecom.%2A.order' \
-H 'Content-type: application/json' \
-H 'Authorization: <AUTH>'
{
"dataExtensionSchemas": [
{
"id": "01ea0c8d-80b8-46e3-bfda-611b3678545b",
"fqdn": "wix.ecom.*.order",
"namespace": "_user_fields",
"jsonSchema": {
"properties": {
"myCustomField1": {
"type": "string",
"maxLength": 50,
"x-wix-permissions": {
"read": ["users-of-users", "users", "apps"],
"write": ["users"]
},
"x-wix-created-date": "2024-10-08T12:13:38.592731806Z"
}
},
"additionalProperties": false
},
"updatedDate": "2024-10-08T12:13:38.639Z",
"createdDate": "2024-10-08T12:13:38.639Z",
"revision": "1",
"maxLimitBytes": 10000,
"currentSizeBytes": 50,
"extensionPoint": "ROOT"
}
]
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a user-defined data extension schema.
You can only call this method when authenticated as a Wix app or Wix user identity.
Schema to create.
Created schema.
curl -X POST \
'https://www.wixapis.com/schema-service/v1/schemas' \
-H 'Content-type: application/json' \
-H 'Authorization: <AUTH>' \
-d '{
"dataExtensionSchema": {
"fqdn": "wix.ecom.*.order",
"namespace": "_user_fields",
"jsonSchema": {
"properties": {
"myCustomField1": {
"type": "string",
"maxLength": 50,
"x-wix-permissions": {
"read": [
"users-of-users",
"users",
"apps"
],
"write": [
"users"
]
}
}
}
}
}
}'
{
"dataExtensionSchema": {
"id": "01ea0c8d-80b8-46e3-bfda-611b3678545b",
"fqdn": "wix.ecom.*.order",
"namespace": "_user_fields",
"jsonSchema": {
"additionalProperties": false,
"properties": {
"myCustomField1": {
"maxLength": 50,
"type": "string",
"x-wix-created-date": "2024-10-08T12:13:38.592731806Z",
"x-wix-permissions": {
"read": ["users-of-users", "users", "apps"],
"write": ["users"]
}
}
}
},
"updatedDate": "2024-10-08T12:13:38.639Z",
"createdDate": "2024-10-08T12:13:38.639Z",
"revision": "1",
"maxLimitBytes": 10000,
"currentSizeBytes": 50,
"extensionPoint": "ROOT"
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a data extension schema is created.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.data_extensions.v1.data_extension_schema
.
Event name. Expected created
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.data_extensions.v1.data_extension_schema_created",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "53eebc77-16ce-4bea-a558-3b793d01ed59",
"entityFqdn": "wix.data_extensions.v1.data_extension_schema",
"slug": "created",
"entityId": "01ea0c8d-80b8-46e3-bfda-611b3678545b",
"createdEvent": {
"entityAsJson": "{\"id\":\"01ea0c8d-80b8-46e3-bfda-611b3678545b\",\"fqdn\":\"wix.ecom.*.order\",\"namespace\":\"_user_fields\",\"jsonSchema\":{\"properties\":{\"myCustomField1\":{\"type\":\"string\",\"x-wix-permissions\":{\"read\":[\"users-of-users\",\"users\",\"apps\"],\"write\":[\"users\"]},\"x-wix-created-date\":\"2024-10-08T12:13:38.592731806Z\",\"maxLength\":50.0}},\"additionalProperties\":false},\"updatedDate\":\"2024-10-08T12:13:38.639Z\",\"createdDate\":\"2024-10-08T12:13:38.639Z\",\"revision\":\"1\",\"maxLimitBytes\":10000,\"currentSizeBytes\":50,\"extensionPoint\":\"ROOT\"}"
},
"eventTime": "2024-10-08T12:13:38.779083434Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "1"
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a data extension schema is deleted.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.data_extensions.v1.data_extension_schema
.
Event name. Expected deleted
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.data_extensions.v1.data_extension_schema_deleted",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a data extension schema is updated.
Unique event ID. Allows clients to ignore duplicate webhooks.
Fully qualified domain name of the entity associated with the event. Expected wix.data_extensions.v1.data_extension_schema
.
Event name. Expected updated
.
ID of the entity associated with the event.
Event timestamp.
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).
If present, indicates the action that triggered the event.
Event information.
The data payload will include the following as an encoded JWT:
{
"data": {
"eventType": "wix.data_extensions.v1.data_extension_schema_updated",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>",
// The identity field is sent as a stringified JSON
"identity": {
"identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP
"anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR
"memberId": "<memberId>", // in case of MEMBER
"wixUserId": "<wixUserId>", // in case of WIX_USER
"appId": "<appId>" // in case of APP
}
}
}
{
"id": "bf73a5be-d435-4402-a42a-8c041e9d659c",
"entityFqdn": "wix.data_extensions.v1.data_extension_schema",
"slug": "updated",
"entityId": "01ea0c8d-80b8-46e3-bfda-611b3678545b",
"updatedEvent": {
"currentEntityAsJson": "{\"id\":\"01ea0c8d-80b8-46e3-bfda-611b3678545b\",\"fqdn\":\"wix.ecom.*.order\",\"namespace\":\"_user_fields\",\"jsonSchema\":{\"properties\":{\"myCustomField1\":{\"type\":\"string\",\"maxLength\":75.0,\"x-wix-permissions\":{\"read\":[\"users-of-users\",\"users\",\"apps\"],\"write\":[\"users\"]},\"x-wix-created-date\":\"2024-10-08T12:13:38.592731806Z\"},\"myCustomField2\":{\"type\":\"string\",\"maxLength\":100.0,\"x-wix-permissions\":{\"read\":[\"users-of-users\",\"users\",\"apps\"],\"write\":[\"users\"]},\"x-wix-created-date\":\"2024-10-08T12:30:44.854371962Z\"}},\"additionalProperties\":false},\"updatedDate\":\"2024-10-08T12:35:50.909Z\",\"createdDate\":\"2024-10-08T12:13:38.639Z\",\"revision\":\"3\",\"maxLimitBytes\":10000,\"currentSizeBytes\":175,\"extensionPoint\":\"ROOT\"}",
"modifiedFields": {
"updatedDate": "2024-10-08T12:30:45.011Z",
"revision": "2"
}
},
"eventTime": "2024-10-08T12:35:50.996331444Z",
"triggeredByAnonymizeRequest": false,
"entityEventSequence": "3"
}