Schémas et types publics

Les contrats Ormuz distinguent les objets métier persistés, les objets externes fournis par les extensions et les valeurs sémantiques communes. Cette distinction est conservée dans l’API, les nodes et les bindings de processus.

Trois familles de types

Préfixe	Rôle	Exemples
`platform.*`	Objets publics Ormuz, persistés ou projections canoniques.	`platform.company`, `platform.invoice`, `platform.credit_exposure`
`extension.*`	Objets provider normalisés exposés par une extension.	`extension.stripe.customer`, `extension.sumsub.applicant`
`common.*`	Valeurs sémantiques et structures réutilisables qui ne sont pas des ressources métier autonomes.	`common.amount`, `common.metadata`, `common.form_spec`

Le type exprime une garantie Deux valeurs JSON qui se ressemblent ne sont pas nécessairement interchangeables. Un platform.invoice est un objet Ormuz hydraté et adressable ; un objet de transport provider ou un draft n’offre pas les mêmes garanties.

Types sémantiques communs

Les sous-types common.* empêchent de perdre une règle métier importante derrière un simple type JSON.

Type	Représentation	Garantie
`common.amount`	`integer`	Montant dans l’unité mineure de la devise. Jamais un flottant.
`common.currency_code`	`string`	Code devise ISO 4217, par exemple EUR.
`common.date`	`string`	Date civile au format YYYY-MM-DD.
`common.datetime`	`string`	Instant ISO 8601 avec séparateur T et timezone.
`common.email`	`string`	Adresse e-mail validée selon le contrat du champ.
`common.phone`	`string`	Numéro de téléphone sous forme sémantique plutôt qu’une chaîne arbitraire.
`common.url`	`string`	URL validée.
`common.metadata`	`object`	Dictionnaire plat de valeurs scalaires réservé à l’intégrateur.

Montants financiers Un common.amount est un entier sûr exprimé dans l’unité mineure de la devise : 125000 EUR signifie 1 250,00 EUR. N’utilisez ni flottants ni montants en unité majeure dans un champ typé common.amount.

Objets persistés, projections et drafts

Une ressource plateforme persistée possède un identifiant et peut être référencée durablement. Une projection, comme receivable ou payable, est calculée à partir de l’état courant et n’a pas nécessairement d’identité autonome.

Un draft n’est pas une famille parallèle telle que company_draft. Il conserve le même objet métier cible, mais le type de processus porte mode: draft et le payload n’a pas encore d’ID.

JSON

{1 item"type":{3 items"type":"object"
"subtype":"platform.company"
"mode":"draft"
}
}

{
  "type": {
    "type": "object",
    "subtype": "platform.company",
    "mode": "draft"
  }
}

Le passage draft → ressource persistée doit être explicite dans le processus. La création n’est autorisée que lorsque le contrat d’autorité de l’objet permet ce chemin.

Identifiants et relations

Les contrats publics utilisent des IDs opaques préfixés — par exemple cmp_*, inv_* ou pci_*. Un champ de relation exposé par l’API référence l’ID de l’objet lié.

Lorsqu’un node déclare une sortie platform.company, il doit produire un objet suffisamment hydraté pour être utilisé par les nodes suivants ; un simple stub { id, object } ne constitue pas une sortie conforme à cette promesse.

Metadata : un contrat volontairement étroit

Tout champ nommé metadata suit common.metadata : dictionnaire plat dont les valeurs sont uniquement string, number ou boolean. Les objets imbriqués, tableaux et valeurs null sont interdits.

Limite	Valeur
Taille sérialisée	16 KB par map
Nombre de clés	50
Longueur d’une clé	64 caractères
Valeur string	2 KB

Les clés absentes lors d’une mise à jour sont conservées ; la suppression passe par le sous-endpoint metadata dédié. Les données dont le Core dépend pour décider d’un comportement doivent être des champs canoniques, pas des conventions cachées dans metadata.

Types dans les processus

Les bindings comparent les types déclarés des entrées et sorties. Une collection array<platform.invoice> conserve le type concret de ses éléments à travers les nodes de collection, et un champ sémantique reste distingué d’un simple string lorsque cette distinction protège le contrat.

Les nodes dynamiques — subworkflow, Decision, Agent task, formulaire ou attente d’événement — dérivent leurs champs du contrat réellement sélectionné. L’éditeur valide donc le mapping par rapport à cette révision ou ce schéma, pas contre un JSON générique.

Où trouver le contrat exact ?

Catalogue des objets — sens fonctionnel, relations et invariants.
Référence API — endpoints et schémas HTTP publics.
Catalogue des nodes Core — entrées, sorties, routes et comportement d’orchestration.
Intégrations — objets extension.*, nodes et événements propres à chaque provider.

Cette page décrit les conventions transverses. Lorsqu’une contrainte appartient à un objet précis — enum de statut, relation obligatoire, transition autorisée — sa page canonique et le schéma API de cette ressource restent la référence détaillée.

← PrécédentLifecycles Suivant →Intégrations