Interface Control Document or Service Contract¶
Interface specification — instantiates Distributed Coordination Architecture
Freezes one recurring exchange between two parties into an explicit contract — objects, semantics, guarantees, acknowledgment, and versioned change rules — so neither side has to renegotiate it.
An Interface Control Document or Service Contract stabilizes a single recurring exchange at the boundary between two parties by writing down exactly what crosses it and what each side may rely on: the objects or messages, their semantics and units, the quality and timing guarantees, the acknowledgment and failure behavior, and — the part that keeps it honest over time — a versioning and compatibility policy so the interface can evolve without silently breaking the other side. Its defining move is that it is narrow and deep: one boundary, fully pinned, so the two parties can build independently against the contract instead of negotiating continuously. It is not the whole-parties agreement (that governs who and why) and not the shared picture of system state (that shows what is true now); it is the durable spec of this one seam and how that seam is allowed to change.
Example¶
A payments provider and an online merchant integrate over a web API, neither side controlling the other end of the seam. Rather than coordinate every release by email, the provider publishes a versioned service contract for the one exchange that matters: the request and response objects for a charge (fields, amounts in minor currency units, the idempotency-key semantics), the guarantees the merchant may rely on (error codes, retry behavior, a stated latency target), and — the part that keeps the seam honest over time — a compatibility policy: additive-only changes within a major version, a new major version for anything breaking, and a fixed deprecation window (say, ≈12 months) before an old version is retired. The merchant builds against v2 and can ignore the provider's internal refactors entirely. When the provider must change how a charge is captured, it does not mutate v2 in place — it ships v3, announces the retirement date for v2, and runs both in parallel through the window. The seam holds because the contract, not a shared understanding, is the source of truth, and because change arrives on an announced cadence rather than as a production surprise.
How it works¶
- Pin the exchanged objects and their exact semantics — fields, units, meaning, encoding — so both sides interpret the exchange identically.
- State the guarantees each side can rely on: quality, timing, acknowledgment, and what happens on failure, so the dependency is explicit rather than assumed.
- Define versioning and compatibility — deprecation windows, backward-compatibility rules, and a migration path — so a change is announced and non-breaking rather than discovered in production.
- Keep it bilateral and bounded. One interface, fully specified; it does not reach into either party's internals beyond the boundary.
Tuning parameters¶
- Formality — a lightweight published schema versus a fully signed, controlled document. More formality prevents drift but slows every change.
- Compatibility policy — strict backward compatibility versus permitted breaking changes with migration windows. Trades consumer safety against evolution speed.
- Granularity — one coarse contract versus many fine ones. Fine contracts localize the blast radius of a change but multiply what must be maintained.
- Verification depth — how much handoff evidence a valid exchange requires, from a schema check to a full conformance test suite.
- Deprecation window — how long superseded versions stay supported; generous windows protect laggards but strand the interface in its past.
When it helps, and when it misleads¶
Its strength is that it lets independently controlled parties build in parallel across a boundary without continuous negotiation, and it catches breaking changes before integration rather than during it. Its central failure mode is contract drift: a document that no longer matches the running reality is worse than none, because both sides confidently trust a lie. Its classic misuse is over-specifying — reaching past the boundary to constrain a party's internal behavior, erasing the very freedom the contract was meant to protect — or maintaining a "living" interface that nobody actually versions, so breaking changes slip through the seam. The discipline that keeps it honest is version discipline backed by conformance tests as the real source of truth: the contract is trustworthy only as far as something checks that both sides still obey it.[n1]
How it implements the components¶
An ICD fills the boundary-contract components — the parts a bilateral specification can own:
interface_and_commitment_contract— it is the interface-and-commitment contract for one seam: the exchanged objects, their semantics and guarantees, and who may rely on what.adaptation_and_reconfiguration_cadence— its versioning, compatibility, and migration policy is the interface-scoped reconfiguration cadence, with explicit deprecation and rollback for that seam.
It does not keep the running ledger of who owes what across the whole system (that is the Commitment and Dependency Register), display the live shared state (that is the Shared Coordination Board), or push change events to subscribers (that is the Event-Driven Coordination Channel). And the architecture-wide question of whether the coordination mode itself still fits belongs to the Joint Operating Agreement and the Coordination Health Review, not to any single interface's version policy.
Related¶
- Instantiates: Distributed Coordination Architecture — the ICD is how a recurring cross-boundary exchange is made reliable without continuous negotiation.
- Consumes: the Dependency and Interaction Map identifies which handoffs are stable and consequential enough to be worth a formal contract.
- Compare: Interface Control Document and Contract Test governs the same kind of seam but enforces it differently: this page is the versioned bilateral spec and its change/deprecation cadence, while that mechanism adds executable CI contract tests that fail the build the moment either side ships an incompatible change. Spec-and-cadence here; test-enforcement there.
- Sibling mechanisms: Joint Operating Agreement · Shared Coordination Board · Synchronization Checkpoint · Event-Driven Coordination Channel · Commitment and Dependency Register · Liaison and Integrator Role
Editorial Notes¶
Form Classification¶
Form family: Rule, Policy & Commitment
Rationale: Interface Control Document or Service Contract operates as a standing rule, threshold, contractual commitment, or policy constraint governing future conduct because it freezes one recurring exchange between two parties into an explicit contract — objects, semantics, guarantees, acknowledgment, and versioned change rules — so neither side has to renegotiate it
Independent corroboration: The frozen evidence defines Interface Control Document or Service Contract as 'Freezes one recurring exchange between two parties into an explicit contract — objects, semantics, guarantees, acknowledgment, and versioned change rules — so neither side has to renegotiate it', so its operative form is Rule, Policy & Commitment.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Engineering & Design
Origin pattern: Convergent development
Present-day reach: Multi-domain
Rationale: Explicit objects, semantics, guarantees, and change rules at recurring interfaces descend from systems-engineering interface control.
Related originating lineages:
- Computer Science & Software Engineering — Service contracts and semantic versioning materially adapt the pattern to software exchanges.
- Organizational & Management Science — Service-level agreements materially extend the contract to recurring inter-unit handoffs.
Review outcome: Independent reviewer agreement; high confidence.
Notes¶
A contract pays off only at stable, recurring boundaries. For a one-off exchange or a seam still changing shape every week, the specification overhead exceeds its value, and a human Liaison and Integrator Role or a shared board carries the coordination better until the interface settles enough to be worth freezing.
[n1] Semantic Versioning (SemVer) is a widely used convention for signaling, in the version number itself, whether a change is backward-compatible or breaking. It is a concrete instance of the compatibility policy an ICD needs, and it works only when a conformance check actually enforces the promise the number makes. ↩