Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Supported entity types for schema creation

When creating a mixin schema through the Schema Service API, you can select from the following entity types: availability, cart, cart_item, category, company, coupon, customer, customer_address, custom_entity, location, media, order, order_entry, price_list, product, quote, return, site, vendor, and vendor_location.

Important distinction: The list above shows which entity types support mixin schema creation through the Schema Service API. APIs that support mixins but are not listed there still require you to create mixin schemas manually (as JSON schemas) and reference them when using those APIs. See the Mixins standard practices page for a complete list of APIs that support mixins.

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 {{OAUTH2_ACCESS_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:

Custom entity authorization and ownership

When you create a custom entity type, the platform provisions type-specific scopes that follow the custom.{lowerCaseType}_* naming pattern.

For a type like DOCUMENT, generated scopes follow this pattern:

  • custom.document_read

  • custom.document_manage

  • custom.document_read_own

  • custom.document_manage_own

Custom instance endpoints accept either tenant-wide Schema scopes or type-scoped scopes:

  • Read operations: schema.custominstance_read or custom.{lowerCaseType}_read or custom.{lowerCaseType}_read_own

  • Manage operations: schema.custominstance_manage or custom.{lowerCaseType}_manage or custom.{lowerCaseType}_manage_own

Custom instance responses include the immutable owner object, which is used for ownership-aware authorization:

  • owner.type: CUSTOMER, EMPLOYEE, or SERVICE

  • owner.userId: creator identifier (for service flows, client identifier)

  • owner.legalEntityId: present for customer-owned instances

For the end-to-end IAM and Schema flow, see Custom scopes for custom entities in the Tokens and Scopes guide.

PreviousSchema Service
NextAPI Reference

Last updated

Was this helpful?