> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/user-guides/management-dashboard/settings/mixin-schemas.md). # Mixin Schemas Create schemas for custom mixin properties. The **Mixin Schemas** section allows extending entities in Management Dashboard, for example a product, with customized fields of different types. To keep shared mixin values and override selected values for individual sites on products or custom instances, see [Site-aware mixins](#site-aware-mixins).

Mixin Schemas overview in Management Dashboard

## Creating a mixin schema There are two ways to define a new schema in Management Dashboard: * defining a schema manually * uploading a JSON file {% hint style="info" %} In Management Dashboard, you can extend the data model for the following entities: availability, cart, cart item, category, classification, company, coupon, custom entity, customer, customer address, location, order, order entry, price list, product, quote, return, site and vendor. {% endhint %} ### Defining a schema manually {% stepper %} {% step %} #### Choose to add a mixin schema Go to **Settings** -> **Mixin Schemas** and choose **Add new mixin schema**. {% endstep %} {% step %} #### Choose the entity Select an entity or multiple entities that you want to customize from the dropdown menu and enter the name for the schema.\ You can also provide a key value for your new schema, which then works as its unique identifier. If you don't provide the key value on your own, it's generated automatically.

Choosing an entity and naming a new mixin schema

{% hint style="warning" %} The localized name you define for the schema later appears as a separate tab in the modified entity. {% endhint %} {% endstep %} {% step %} #### Save your configuration Choose the **Confirm** button. {% endstep %} {% step %} #### Define mixin fields Go to **Fields** tab and choose **+** icon to add a mixin field. * **Type** – Select a field type relevant to its purpose. {% hint style="success" %} The following field types are supported: array, boolean, date, date\_time, decimal, enum, integer, object, text, and time. The **array** mixin types support values of different types as well: boolean, date, date\_time, decimal, enum, integer, object, text, and time. Additionally, mixin schemas for **Custom Entities** support reference field types for establishing one-to-one relationship, and array of references for one-to-many relationships. The reference can point to any other custom entity type or to the following Emporix types: cart, category, customer, customer segment, classification, legal entity, media, order, price list, and product. When you create or edit a specific instance of such custom entity, you can select instances of referenced types. {% endhint %} * **Key** – Define the name of the field. * **Name** – Provide the display name and its translations in the desired languages. * **Description** – Enter the field description. * **Array Type** (only for the **Array** type) – Choose the relevant type of values in an array. * **Values** (only for **Enum** type) – Define the default values for the field. Confirm each value with the **Enter** key. * **Reference Type** (only for **Reference** type and **Reference** in **Array Type**, and only in mixin schemas for **Custom Entities**) – Select the entity you want to establish a reference to. * **Precision** (only for the **Decimal** type) – Define the allowed decimal step for field values. Use values such as `0.1`, `0.01`, `0.001`, and further steps of the form `10^-n` (for example `0.0001`). If you do not set a precision for a decimal field, the default step `0.01` is applied. Choose a finer step for measurements, conversion factors, or other precision-sensitive values; `0.01` is typically suitable for prices and similar monetary amounts. * **No precision** (only for the **Decimal** type) – Enable this option to accept decimal values without a step constraint. When enabled, the **Precision** field is disabled. Use this when stored values must not be restricted to a fixed decimal increment. * Provide relevant configuration in **Settings**: * **Localized** (only for **Text** type) – Decide whether the field is translated to other languages. * **ReadOnly** – Decide whether the field is non-editable. * **Required** (except for **Boolean** type) – Decide whether the field is mandatory. * **Nullable** – Decide whether the field can accept `null` values. * **Array Localized** (only for **Text** in **Array Type**) – Decide whether texts within the array are localized. * **Array Values** (only for **Enum** in **Array Type**) – Define the default values for the field. Confirm each value with the **Enter** key.

Configuring basic settings for a mixin field

Configuring reference settings for a mixin field

Configuring decimal settings for a mixin field

{% endstep %} {% step %} #### Save the fields Save a field with **Confirm** button. Repeat these steps to add as many fields as you require for the given entity. {% endstep %} {% step %} #### Optional: Define object fields If you've added fields of **object** type or of **array of objects** type, choose **+** icon within the given row to define the object's fields (only for **object** and **array of objects** types).

Defining nested fields for object and array of objects mixin types

{% endstep %} {% step %} #### Save the schema When you're done with defining mixin schema fields, confirm schema creation with **Save**. This action generates the schema for a particular entity or entities. You can already view the schema details in the Management Dashboard. If you need the JSON schema file, choose **Open Generated JSON** to access it.

Schema editor with a link to the generated JSON — Schema editor with generated JSON link

{% endstep %} {% endstepper %} **Result**: The new schema is in use. It means that if, for example, you've created a schema called *Size* for a product entity, next time you create or edit a product, the new fields are available in a *Size* tab.

Product detail view showing fields from an assigned mixin schema

The schemas of **object** type display the defined objects as nested within a hierarchical structure:

Product mixin schema with object-type fields displayed as a hierarchy

The schemas of **array of objects** type also allow for adding objects with the defined fields:

Product mixin schema with an array of objects and their defined fields

### Uploading a JSON file Upload a JSON file when you already have a schema definition and want to use it as the starting point for a new mixin schema. {% hint style="info" %} If you want to learn how to create JSON schema file, see [Prepare a JSON schema definition](/api-documentation/api-guides/utilities/schema/schema.md#prepare-a-json-schema-definition). {% endhint %} {% stepper %} {% step %} #### Start a mixin schema Go to **Settings** → **Mixin Schemas** and select **Add new mixin schema**. {% endstep %} {% step %} #### Provide the schema details Select one or more entity types and enter the schema name. You can also provide a key. {% endstep %} {% step %} #### Upload the file Choose the schema file from your device or drag it to the upload area. If the schema requires per-site values on products or custom instances, select **Site aware**. Select **Confirm** to open the schema editor.

Uploading a JSON file to create a mixin schema — Creating a mixin schema from an uploaded file

{% endstep %} {% step %} #### Review and save the schema Review the imported fields on the **Fields** tab, then select **Save** and confirm the creation. {% endstep %} {% endstepper %} **Result:** The new schema is available for its assigned entity types. For example, a product schema adds a tab named after the schema when you create or edit a product. ## Editing mixin schemas {% stepper %} {% step %} #### Choose to edit a schema Go to **Settings** -> **Mixin Schemas** and select the schema you want to change. Choose the Edit icon to modify it. {% endstep %} {% step %} #### Make the changes Make changes to the schema or to particular fields in the schema: * In **Schema** tab, you can select or unselect entities types you want to apply the schema to. * In **Fields** tab, you can change settings for particular fields, add more or remove fields from the schema. {% endstep %} {% step %} #### Save your configuration Confirm your changes with **Save** and confirm you want to update the existing schema.

Confirmation dialog for saving a new version of a mixin schema

{% endstep %} {% endstepper %} {% hint style="warning" %} Each time you edit a schema, you generate its new version. This behavior is to prevent validation errors for the objects that were created/edited earlier and use the older schema versions. The latest schema version is always applied by default. {% endhint %} **Result:** A new schema version is created. New entities use it automatically. Existing entities with saved values keep their current version until you review and apply the update. {% hint style="info" %} If you have a schema applied to multiple entities, it is possible to modify the schema for each entity separately. You need to select the entities you want your changes to apply to when editing the schema. Then, the new schema version is in use only for the selected entities while the other ones still use the previous version. {% endhint %} ### Mixin schema versioning When you edit a mixin schema that is already assigned to an entity, your changes become visible in the entity view. For example, suppose you have a custom instance schema for mobile phones. If you add fields or modify field types, Management Dashboard presents those changes for review when you open an instance that has values saved against the older version. When a mixin schema is used in an entity, an indicator in the view displays the mixin schema version number. Each time you update the mixin schema and open the entity that uses it, you can see which fields were added or modified. For instance, in the mobile phone instance schema below, the newly added and updated fields are highlighted accordingly - blue for new, yellow for the changed ones.

Entity view showing newly added (blue) and modified (yellow) mixin fields

In this view, you can compare the current mixin schema version with the new one. You can either keep the old version, or decide to use the new one.

Preview and confirmation screen for applying an updated mixin schema version

New fields and updates are highlighted when the entity has mixin values saved against an older schema version. You can keep the current version or apply the new one. If the entity has no saved values for that schema, it uses the latest version automatically without displaying a preview:

Entity using a mixin schema without previously saved values, automatically updated to the latest version

If you need a more detailed, technical comparison of all your changes, choose the **Technical** button. This opens a side-by-side comparison of the current and updated schemas in a JSON format. At the top, you can see a list of differences showing the unique keys of the newly added fields. The format of these keys depends on whether they were custom-defined or auto-generated.

Technical JSON diff view comparing current and updated mixin schemas

See other examples for Product and Customer entities:

Example of mixin schema versioning for a Product entity

Example of mixin schema versioning for a Customer entity

## Site-aware mixins Site-aware mixins let a product or custom instance keep shared mixin values and override selected values for individual sites. Use them when the same entity is available across sites but some attributes differ by market or storefront. In Management Dashboard, mark the mixin schema as **Site aware**, then maintain its **Default** values and site-specific overrides on the product or custom instance. {% hint style="warning" %} Site-aware mixin editing is available for products and custom instances. Assign the schema to **Product**, a custom entity type, or both. Schemas are assigned to custom entity types, while override values are edited on instances of those types. See [Custom Entities](/user-guides/management-dashboard/settings/custom-entities.md) and [Custom Instances](/user-guides/management-dashboard/custom-instances.md). This feature is separate from the mixin fields on a product **Availability** row. Those fields belong to an availability mixin schema. See [Products](/user-guides/management-dashboard/products-module/products.md). {% endhint %} Site-aware mixins are useful in the following situations: * The same product or custom instance is sold or used across multiple sites. * Most mixin attributes are shared, and only some values must differ by site. * API clients need one merged set of values for the requested site. If every attribute is the same on all sites, a standard mixin schema is enough. ### Creating a site-aware mixin schema {% stepper %} {% step %} #### Start a mixin schema Go to **Settings** → **Mixin Schemas** and select **Add new mixin schema**. Choose **Product**, a custom entity type, or both. Enter the schema name and, if needed, a key. Select **Confirm** to open the schema editor. To update an existing schema, open it from the list. {% endstep %} {% step %} #### Enable site awareness On the **Schema** tab, select **Site aware**.

Mixin schema with Product type and Site aware selected — Configuring a site-aware mixin schema

{% endstep %} {% step %} #### Define fields and save On the **Fields** tab, add the attributes you need, then select **Save**. Field setup follows the same rules as a standard mixin schema. See [Creating a mixin schema](#creating-a-mixin-schema). Saving changes to an existing schema creates a new version. Apply the new version to products or custom instances as described in [Mixin schema versioning](#mixin-schema-versioning). {% endstep %} {% endstepper %} **Result:** Products or custom instances that use the schema show a site context panel on the mixin tab. You can also enable **Site aware** when you upload a JSON schema file. Follow [Uploading a JSON file](#uploading-a-json-file) and choose **Site aware** before you confirm the upload. ### Setting default and site-specific values The following example uses a site-aware **Vehicle search attributes** schema on a vehicle instance.

Vehicle search attributes mixin schema with Site aware enabled — Site-aware Vehicle search attributes schema

{% stepper %} {% step %} #### Open the entity Open a product or a custom instance whose entity type is assigned to the site-aware schema. Open the mixin tab named after your schema. {% endstep %} {% step %} #### Set Default values In the site context panel, choose **Default** and enter the values shared by all sites. Complete every required field in **Default**. Management Dashboard does not save the schema values until the required default fields are complete.

Site context panel with Default selected on a vehicle instance — Default mixin values on a vehicle instance

{% endstep %} {% step %} #### Add site-specific values Choose a site in the site context panel. Fields without an override show the corresponding **Default** value. Enter only the values that must differ for this site. To remove an override, choose **Use default** for that field.

Site context panel with United States selected and overridden mixin values — Site-specific mixin values for the United States site

{% endstep %} {% step %} #### Save all contexts Choose **Save**. Management Dashboard stores the **Default** values and every site-specific override changed in the current session. **Discard** reverts unsaved changes in all site contexts for this schema. {% endstep %} {% endstepper %} **Result:** The product or custom instance keeps shared **Default** values and optional overrides. API clients that request the entity with a site context receive the combined values for that site. ### How site context works Use the site context panel to choose which values you are editing and to clear leftover overrides after a site is deleted from the tenant. The panel includes the following contexts: * **Default** – shared mixin values for all sites * **Site** – each site configured for your tenant, shown with the site name when available, otherwise the site code * Removed site – after you delete a site from the tenant, its context stays on the product or custom instance for as long as site-specific mixin values remain stored for that site code To clear leftover values, open the removed site context and choose **Use default** for every overridden field, then choose **Save**. When no site-specific values remain, the removed site context disappears. The following indicators help you track values while editing: * An asterisk next to a context – that context has unsaved changes * A marker on a site – that site already has site-specific values stored Switching between **Default** and sites does not save by itself. Unsaved work stays in the form until you choose **Save** or **Discard**. ## Displaying mixins in entity list view You can add a mixin field as a column in the list view of a selected entity. The mixin field can serve as a filter so that you can find the items of your interest. {% stepper %} {% step %} #### Choose to customize your view Go to the selected entity view and choose the **Orchestration** icon.

Orchestration icon for customizing the entity list view

{% endstep %} {% step %} #### Choose the mixins In the **Mixins** section, look for the mixin fields you want to add as filter columns. Or, choose **Add custom mixin** to add a new mixin field.

Selecting mixin fields to add as list view columns and filters

The selected mixin fields appear in the orchestration panel, where you can enable or edit them.

Selected mixin fields in the orchestration panel

{% endstep %} {% step %} #### Adjust the way how the columns are displayed Use the **Edit** icon. You can edit the displayed label of the mixin column.

Editing the label of a mixin field column in the list view

{% endstep %} {% step %} #### Save the selection Select **Save**. The selected mixin fields appear as columns in the entity list view and can be used as filters. {% endstep %} {% endstepper %} {% hint style="warning" %} Only fields from mixin schemas managed in **Settings** → **Mixin Schemas** appear in the column selector. A mixin added directly to an entity through its API does not appear unless its schema is registered for that entity type. Create or assign the schema in **Mixin Schemas** first. Adding mixins as column filters is possible for the following entities: cart, cart item, category, classification, company, coupon, custom entity, customer, customer address, order, order entry, price list, product, quote, return, site, and vendor. {% endhint %} ## Unassigning a schema If you no longer want to apply the latest version of a schema to an entity, you can unassign it. {% stepper %} {% step %} #### Select the schema Go to **Settings** -> **Mixin Schemas** and select the schema you want to remove from an entity. {% endstep %} {% step %} #### Choose **Unassign** icon Choose the icon to remove the connection between the latest schema version and entity.

{% endstep %} {% step %} #### Confirm the action Choose **Yes** to confirm, or **Cancel** to keep the assignment.

Confirmation dialog for unassigning a schema from an entity

{% endstep %} {% endstepper %} **Result**: The particular entity uses the previous version of the schema that exists in the database. If you had only one schema version and you unassign it from an entity, the schema tab is no longer visible when you create or edit objects of that type. {% hint style="warning" %} The unassigned schemas are not displayed in the Management Dashboard. To retrieve, edit or delete an unassigned schema, use API mechanism. See more in [Schema Service](/api-documentation/api-guides/utilities/schema.md). {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developer.emporix.io/user-guides/management-dashboard/settings/mixin-schemas.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.