About Reading and Writing Schema Plugin Fields

Once you add your schema plugin to an object, you can read and write to the schema plugin fields with the object’s endpoints. The fields you added appear in the extendedFields object, which is located at the top level of an API object.

Namespaces

Inside extendedFields is a nested object called namespaces. The namespaces object contains the namespaces of any apps that extend the same API object. Let’s say your app extends the Booking object. When you create your schema in the Developer Center, you’re required to give it a namespace (for example, @account1/myApp). That namespace will be listed in the namespaces object. Inside the namespace are the fields you defined in your schema plugin.

Now imagine another app also extends the Booking object. We’ll call their namespace @account2/anotherApp.

If a user installs both apps on their site, the Booking object needs to know which fields belong to which app. This is where namespaces come in. The object will separate your plugin data from the other app's by adding two separate objects in namespaces and placing your respective schema plugins in the appropriate object. The extendedFields object looks something like this:

1

When your app reads or writes to a field defined by your schema plugin, it must include your namespace in the call to access the correct field.

Permissions

You can only read and write to schema plugin fields that give you permission to do so. These permissions are defined in the x-wix-permissions object of each field in the schema plugin. A field can have one or more of the following permissions:

• owning-app: The app that created the schema plugin can read and write to the field.
• apps: Other apps installed on the site can read and write to the field.
• users: Site admins can read and write to the field.
• users-of-users: Site visitors can read and write to the field.

A field’s permissions will affect its visibility during API calls. For example, if a user queries an object, plugin fields without “users” read permissions will not be returned.

Reading extended fields

You can read schema plugin fields using standard API methods like Query or Get. For example, if you’ve extended the Booking object, you can query the object and see your schema plugin fields in extendedFields under your app's namespace. Any data from other apps are contained under separate namespaces from yours.

Writing extended fields

You can also write to the fields in a schema plugin. APIs that support schema plugins provide two different ways to do this:

• Write to the fields through a standard endpoint.
• Write to the fields through a dedicated endpoint for schema plugin fields.

The plugin fields your app can write to depend on the field permissions defined in the schema plugin.

Standard endpoints

You can write schema plugin data using the object’s standard API endpoints. The advantage of using a standard endpoint is that you can update regular fields as well as those in the schema plugin in a single call.

When you use the standard endpoint to update a schema plugin field, the object’s revision is incremented. This is true even if you update only the plugin field and none of the object’s regular fields.

To update plugin fields, call the API’s Update endpoint. Below is an example of the general syntax:

You can also clear a schema plugin field by setting its value to null. For example:

1

Because this is a standard endpoint, you can add any other fields from the object that you want to update.

Dedicated endpoints

APIs that support schema plugins have a dedicated Update Extended Fields endpoint. Use this endpoint if you only want to update the schema plugin fields.

If the object you extended has a revision field, you don't need to pass it when using a dedicated endpoint. The object’s revision remains the same.

A call to Update Extended Fields looks a little different from a typical Update API call. Instead of passing an updated extendedFields object, you pass the namespace and the data you want to update as separate parameters. A dedicated endpoint call looks like this:

Note that the dedicated endpoint may require a different permission scope than the standard Update endpoint.

Webhooks

When you update schema plugin data 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 object. Only plugin data with “apps” read permissions are visible.

What’s next

Learn how to add a schema plugin to an API object.