Developer Preview
This feature is currently in developer preview. Features in developer preview are subject to change and are not intended for use in production.
The extended fields feature allows an app to extend the objects used by Wix's APIs with additional fields. You can use these fields to store data that isn't supported by the object. For example, you can extend the Booking object to include extra data. Extended fields are added to an app in the Wix Dev Center. Once extended fields are added for a particular object, they can be read and written using that object's API endpoints. This article explains how to add extended fields to an app and the details of reading and writing extended fields using APIs.
To add extended fields to an app's API object, do the following:
- Open the Wix Dev Center and select the app you want to add extended fields for.
- In the left sidebar, click Extensions.
- Click Create Extension.
- Type
extended-fields
in the search bar. Choose the object you want to add extended fields to and click Create.
- If this is the first time you're adding extended fields to the app, you're prompted to create a namespace for the app. This namespace is used when reading and writing any extended fields created for the app.
- Use the JSON Editor to define the extended fields you want to add the object in JSON Schema format.
The editor's linter indicates if there are any errors in the JSON Schema.
- Once your extended fields are defined, click Save.
Important: Once you add an extended field to an app, it can't be removed. You can archive an extended field to prevent it from being read or written using APIs.
Once you add extended fields to an app, you can read and write them using the API endpoints for the object.
To read extended field data, use the same API endpoint used to retrieve the object you extended. Your call returns any extended field data your app added to the object as well as data that you have permission to access that was added by other apps or site owners.
Extended fields are added to the main object in the extendedFields
field. This field's value is an obejct containing a namespaces
field. The namespaces
object contains the extended field data for each app that has extended the main object. Each app in this object is identified by its namespace. Data added by site owners is included under the _user_defined
namespace.
For example:
Copy Code
{"extendedFields": {"namespaces": {"@account1/myApp": {"myField": "My field value","myField2": "Another field value for the same app"},"@account2/anotherApp": {"appField": "A field value for a different app"},"_user_defined": {"userField": "A field value added by a site owner"}}}}
Note: When you read an object with extended fields, you can only retrieve the data that your app has permissions to read. For example, if the extended fields are defined by the owning app without adding
"apps"
to the read permissions, other apps won't see those extended fields when they retrieve the object.
There are 2 ways to write extended field data: standard endpoints and dedicated endpoints.
You can write extended field data using the same API endpoints used to write the object you extended. Include the new or updated extended field data in the extendedFields
field of the object, as in the example above. To delete the value of an extended field, set its value to null
.
APIs that support extended fields also have a dedicated "Update Extended Fields" endpoint. You can use this endpoint to update only the extended fields of an object. If the object you extended has a revision
field, you don't need to pass it when updating extended fields using a dedicated endpoint. This endpoint may require a permission scope that's different from the scope required to update the object itself. Dedicated endpoints use a slightly different data format. The namespace of the app whose data you want to update and the data itself are separated in the request body.
Example dedicated endpoint request body:
Copy Code
{"namespace": "@account-name/app1","namespaceData":{"myField": "my field value"}}
When you update extended fields using either a standard or dedicated endpoint, the standard "Updated" webhook for the extended object is triggered. The webhook payload contains the updated object including the extendedFields
field. The payload only includes data for extended fields whose read permissions include "apps"
. The payload also includes a boolean value called _has_more_data
. This value is set to true
if extended fields were updated that don't have "apps"
in their read permissions. In this case, you can see the updated extended fields by reading the object using the appropriate API endpoint.
Here is an example of the extendedFields
property in a webhook payload:
Copy Code
{// ... Other object data"extendedFields": {"namespaces": {"@account-name/app1": {"myField": "my field value","myField2": "another field value"}},"_has_more_data": true}}
Extended fields are defined using a subset of JSON schema. There are some general restrictions on the JSON schema to keep in mind when defining extended fields:
- Extended field schemas 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 maximum storage size for extended fields for an object per app is 10 KB. This means that each site that installs your app can store up to 10 KB of extended field data for each object that your app extends. This limitation is applied to the schema. It's calculated based on the fields defined in the schema including the maximum lengths of all strings and the maximum items of all arrays.
The extended fields feature supports all the basic JSON schema types with some restrictions, as follows:
The string
type is used to define a JSON schema string. Please note the following restrictions to the string
definition:
- Length: Strings must be between 1 and 10000 characters long. The maximum length of a
string
extended field must be defined using themaxLength
keyword. - Format: The following formats are supported:
- Hostnames
- Resource identifiers
- Dates. Only
date
,date-time
, andtime
values are supported. email
: A custom Wix value indicating a valid email address. The maximum length of an email address is 254 characters.phone
: A custom Wix value indicating a valid phone number.single-line
: A custom Wix value. By default, allstring
extended fields are considered multi-line text. Thesingle-line
format indicates a field that can only contain a single line of text. The string must end with a newline character (\n
).Note: If a string is defined as
single-line
, the format can be removed later. However, if a string is created as multi-line text, the format can't be changed later tosingle-line
.
The number
and integer
types are used to define a JSON schema numeric type. The minimum value for a numeric extended field is -2^53 + 1
and the maximum value is 2^53 + 1
.
The object
type is used to define a JSON schema object. Please note the following restrictions to the object
definition:
- An
object
extended field's schema must contain aproperties
field that defines the properties of the object. - The properties of an object must follow the all the restrictions of the other extended field types.
- There is a maximum of 10 nesting levels for an object.
The array
type is used to define a JSON schema array. Please note the following restrictions:
- An
array
extended field's schema must contain anitems
field that defines the items in the array. - The items in the array must follow the all the restrictions of the other extended field types.
- The maximum length of an array is 100 items. The maximum number of items of an
array
extended field must be defined using themaxItems
keyword. - All the items in an array must be the same type.
- Arrays can only contain items of these types:
string
,number
,integer
, andboolean
.
The boolean
type is used to define a JSON schema boolean. There are no restrictions on the boolean
type object.
The following global JSON schema keywords are supported:
The following global keywords are not supported:
required
$defs
$ref
readOnly
writeOnly
Wix extends the JSON schema to support the following Wix-specific keywords:
This keyword is used to define the permissions required to read and write an extended field. This keyword is required for all extended fields. Its is an object that defines read and write permissions in separate arrays.
For example:
Copy Code
"x-wix-permissions": {"read": ["owning-app", "apps", "users", "users-of-users"],"write": ["owning-app", "apps", "users"]}
The supported permissions values are as follows:
"owning-app"
: The app that defines the extended field."apps"
: Other apps installed on a site together with the app that defines the extended field."users"
: Collaborators of sites that have the owning app installed."users-of-users"
: Visitors of sites that have the owning app installed.
Note: If you enable
users-of-users
permissions for reading or writing an extended field, you should also enable the same permissions forusers
. Otherwise, users won't be able to read or write the extended field data created by their site visitors.
This keyword is added to the schema of an existing extended field to archive the field. The value of this keyword is a boolean. Once an extended field is archived, it can't be read or written using APIs. If an archived extended field has nested fields, the nested fields are also archived. To restore an archived extended field, change the value of this keyword to false
or remove it from the schema.
For example:
Copy Code
"myField": {"x-wix-archived": true,"type": "string","maxLength": 100,"x-wix-permissions": {"read": ["apps"],"write": ["apps"]}}
This keyword is added automatically to every extended field when it's added to a schema. It indicates the date and time when an extended field was added in ISO 8601 format.
For example:
Copy Code
"myField": {"x-wix-created-date": "2020-01-01T00:00:00.000Z","type": "string","maxLength": 100}
Here is an example of an extended field schema that defines firstName
, lastName
, and age
fields. This is what the final schema looks like in the JSON Editor.
Copy Code
{"type": "object","properties":{"firstName": {"type": "string","description": "The person's first name.","x-wix-permissions": {"read":["apps"],"write":["users"]},"title":"First Name","maxLength": 20},"lastName": {"type": "string","description": "The person's last name.","x-wix-permissions": {"read":["apps"],"write":["users"]},"title":"Last Name","maxLength": 20},"age": {"description": "Age in years which must be equal to or greater than zero.","type": "integer","minimum": 0,"x-wix-permissions": {"read":["apps"],"write":["users"]},"title":"Age","maxLength": 20}}}