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.
Note:
Your schema plugin fields will only appear in extendedFields if your app is approved.
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 app dashboard, 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:
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.
Note: If a site owner has defined a schema plugin, that plugin is defined in a default namespace called “user_defined”. This namespace may appear in API calls.
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.
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.
Note:
When you read an object with a schema plugin, you can only retrieve the data that your app has permissions to read. For example, plugin fields that don’t have the “apps” permission can’t be seen by other apps installed on the site.
You can write schema plugin data by calling the object’s standard Update endpoint. This allows you to update both regular fields and schema plugin fields in a single call.
When you 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.
You can also clear a schema plugin field by setting its value to null. For example:
Be aware that the plugin fields your app can write to depend on the field permissions defined in the schema plugin.
When you update schema plugin data, the 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.
Learn how to add a schema plugin to an API object.