In This Article

About Schema Plugins

A schema plugin adds custom fields to a Wix object, such as an order or a booking, without changing the object's predefined fields. This reference is the shared contract for those fields. It covers where their values live on the object, which namespace they belong to, how each development path defines them, and who can read and write them.

Unlike other backend extensions, a schema plugin has no generated files and no handler. It's a JSON schema that Wix stores and applies to the object. How you define that schema depends on whether the fields belong to an app or to a site.

Extended fields

An object that supports schema plugins has an extendedFields property. Custom field values live under extendedFields.namespaces, grouped by namespace:

Copy

Some objects also have extendedFields on the items of a nested array, such as an order's line items. Each extendedFields property is extended independently.

You read and write custom field values through the object's own API, such as Get Order and Update Order, like any other field. For which objects support custom fields, see Supported objects.

Namespaces

Each set of custom fields on an object belongs to one namespace:

App namespace: Fields that an app defines in its schema plugin, such as @my-account/my-app. Every site that installs the app gets these fields.
_user_fields: Fields that belong to one site. They're created with the Data Extension Schema API, or by Wix users in the site dashboard, for example as checkout form fields. A site has at most one _user_fields schema per object.

When you read or write a value, use the namespace of the schema that defines the field.

Define fields across development paths

Wix Studio and Wix Editor sites: Backend code calls the Data Extension Schema API to create or update the site's _user_fields schema. See About Data Extension Schemas. Studio Two sites don't currently support schema plugins.
Apps, including Wix-managed, self-managed, and Blocks apps: Define the schema plugin in the app dashboard, in the app's own namespace. The schema stays a draft that only test sites use until you release an app version, and released schemas stay backward compatible. See Extend an Existing Object with a Schema Plugin. An app can also add fields to one site's _user_fields schema with the Data Extension Schema API.

The Data Extension Schema API can list app schema plugins, but it can only create and update _user_fields schemas.

The JSON schema

Both kinds of schema use the same subset of JSON Schema. Each field needs a type and x-wix-permissions, and a string field also needs a maxLength. A schema can have up to 256 fields, and its fields can hold up to 10 KB of data on each object. For every type, format, keyword, and editing rule, see The JSON Schema in the API reference.

You can only make non-breaking changes to a field once it exists. In an app schema plugin, archive a field with x-wix-archived instead of removing it. In a _user_fields schema, an update that drops a field fails, so remove fields with Delete User Defined Fields.

Field permissions

x-wix-permissions sets who can read and write each field's values, with these values:

Value	Who it covers
`owning-app`	The app that defined the field.
`apps`	Apps installed on the site.
`users`	Wix users who manage the site, such as the site owner.
`users-of-users`	Site visitors and site members.

Wix adjusts the permissions depending on the namespace:

App namespace: The app dashboard adds owning-app to every field, so you don't need to list it.
_user_fields: Wix adds users to every field and removes owning-app, because no app owns the site's fields. To let apps on the site read or write a field, include apps.