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.

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

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.

Defining a schema manually

1

Choose to add a mixin schema

Go to Settings -> Mixin Schemas and choose Add new mixin schema.

2

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

The localized name you define for the schema later appears as a separate tab in the modified entity.

3

Save your configuration

Choose the Confirm button.

4

Define mixin fields

Go to Fields tab and choose + icon to add a mixin field.

• Type – Select a field type relevant to its purpose.

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.

• Key – Define the name of the field.
• Name – Provide the display name and its translations in the 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 the Enter key.
• Reference Type (only for Reference type and Reference in Array Type) – 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 Enter key.

Configuring basic settings for a mixin field

Configuring reference settings for a mixin field

Configuring decimal settings for a mixin field

5

Save the fields

Save a field with Confirm button.

Repeat these steps to add as many fields as you require for the given entity.

6

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

7

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.

Preview of a generated mixin schema

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.

If you want to learn how to create JSON schema file, see Prepare a JSON schema definition.

1

Choose to add new schema

Go to Settings -> Mixin Schemas and choose Add new schema.

2

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.

3

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

4

Save your changes

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

1

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.

2

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.

3

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

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.

Result: A new version of the schema has been uploaded and is now in use.

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.

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.

1

Choose to customize your view

Go to the selected entity view and choose the Orchestration icon.

Orchestration icon for customizing the entity list view

2

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

3

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

4

Save the selection

The columns appear instantly in the entity list view.

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, cart item, category, classification, company, coupon, custom entity, customer, customer address, order, order entry, price list, product, quote, return, site, and vendor.

Unassigning a schema

If you no longer want to apply the latest version of a schema to an entity, you can unassign it.

1

Select the schema

Go to Settings -> Mixin Schemas and select the schema you want to remove from an entity.

2

Choose Unassign icon

Choose the icon to remove the connection between the latest schema version and entity.

Unassign icon used to detach a schema from an entity

3

Confirm the action

Choose Yes to confirm, or Cancel to keep the assignment.

Confirmation dialog for unassigning a schema from an entity

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.

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.