CommunitySupport PortalYouTubeFree trialSign Up!

Schema Tutorial

With the Schema Service you can easily create and manage customized/industry-specific fields for different types in Management Dashboard. The new fields appear in a separate tab when you create an instance of the extended type.

It is possible to create mixin schemas through API for the following entities: category, company, coupon, customer, customer.address, order, price list, product, quote and return.

How to add custom fields for an entity

This tutorial explains how to add custom fields for a product entity.

Create a schema

To extend the product entity in Management Dashboard with some industry-specific fields, create a schema that defines the required fields and generates JSON file representation by sending a request to the Creating a schema endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference
curl -L 
  --request POST 
  --url 'https://api.emporix.io/schema/{tenant}/schemas' 
  --header 'Authorization: Bearer YOUR_OAUTH2_TOKEN' 
  --header 'Content-Type: application/json' 
  --data '{
    "name": {
      "en": "Product Custom Attributes"
    },
    "types": [
      "PRODUCT"
    ],
    "attributes": [
      {
        "key": "weight",
        "name": {
          "en": "Weight of a product"
        },
        "description": {
          "en": "The exact weight of a product in grams."
        },
        "type": "TEXT",
        "metadata": {
          "readOnly": true,
          "required": true
        }
      },
      {
        "key": "size",
        "name": {
          "en": "Size of a product"
        },
        "description": {
          "en": "The exact size of a product. Possible values are S, M, L."
        },
        "type": "ENUM",
        "metadata": {
          "readOnly": true,
          "required": true
        },
        "values": [
          {
            "value": "S"
          },
          {
            "value": "M"
          },
          {
            "value": "L"
          }
        ]
      },
      {
        "key": "advertisement",
        "name": {
          "en": "Advertisement of a product"
        },
        "description": {
          "en": "A localized advertisement of a product."
        },
        "type": "TEXT",
        "metadata": {
          "localized": true,
          "required": true
        }
      }
    ]
  }'

Request result is the new schema ID - "id": "6915ec3c047dc4456d86a26f".

Retrieve a schema

Retrieve the created schema to get the schema URL by calling the Retrieving a schema endpoint.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

In the response, you can see the URL link to cloudinary repository, where the schema for the product type has been uploaded.

When you create a product, the validation mechanism runs against the schema stored under the mentioned cloudinary URL.

Create a product

Now, create a product that contains additional fields by sending a request to Creating a new product endpoint.

The product should contain "metadata.mixins.{{id}}: {{cloudinaryUrl}}", where id is the schema URL you retrieved with GET operation in the previous step.

For example, you created a schema with size attribute and it got assigned a schema id: 6915ec3c047dc4456d86a26f. When creating or editing a product, provide the schema id and URL details in the payload of the POST request:

The product you created has already the custom fields added in the separate Product Custom Attributes tab.

How to create a more complex schema

In case you need to add a schema for more complex attribute types than those supported by default, instead of creating a schema, you can create a reference. This tutorial shows you how to upload more complex schemas.

Prepare a JSON schema definition

See the example JSON file that defines fields of different types:

Create a reference

To use the schema in Emporix Commerce Engine, send a request to the Creating a reference endpoint. This action creates a reference to your schema so that you use the extended type. The schema reference is used to create or edit product objects.

Note that the fields of types that are not supported by default are not displayed in the Management Dashboard. You can edit them by API requests.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

CURL request example:

JSON example:

Create a product

Now, create a product and provide values for the customized fields by sending a request to Creating a new product endpoint.

See the example payload for creating a product basing on the schema from the previous step:

PreviousSchema ServiceNextAPI Reference

Last updated

Was this helpful?