A four-engineer team has six weeks to ship identity verification through a third-party KYC provider whose API model is well documented and has not changed in two years. The reviewing architect requires an anti-corruption layer that translates the provider's model into a model the team defines itself. Which call is correct?
Show the full answer Hide the answer
The deciding property
Not elegance, and not "coupling is bad". Three facts settle it: can you influence the upstream model, is that model adequate for your use, and how much of your own domain logic touches it.
Here you have no influence over a vendor, the model is documented and stable, and identity verification touches your domain in a handful of places - a decision outcome, a risk score, maybe a document reference. That combination is what Evans' 2003 context-mapping work calls Conformist: accept the upstream model and spend nothing on translation.
Why conformist is right here
The anti-corruption layer is insurance, and it has a premium: a second model, a mapping in both directions, tests for the mapping, and two changes for every new field the provider exposes instead of one. On a four-engineer team with six weeks, that premium is paid out of the only budget that matters.
The thing people miss is that a conformist relationship is not a refusal to protect the domain. It is a narrower protection: conform at the boundary, and translate only where one of your own invariants depends on the shape. If your domain rule is "a customer may not transact until verification is approved and not expired", you need two concepts - approved, expires-at - with your own names and your own validity rules. The other forty fields pass through as the provider's types, read by the one module that talks to the provider.
Keep the containment honest: the provider's types must not appear in your core. Conformist means one module owns them, not that they are free to spread.
Why the other options fail
- "Build the full anti-corruption layer now." The textbook answer, applied without the condition that justifies it. An anti-corruption layer earns its cost when the upstream model is unstable, actively bad, or about to be replaced. None of that is stated, and if the provider has not changed in two years the insurance is priced against a risk you can name but not evidence.
- "Adopt the provider's model throughout the domain." This is the real failure mode of conformist and the reason the pattern has a bad reputation. Once vendor types are in the core, every calling site has an opinion about the vendor, and swapping providers becomes a rewrite rather than a module change.
- "Define your own canonical model for a second provider later." Speculative generality. You are designing an abstraction over one example, and an abstraction derived from one implementation reliably fits only that one. The second provider arrives with a concept the first did not have, and the model you guessed has to change anyway - this time with callers depending on it.
What would flip the decision
| If this changes | Choose | Because |
|---|---|---|
| A second provider is contracted | Anti-corruption layer | now there are two shapes and one domain concept; translation is real work being done, not insurance |
| The provider's model contradicts an invariant - for example it allows an approval with no expiry | Anti-corruption layer for that concept | your domain cannot represent an illegal state just because the vendor can |
| The provider is a startup mid-redesign of its API | Anti-corruption layer | the premium buys a known shock absorber |
| Verification logic spreads into pricing and onboarding | Translate at the edge of those contexts | the containment has failed and the cost of conforming is now paid by three teams |
When this is the wrong answer
When the upstream is not a vendor but another team in your own organisation. Then you do have influence, and the right move is usually a conversation that produces a published model at their boundary rather than either conforming silently or building a translator in the dark. Conformist is for relationships where you cannot change the other side.