Capability Flag

When a platform integrates many partners, some differences between them are accidental — naming, formatting, protocol — and belong in an adapter. Others are real: this supplier offers free cancellation and that one does not; this carrier returns delivery receipts and that one never will; this retailer reports inventory continuously and that one nightly.

Real differences cannot be abstracted away without producing silent incorrectness. A capability flag makes them explicit and queryable: the partner declares what it supports, and product logic consults the declaration.

Why it matters

The alternative is the canonical model absorbing every partner's peculiarities as optional fields. That model then changes whenever any partner changes — which is precisely the opposite of what an anti-corruption layer exists to provide. Every downstream service must handle fields that apply to one partner, and adding partner 301 modifies code that partners 1 through 300 depend on.

Capability flags keep the canonical model stable by moving variance into data.

Implementation patterns

• Declare capabilities as partner configuration, versioned and reviewable, not as branches in shared code.
• Model what the platform's product needs, not the union of what partners offer. If no product surface consumes a capability, it does not belong in the model.
• Pair each capability with a reliability profile — timeout, retry budget, concurrency ceiling, freshness tolerance, circuit state — also as data, so tuning a slow partner is a configuration change rather than a code change.
• Make absence explicit. "Delivery receipts: never" is different from "delivery receipts: unknown", and product logic should be able to distinguish them.
• Surface capability-driven behaviour in telemetry, so the effect of a partner's limitations is measurable rather than folded into a general error rate.

Industry example

Travel platforms aggregating hundreds of suppliers face this in its purest form. Suppliers differ in whether prices include tax, whether cancellation terms are structured or free text, whether availability is authoritative or advisory, and in throughput ceilings that vary by orders of magnitude.

The failure pattern is well established: a team models the union of all supplier capabilities, the canonical availability object grows to forty fields of which any given supplier populates twelve, and every integration change ripples through the aggregation layer.

The working pattern models availability, price with a defined tax treatment, cancellation terms and a booking handle — what the product needs — and represents everything else as declared capabilities. The aggregator fans out in parallel under a global deadline, treats partial results as the normal case, and applies each partner's reliability profile from configuration.

The same structure recurs in communications platforms with per-carrier differences, and in retail integrations where inventory reporting quality varies enormously by partner.

Failure scenarios

• Silent defaulting. An adapter filling a missing field with a plausible value turns a partner's data gap into a platform correctness problem nobody can attribute.
• Capabilities that no product surface uses, accumulating as configuration nobody maintains.
• Capability drift — the declaration says one thing and the partner does another, with nothing detecting the divergence. Capabilities need verification against observed behaviour.
• Branching on partner identity rather than on capability, which reintroduces the coupling the pattern removes.

Trade-offs

Capability flags add indirection: reading the product logic requires knowing which capabilities exist and what they mean, and a capability set that grows unchecked becomes its own form of complexity.

They also push a decision onto the product: what should happen when a partner lacks this capability? That question is harder than adding a nullable field, and answering it is the actual value — a nullable field defers the decision until a customer encounters it.

Interview question

"Your platform integrates 300 suppliers with different capabilities. Where do the differences live, and how do you add supplier 301 without touching the aggregation layer or risking the other 300?"