Pass the MXO customer profile through untyped and project only the fields KBP uses

ID
ADR 9.4
Status
accepted
Date
2026-09-30
Deciders
KBP architect
Tags
integration mxo comtrol

Context and problem statement

External API responses normally cross the KBP integration boundary through typed transport contracts. These contracts are derived from a provider-owned OpenAPI specification or another stable contract. The MXO CustomerProfile_v1_4 has no such contract. MXO owns a dynamic schema, and COMtrol needs the complete profile for its sales-condition and test-profile editors.

KBP also needs a few profile fields for its own business decisions: contract ID, estimated HT/NT consumption, consumption type, electricity-meter category, portal and app activity timestamps, and the master-data-overlay flag. Neither MXO nor another owning team provides typed endpoints for these use cases.

How should KBP handle a profile it must forward completely but whose schema it does not control?

Decision drivers

  • COMtrol receives every profile field, including fields KBP does not know about.
  • MXO schema additions reach COMtrol without a KBP release.
  • KBP business logic depends on as little of the dynamic structure as possible.

Considered options

  1. Typed transport contract for the complete profile
  2. Untyped pass-through with a typed projection of the fields KBP uses
  3. Typed use-case endpoints provided by the owning team

Decision outcome

Chosen option: 2, untyped pass-through with a typed projection. It is the only option that meets all drivers today. KBP retrieves the live profile as an untyped dictionary and converts it to a JSON object. It enriches the object with request data and forwards the complete result to COMtrol. Only the fields listed above are mapped to a typed projection (MxoCustomerProfile) before they reach business logic.

Option 1 would drop unknown fields and need a KBP release for every MXO schema change. Option 3 is the preferred integration pattern, but no owning team provides the endpoints yet.

Consequences

  • Good, because COMtrol always gets the complete, current profile.
  • Good, because the coupling to the dynamic schema is limited to one typed projection.
  • Bad, because KBP business decisions still depend on a provider-specific structure without a stable contract. A renamed or removed field fails at runtime, not at build time.

Confirmation

This is an exception, not a pattern for new integrations. It ends when an owning team provides typed use-case endpoints that replace KBP’s interpretation of the profile. KBP then supersedes this record.