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.
Skill details
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 eventsDiagnose a
400mixin validation error or a403on custom instances
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_readfor schemas and types;schema.custominstance_manageor type-specificcustom.{type}_*scopes for instances; the core entity’s manage scope when attaching a mixin to that entityAn HTTP client that can send JSON with
Authorization: BearerA 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_CONTRACTand an instance with mixin fields.
Why do I get
400 The schema cannot be downloadedon this instance write?
Query custom instances where
mixins.contractFields.termMonthsis 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
REFERENCEfields only on mixins attached to custom entities. Core-entity mixins cannot carry references.In schema attributes, use
NUMBERfor whole numbers andDECIMALwhen values can be fractional. ADECIMALattribute allows two decimal places unless you setprecision.Site-aware overlays let a custom instance or product carry per-site values. Create the schema with
siteAware: true, and store the values undermixins.<key>__<siteCode>. Only the base<key>goes intometadata.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
400on mixin write as validation – check required fields, types, enums, and thatmixins.<key>andmetadata.mixins.<key>use the same key. If aqquery returns nothing, first confirm the mixin exists withq=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?

