External objects, drafts, and mappings
The partner system and Ormuz do not automatically share the same data model. An extension must make the boundary explicit between the external fact, its possible projection, and the platform's canonical object.
External objects
An external object represents a contract of the partner system exposed to Ormuz in typed form. It preserves the identity and semantics needed to reason about the provider without pretending to become a canonical Ormuz object.
- preserve the external identity needed for correlation;
- normalize transport formats when the Ormuz contract imposes a stronger convention;
- do not invent a business field when neither the provider nor Ormuz establishes its meaning precisely;
- do not label an external object as
platform.*until it is a genuine canonical object.
Platform objects
A platform object uses the canonical Ormuz contract regardless of the surface that provides it. An extension does not define its own lightweight variant of a company, d’une invoice or a payment.
Addressable resources, computed projections, and embedded objects do not have the same access patterns. Check the canonical catalog before designing a parameter, output, or mapping.
Drafts
A draft is a platform-object payload before persistence. It is not a parallel object family: it keeps the same business type, while its process type carries the mode draft.
An external projection to a draft allows persistence only when the authority contract of the target type permits that materialization. Observation facts owned by an external role must not be fabricated through a generic field-by-field creation surface.
Mappings
A mapping establishes a durable correspondence between an external identity and a specific platform object within the scope of an extension configuration.
The mapping freezes an exact correspondence within the scope of an extension configuration; it grants no additional rights over the target.
This correspondence supports correlation, idempotency, and exact resolution. It does not grant the right to list objects, search for another object, arbitrarily traverse its relations, or mutate it.
A mapping can never create new authority: it can only freeze a relationship that the extension was already entitled to establish when it was created.
Inbound events
A webhook or other inbound event may validate, normalize, and expose typed external data. It must not silently turn the arrival of an event into an arbitrary mutation of a platform object.
When an event must provide a platform object to the process, that resolution must be reliable enough for the contract to be honest. Data that is randomly absent for timing reasons must not be presented as a stable output.