Objets externes, drafts et mappings
Le système partenaire et Ormuz ne partagent pas automatiquement le même modèle de données. Une extension doit rendre explicite la frontière entre le fait externe, sa projection éventuelle et l’objet canonique de la plateforme.
Objets externes
Un objet externe représente un contrat du système partenaire exposé de manière typée à Ormuz. Il conserve l’identité et la sémantique nécessaires pour raisonner sur le fournisseur sans prétendre devenir un objet canonique Ormuz.
- préservez l’identité externe utile à la corrélation ;
- normalisez les formats de transport lorsque le contrat Ormuz impose une convention plus forte ;
- n’inventez pas un champ métier lorsque ni le fournisseur ni Ormuz n’en établissent précisément la signification ;
- ne qualifiez pas un objet externe de
platform.*tant qu’il n’est pas un véritable objet canonique.
Objets plateforme
Un objet plateforme utilise le contrat canonique Ormuz quelle que soit la surface qui le fournit. Une extension ne définit pas sa propre variante allégée d’un company, d’une invoice ou d’un payment.
Les ressources adressables, projections calculées et objets embarqués n’ont pas les mêmes modes d’accès. Vérifiez le catalogue canonique avant de concevoir un paramètre, un output ou un mapping.
Drafts
Un draft est un payload d’objet plateforme avant persistance. Ce n’est pas une famille d’objet parallèle : il garde le même type métier mais son type process porte le mode draft.
Une projection externe vers un draft n’autorise sa persistance que si le contrat d’autorité du type cible permet cette matérialisation. Les faits d’observation appartenant à un rôle externe ne doivent pas être fabriqués via une surface générique de création champ par champ.
Mappings
Un mapping établit une correspondance durable entre une identité externe et un objet plateforme précis dans le périmètre d’une configuration d’extension.
Le mapping fige une correspondance exacte dans le périmètre d’une configuration d’extension ; il ne confère aucun droit supplémentaire sur la cible.
Cette correspondance sert à la corrélation, à l’idempotence et à la résolution exacte. Elle ne donne pas le droit de lister des objets, rechercher un autre objet, traverser arbitrairement ses relations ou le muter.
Un mapping ne peut jamais créer une autorité nouvelle : il ne peut figer qu’une relation que l’extension était déjà légitime à établir au moment de sa création.
Événements entrants
Un webhook ou autre événement entrant peut valider, normaliser et exposer des données externes typées. Il ne doit pas transformer silencieusement l’arrivée d’un événement en mutation arbitraire d’un objet plateforme.
Lorsqu’un événement doit fournir un objet plateforme au processus, cette résolution doit être suffisamment fiable pour que le contrat soit honnête. Une donnée aléatoirement absente pour des raisons de timing ne doit pas être présentée comme un output stable.