> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-extensibility.md).
# 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.
{% hint style="info" %}
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](/api-documentation/api-guides/utilities/schema.md) documentation, the [Schema Service tutorial](/api-documentation/api-guides/utilities/schema/schema.md), [Custom Instance API reference](/api-documentation/api-guides/utilities/schema/api-reference/custom-instance.md), and [Mixins](/api-documentation/standard-practices/mixins.md) standard practices.
{% endhint %}
## Skill details
| Property | Value |
| ------------ | ----------------------------------------------------- |
| Skill name | `emporix-extensibility` |
| Package path | `skills/emporix-extensibility/` (contains `SKILL.md`) |
Install it once using [Installing skills](/agentic-commerce-intelligence/agentic-engineering/skill-library.md#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
{% hint style="info" %}
For tokens and scope grants, use the [Emporix Auth](/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-auth.md) skill. Product modelling guidance belongs to the [Emporix Product Data](/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-product-data.md) skill.
{% endhint %}
## 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:
```mermaid
---
config:
layout: fixed
theme: base
look: classic
themeVariables:
background: transparent
lineColor: "#9CBBE3"
arrowheadColor: "#9CBBE3"
edgeLabelBackground: "#FFC128"
edgeLabelTextColor: "#4C5359"
---
flowchart TD
Start["What are you modelling?"]
About{"Extra fields on an
existing Emporix entity?"}
Supported{"Schema Service
creates the schema?"}
Own{"Own identity and
lifecycle?"}
MixinSS["Mixin via Schema Service"]
MixinHost["Mixin with hand-hosted
JSON Schema"]
Custom["Custom entity type
and instances"]
Reconsider["Likely still a mixin"]
Start --> About
About -->|Yes| Supported
Supported -->|Yes| MixinSS
Supported -->|No| MixinHost
About -->|No| Own
Own -->|Yes| Custom
Own -->|No| Reconsider
style Start fill:#F2F6FA,stroke:#4C5359,color:#4C5359
style About fill:#DDE6EE,stroke:#4C5359,color:#4C5359
style Supported fill:#DDE6EE,stroke:#4C5359,color:#4C5359
style Own fill:#DDE6EE,stroke:#4C5359,color:#4C5359
style MixinSS fill:#A1BDDC,stroke:#4C5359,color:#4C5359
style MixinHost fill:#A1BDDC,stroke:#4C5359,color:#4C5359
style Custom fill:#A1BDDC,stroke:#4C5359,color:#4C5359
style Reconsider fill:#A1BDDC,stroke:#4C5359,color:#4C5359
Start@{ shape: rounded}
MixinSS@{ shape: rounded}
MixinHost@{ shape: rounded}
Custom@{ shape: rounded}
Reconsider@{ shape: rounded}
```
Confirm which entities support Schema Service schema creation versus hand-hosted JSON Schema in the [Mixins](/api-documentation/standard-practices/mixins.md) guide.
**Mixin payload shape** – On write, an entity carries two maps that must use the same mixin key: `mixins.` holds the field values, and `metadata.mixins.` points at the JSON Schema URL those values are validated against. For schemas created through the Schema Service, that `` 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](/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-auth.md)
* 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.
* 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.` and `metadata.mixins.` use the same key. If a `q` query returns nothing, first confirm the mixin exists with `q=mixins.: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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.emporix.io/agentic-commerce-intelligence/agentic-engineering/skill-library/emporix-extensibility.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.