Extended Fields

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.

Add extended fields to an app

To add extended fields to an app's API object, do the following:

1. Open the Wix Dev Center and select the app you want to add extended fields for.
2. In the left sidebar, click Extensions.
   
3. Click Create Extension.
   
4. Type extended fields in the search bar. Choose the object you want to add extended fields to and click Create.
   
5. 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.
   
6. 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.
   
7. 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.

Read and write extended fields

Once you add extended fields to an app, you can read and write them using the API endpoints for the object.

Read

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:

1
{
2
  "extendedFields": {
3
    "namespaces": {
4
      "@account1/myApp": {
5
        "myField": "My field value",
6
        "myField2": "Another field value for the same app"
7
      },
8
      "@account2/anotherApp": {
9
        "appField": "A field value for a different app"
10
      },
11
      "_user_defined": {
12
        "userField": "A field value added by a site owner"
13
      }
14
    }
15
  }
16
}

Write

There are 2 ways to write extended field data: standard endpoints and dedicated endpoints.

Standard 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.

Dedicated endpoint

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:

1
{
2
  "namespace": "@account-name/app1",
3
	"namespaceData":{
4
	  "myField": "my field value"
5
  }
6
}

Webhooks

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:

1
{
2
  // ... Other object data
3
  "extendedFields": {
4
    "namespaces": {
5
      "@account-name/app1": {
6
        "myField": "my field value",
7
        "myField2": "another field value"
8
      }
9
    },
10
    "_has_more_data": true
11
  }
12
}

JSON Schema for extended fields

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:

String

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 the maxLength keyword.
• Format: The following formats are supported:
  • Hostnames
  • Resource identifiers
  • Dates. Only date, date-time, and time 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, all string extended fields are considered multi-line text. The single-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 to single-line.

Numeric types

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.

Object

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 a properties 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.

Array

The array type is used to define a JSON schema array. Please note the following restrictions:

• An array extended field's schema must contain an items 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 the maxItems keyword.
• All the items in an array must be the same type.
• Arrays can only contain items of these types: string, number, integer, and boolean.

Boolean

The boolean type is used to define a JSON schema boolean. There are no restrictions on the boolean type object.

Global 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 extends the JSON schema to support the following Wix-specific keywords:

x-wix-permissions

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:

1
"x-wix-permissions": {
2
  "read": ["owning-app", "apps", "users", "users-of-users"],
3
  "write": ["owning-app", "apps", "users"]
4
}

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.

x-wix-archived

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:

1
"myField": {
2
  "x-wix-archived": true,
3
  "type": "string",
4
  "maxLength": 100,
5
  "x-wix-permissions": {
6
    "read": ["apps"],
7
    "write": ["apps"]
8
  }
9
}

x-wix-created-date

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:

1
"myField": {
2
  "x-wix-created-date": "2020-01-01T00:00:00.000Z",
3
  "type": "string",
4
  "maxLength": 100
5
}

Example extended field schema

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.

1
{
2
  "type": "object",
3
  "properties":{
4
    "firstName": {
5
      "type": "string",
6
      "description": "The person's first name.",
7
      "x-wix-permissions": {
8
        "read":["apps"],
9
        "write":["users"]
10
      },
11
      "title":"First Name",
12
      "maxLength": 20
13
    },
14
    "lastName": {
15
      "type": "string",
16
      "description": "The person's last name.",
17
      "x-wix-permissions": {
18
        "read":["apps"],
19
        "write":["users"]
20
      },
21
      "title":"Last Name",
22
      "maxLength": 20
23
    },
24
    "age": {
25
      "description": "Age in years which must be equal to or greater than zero.",
26
      "type": "integer",
27
      "minimum": 0,
28
      "x-wix-permissions": {
29
        "read":["apps"],
30
        "write":["users"]
31
      },
32
      "title":"Age",
33
      "maxLength": 20
34
    }
35
  }
36
}