# Mixin Schemas The **Mixin Schemas** section allows extending entities in Management Dashboard, for example a product, with customized fields of different types.

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: cart, cart item, category, classification, company, coupon, custom entity, customer, customer address, 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="info" %} The following field types are supported: array, boolean, date, date\_time, decimal, enum, number, object, text, and time. The **array** mixin types support values of different types as well: boolean, date, date\_time, decimal, enum, number, 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 a name of the field. * **Name**: Provide the name to display and its translation in desired languages. * **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 **Enter** key. * **Reference Type** (only for **Reference** type and **Reference** in **Array Type**): Select entity you want to establish reference to. This is supported for custom entity schemas only. * 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 **Enter** key.

Configuring basic settings for a mixin field

Configuring reference 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.

{% 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 Updating schema by JSON file might be useful when you have an already defined data model. {% hint style="info" %} If you want to learn how to create JSON schema file, see [Prepare a JSON schema definition](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/utilities/schema/schema#prepare-a-json-schema-definition). {% endhint %} {% stepper %} {% step %} #### Choose to add new schema Go to **Settings** -> **Mixin Schemas** and choose **Add new schema**. {% endstep %} {% step %} #### Add a name for entity schema Choose an entity or multiple entities that you want to customize from the dropdown menu and enter the name for the schema. {% endstep %} {% step %} #### Add a mixin schema file Choose the schema file from your device or drag and drop it to the selected area and choose **Confirm**.

Uploading a JSON file to create or update a mixin schema

{% endstep %} {% step %} #### Save your changes {% endstep %} {% endstepper %} **Result**: The new schema is in use. It means that if, for example, you've updated a schema for a product entity, next time you create a product, the new fields are available in a separate tab called the same as your schema. ## 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 version of the schema has been uploaded and is now in use. {% 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 update the schema to add new fields or modify existing field types, those changes automatically appear in the entity that uses the schema. 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 only if the instance already has previously saved mixin values. If the entity uses the same mixin schema but has no saved values, it automatically updates to the latest schema version without displaying a preview of the changes. For example:

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

## 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 list.

Entity list view with mixin columns added

{% 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 The columns appear instantly in the entity list view. {% endstep %} {% endstepper %} {% hint style="warning" %} Only the mixins defined in the Schema Service can serve as column filters. If you use the API to create mixins instead of the Schema Service, you won't be able to add the mixin fields from the API upload. To get around this, first define the mixin fields for a given entity in the Schema Service. Adding mixins as column filters is possible for the following entities: cart, category, classification, company, coupon, custom entity, customer, customer address, order, order entry, price list, product, quote, and return. {% 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](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/utilities/schema). {% endhint %}