Public schemas and types
Ormuz contracts distinguish persisted business objects, external objects provided by extensions, and shared semantic values. This distinction is preserved across the API, nodes, and process bindings.
Three type families
| Prefix | Role | Examples |
|---|---|---|
platform.* | Public Ormuz objects, persisted resources, or canonical projections. | platform.company, platform.invoice, platform.credit_exposure |
extension.* | Normalized provider objects exposed by an extension. | extension.stripe.customer, extension.sumsub.applicant |
common.* | Semantic values and reusable structures that are not standalone business resources. | common.amount, common.metadata, common.form_spec |
Two JSON values that look alike are not necessarily interchangeable. A platform.invoice is a hydrated, addressable Ormuz object; a provider transport object or draft does not offer the same guarantees.
Shared semantic types
The subtypes common.* prevent an important business rule from being lost behind a simple JSON type.
| Type | Representation | Guarantee |
|---|---|---|
common.amount | integer | Amount in the currency's minor unit. Never a float. |
common.currency_code | string | ISO 4217 currency code, for example EUR. |
common.date | string | Civil date in YYYY-MM-DD format. |
common.datetime | string | ISO 8601 instant with `T` separator and timezone. |
common.email | string | Email address validated according to the field contract. |
common.phone | string | Phone number represented semantically rather than as an arbitrary string. |
common.url | string | Validated URL. |
common.metadata | object | Flat dictionary of scalar values reserved for integrator use. |
A common.amount is a safe integer expressed in the currency's minor unit: 125000 EUR means EUR 1,250.00. Do not use floating point or major-unit amounts in a typed common.amount.
Persisted objects, projections, and drafts
A persisted platform resource has an identifier and can be referenced durably. A projection such as receivable or payable is calculated from current state and does not necessarily have autonomous identity.
A draft is not a parallel family such as company_draft. It keeps the same target business object, but the process type carries mode: draft and the payload does not yet have an ID.
{
"type": {
"type": "object",
"subtype": "platform.company",
"mode": "draft"
}
}The draft → persisted resource transition must be explicit in the process. Creation is allowed only when the object's authority contract permits this path.
Identifiers and relationships
Public contracts use opaque prefixed IDs — for example cmp_*, inv_* or pci_*. A relationship field exposed by the API references the linked object's ID.
When a node declares an output platform.company, it must produce an object hydrated enough to be used by subsequent nodes; a simple stub { id, object } does not satisfy that promise.
Metadata: a deliberately narrow contract
Every field named metadata follows common.metadata: flat dictionary whose values are only string, number or boolean. Nested objects, arrays, and null values are forbidden.
| Limit | Value |
|---|---|
| Serialized size | 16 KB per map |
| Number of keys | 50 |
| Key length | 64 characters |
| String value | 2 KB |
Keys absent during an update are preserved; deletion uses the dedicated metadata sub-endpoint. Data the Core depends on to determine behavior must be canonical fields, not hidden conventions in metadata.
Types in processes
The bindings compare declared input and output types. A collection array<platform.invoice> preserves the concrete type of its elements across collection nodes, and a semantic field remains distinct from a plain string when that distinction protects the contract.
Dynamic nodes — subworkflow, Decision, Agent task, Form, or event wait — derive their fields from the contract actually selected. The editor therefore validates mapping against that revision or schema, not generic JSON.
Where to find the exact contract?
- Object catalog — functional meaning, relationships, and invariants.
- API reference — endpoints and public HTTP schemas.
- Core node catalog — inputs, outputs, routes, and orchestration behavior.
- Integrations — objects
extension.*, nodes, and events specific to each provider.
This page describes cross-cutting conventions. When a constraint belongs to a precise object — status enum, required relationship, allowed transition — its canonical page and API schema remain the detailed reference.