Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Emporix Extensibility

Use the emporix-extensibility skill to add mixins and custom entities with the Schema Service.

Use the emporix-extensibility skill to extend the Emporix data model with the Schema Service – add custom fields (mixins) to core entities, define custom entity types and instances, and query custom data with the q filter language.

This page explains when to use the skill and how to work with it. For field types, endpoints, and OpenAPI details, see the Schema Service documentation, the Schema Service tutorial, Custom Instance API reference, and Mixins standard practices.

Skill details

Property
Value

Skill name

emporix-extensibility

Package path

skills/emporix-extensibility/ (contains SKILL.md)

Install it once using Installing skills.

When to use it

Use this skill when you need to:

  • Add a custom field or mixin to a core entity (Product, Order, Customer, Cart, and others)

  • Decide between a mixin and a custom entity type

  • Create a mixin schema or a custom type, and write or bulk-import custom instances

  • Wire the three-tier custom-instance scope model (tenant-wide / type-specific / own-only)

  • Query mixin fields with q, expand references between custom entities, or subscribe to custom-instance webhook events

  • Diagnose a 400 mixin validation error or a 403 on custom instances

For tokens and scope grants, use the Emporix Auth skill. Product modelling guidance belongs to the Emporix Product Data skill.

How it works

The Schema Service drives two extension mechanisms:

  • A mixin adds custom fields to an entity Emporix already owns.

  • A custom entity type invents a new record kind with its own instances (and optional mixins).

Decide which mechanism fits before you write schemas:

Confirm which entities support Schema Service schema creation versus hand-hosted JSON Schema in the Mixins guide.

Mixin payload shape – On write, an entity carries two maps that must use the same mixin key: mixins.<key> holds the field values, and metadata.mixins.<key> points at the JSON Schema URL those values are validated against. For schemas created through the Schema Service, that <key> is the schema’s id, so set a readable id when you create the schema. A separate key field in the create body is ignored and does not become the mixin key.

Custom types – Create a custom entity type; instances then belong to that type. When the type is created, Emporix also auto-provisions the matching custom.{type}_* scopes for read and manage access. Endpoint paths are in the Schema Service documentation linked above.

Prerequisites

Before you use this skill, make sure you have:

  • A valid bearer token – see Emporix Auth

  • Scopes matching the operation – schema.schema_manage / schema.schema_read for schemas and types; schema.custominstance_manage or type-specific custom.{type}_* scopes for instances; the core entity’s manage scope when attaching a mixin to that entity

  • An HTTP client that can send JSON with Authorization: Bearer

  • A public HTTPS URL for the JSON Schema – only when the entity requires a hand-hosted mixin schema

How to use it

After install, work in your AI tool with natural-language requests. Examples:

Add a warranty months mixin to Product with a readable schema id.

Should this be a mixin on Order or a custom entity type?

Create custom type SERVICE_CONTRACT and an instance with mixin fields.

Why do I get 400 The schema cannot be downloaded on this instance write?

Query custom instances where mixins.contractFields.termMonths is at least 12.

Provide your tenant name, target entity or type id, and the scopes on your token.

Usage notes

  • Choose mixin keys carefully and keep them stable. Each key is stored on every record that uses the mixin, so a rename splits old data from new.

  • Put REFERENCE fields only on mixins attached to custom entities. Core-entity mixins cannot carry references.

  • In schema attributes, use NUMBER for whole numbers and DECIMAL when values can be fractional. A DECIMAL attribute allows two decimal places unless you set precision.

  • Site-aware overlays let a custom instance or product carry per-site values. Create the schema with siteAware: true, and store the values under mixins.<key>__<siteCode>. Only the base <key> goes into metadata.mixins.

  • Availability, Location, and Vendor Location support schema creation through the Schema Service, so you do not need to host their JSON Schema yourself.

  • Grant the narrowest custom-instance scopes that fit the caller (tenant-wide, then type-specific, then own-only). After you add scopes in IAM, request a new token. Existing tokens still return 403.

  • Tear down in order – delete or reassign instances, remove mixin schemas that target the type, then delete the type. Auto-provisioned custom.{type}_* scopes remain until you clean them up in IAM.

  • Treat a 400 on mixin write as validation – check required fields, types, enums, and that mixins.<key> and metadata.mixins.<key> use the same key. If a q query returns nothing, first confirm the mixin exists with q=mixins.<key>:exists.

  • For bulk imports where referenced records may not exist yet, you can pass ?validateReferences=false. Use it only when you intend to fix references later.

Last updated

Was this helpful?