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 satellite bus team and an instrument team, in different organizations, must integrate their hardware eighteen months from now. Instead of meeting weekly to reconcile assumptions, they sign an ICD: the mechanical interface (bolt pattern, mass budget, envelope), the electrical interface (bus voltage, peak draw, connector pinout), the thermal interface, and the data interface (telemetry frame format, command set, timing). Each team then builds to the document in parallel, largely without contact. When the instrument later needs two more watts, that is not a hallway surprise at integration — it is a formal change request against the ICD, checked for compatibility and versioned, with the affected side notified. The seam holds because the contract, not a shared memory, is the source of truth.

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.^[1]

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.

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.
Sibling mechanisms: Joint Operating Agreement · Shared Coordination Board · Synchronization Checkpoint · Event-Driven Coordination Channel · Commitment and Dependency Register · Liaison and Integrator Role

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.

References¶

[1] 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. ↩