Extend an Existing Object Array Field with a Schema Plugin

Schema plugins are backend extensions that allow you to add fields to API objects. In addition to extending objects at the root level, schema plugins can extend nested arrays within objects by adding fields to individual array items. Once added, these nested fields can be read and written using the object's regular endpoints, just like any other field in the object.

For example, you can extend individual line items in an eCommerce order, allowing you to add custom data specific to each array item.

Extending an object array field with a schema plugin

To add a schema plugin extension for a nested array field to your app:

1. Select an app from the Custom Apps page in your Wix Studio workspace.

2. Select Extensions in the left side-menu, and click + Create Extension.

   

3. Search for schema plugin in the search bar. Choose the object that contains the specific field you want to extend and click Create.

4. If this is the first time you're adding a schema plugin to the app, you'll be prompted to create a namespace for the app. This namespace is used when reading and writing any schema plugin fields created for the app. Once you save the namespace, it can't be changed.

   

5. Use the JSON Editor to define your schema plugin as a JSON Schema. When defining a schema plugin for nested array fields, you'll target the specific array property path rather than the root object.

   For example, to extend line items in an order, your schema might target the lineItems array:

   Copy

   

6. Once your schema plugin is defined, click Save.

   Important: Once you add a schema plugin to an app, it can't be removed. You can archive the plugin fields to prevent them from being read or written.

Your app now has a schema plugin extension for nested array fields. When working with the extended object, each array item will have its own extendedFields property that contains your custom fields in your app's namespace.

Accessing nested schema plugin fields

When reading or writing to nested schema plugin fields, you access them through the specific array item's extendedFields property:

You can return to the JSON editor to make non-breaking changes to the schema.