JSON Schema for the Data Extensions Schema API

When creating or updating a data extension schema, you define the jsonSchema property using a subset of JSON Schema. This schema acts as a blueprint, describing the properties, data types, and constraints of the object that appears in the extendedFields property of an object.

The JSON Schema has some restrictions and additions specific to Wix, but the general syntax, supported types, and keywords are mostly the same as standard JSON Schema. Wix supports JSON Schema version 2019-09 or higher.

Example JSON Schema

The following example is a JSON Schema you can provide in the jsonSchema field and defines the following custom fields:

• firstName
• lastName
• age

General restrictions

As with standard JSON Schema, to define your fields, you’ll add them as property keys to the properties object. Keep in mind the following restrictions:

• The JSON Schema can't contain more than 256 properties.

• The maximum length of a property key is 64 characters.

• Property keys must start with a letter and can contain only letters, numbers, and underscores.

• The JSON Schema can store a maximum of 10 KB of data per object. This means that each site can store up to 10 KB of data for each extended object.

  For example, if a site extends both the Booking and Checkout objects, it has a total of 20 KB of database storage. It can use up to 10 KB for the Booking object schema and up to 10 KB for the Checkout object schema.

  A schema’s maximum size is calculated based on the field types defined in the schema, including the maximum lengths of all strings and the maximum items of all arrays.

Schema properties

Root-level properties

The following table lists the root-level properties.

The properties object

The following table lists the keys allowed in each property object.

Supported types

The jsonSchema field supports all the basic JSON Schema types, with some restrictions. These restrictions (if any) are detailed below for each type.

string

Size: Varies. Each character is 1 byte.

Restrictions:

• Length: Strings must be between 1 and 10,000 characters long.

Supported formats:

The JSON Schema field supports the following format values:

number

Size: 8 bytes

Restrictions:

• Minimum value: -2⁵³ + 1.
• Maximum value: 2⁵³ + 1.

integer

Size: 4 bytes

Restrictions:

• Minimum value: -2⁵³ + 1.
• Maximum value: 2⁵³ + 1.

object

Size: Varies

Restrictions:

• An object must contain a properties field that defines its properties.
• The object’s properties must follow the restrictions of the other types listed here.
• There is a maximum of 10 nesting levels for an object.

array

Size: An array’s size is determined by the type it contains and its max length. For example, given the following property:

The array contains a maximum of 20 integers. Therefore its total size is:

4 bytes/integer × 20 integers = 80 bytes.

Now consider an array of strings:

The array contains a maximum of 10 strings, each of which can have a maximum length of 10 characters. Since 1 character = 1 byte, we can calculate the array’s total size like this:

(10 characters × 1 byte/character) × 10 = 100 bytes.

Restrictions:

• An array must contain an items key that defines the type of items in the array.
• The items in the array must follow all the restrictions of the other types listed here.
• An array can contain a maximum of 100 items. The maximum number of items must be defined using the maxItems keyword.
• All the items in an array must be the same type.
• Arrays support items of type string, number, integer, boolean, and object.

boolean

Size: 1 byte

Restrictions: None

Supported keywords

The following global JSON Schema keywords are supported:

• Annotations
• Enumerated values

The following global keywords are not supported:

• required
• $defs
• $ref
• readOnly
• writeOnly

Wix-specific keywords

Wix provides a number of keywords that aren't part of standard JSON Schema. You can use these keywords when defining the JSON Schema.

x-wix-pii

Add this keyword to mark a property as PII. A property marked as PII becomes available in GDPR flows.

Here's an example usage of x-wix-pii:

The following field types can be marked as PII:

• strings
• numbers/integers
• arrays of strings
• arrays of numbers

The object you're working with must be PII-enabled in order to mark data extension fields as PII. If it's not, setting x-wix-pii to true will generate an error.

You must mark a field as PII when you create your schema. By default, fields not initially marked as PII are non-PII. You can't change a non-PII field to PII because this is a breaking change. Likewise, you can't change a PII field to non-PII.

If you archive a PII field, any PII data associated with it is deleted.

Defining field permissions

For each property you add to the JSON Schema, you need to define permissions. These permissions define who can read and write to the field.

The permissions you define in the schema assume that the extended entity allows apps to read and write it. If an entity does not allow apps read and write permission, then no group will be able to read and write to the entity, no matter what permissions are defined.

Supported permission values:

• owning-app: The app that defines the extended field.
• apps: All apps installed on the same site.
• users: Wix users that own the site.
• users-of-users: Visitors of sites.

To add permissions to a field, include the Wix-specific x-wix-permissions keyword in the field object. In the value, include two arrays: one specifying the read permissions, and the second specifying the write permissions.

For example:

Editing the schema

Once you’ve saved the schema, there are limits on how you can edit it. You can only make non-breaking changes to the schema. Examples of non-breaking changes include:

• Adding a new field.
• Adding or removing permissions in an existing field.
• Increasing a field’s max limit (for example, the maxLength value in a string field).
• Decreasing a field’s min limit (for example, the value of minimum in a number or integer field).
• Removing a field’s min or max limit entirely.
• Changing settings like title, description and placeholder.

Examples of breaking changes are:

• Removing a field.
• Decreasing a field’s max limit.
• Increasing a field’s min limit.
• Adding a max or min limit to a field that didn’t have one before.

Archive schema fields

You can’t delete fields from your schema, but you can archive them using the x-wix-archived keyword. As with permissions, add x-wix-archived to the field that you want to archive, and set it to true.

For example:

The archived property remains in the database, so you can't reuse its key for another property. Wix filters the archived field during read operations and ignores it during write operations. A field that is archived still takes up the same amount of space in memory and therefore counts towards the 10 KB total your JSON Schema can take up.

All the schema types support archiving. If the archived field has nested fields, the nested fields are also archived. To restore an archived extended field, change the value of x-wix-archived to false or remove it from the schema.

Filtering schema fields

You can make a JSON Schema field filterable by adding the x-wix-filterable keyword to the field, and setting its value to true:

You can then use the field as a filter in the object's standard API query method. For example, a query object might look like this:

Supported operations

Extended fields created using the Data Extension Schema API support the following filter, sort, and aggregation operations:

You can make a maximum of 10 fields filterable. If you archive a filterable field, it can't be used as a filter and no longer counts towards the 10-field maximum. If you unarchive the field, it remains unfilterable by default. You'll need to manually set it as filterable again using the x-wix-filterable keyword.

JSON validation errors

If your JSON Schema doesn't align with the restrictions detailed above, you receive a validation error. Here are a few common errors and what they mean: