System Interface Contracts

System Interface Contracts

Concept of the skill

Designing and reviewing cross-boundary interface contracts across modules, services, jobs, APIs, event producers/consumers, webhooks, data engineering surfaces, and AI agents/tools.

Concept of the Skill

What it is: System interface contract design is the discipline of making the stable promise at a boundary explicit before independently changing parties depend on it. The boundary may be a module, package, service, background job, queue, API, webhook, database read/write surface, AI tool, agent, or team handoff.

Mental model: A contract has parties, ownership, direction, semantics, data shape, lifecycle, failure behavior, compatibility rules, operational promises, trust boundaries, observability, and tests. A schema describes shape; a contract describes what both sides may safely rely on.

Why it exists: Integrations fail when each side has a private interpretation of "what the other side does." A written contract lets teams deploy independently, lets agents/tools call systems safely, and makes drift visible before it becomes a production incident.

What it is NOT: It is not detailed REST resource design, event envelope/topic design, stored-data modeling, post-failure debugging, or ADR writing after the contract is chosen. It owns the cross-boundary promise and routes detailed protocol work to the relevant neighbor skill.

One-line analogy: A system contract is a load-bearing join: the parts can move independently only because the join's shape, tolerances, and failure modes are known.

Common misconception: A JSON Schema, TypeScript type, OpenAPI file, or tool definition is not automatically the whole contract. Those artifacts are useful syntax and tooling surfaces, but the real contract also includes semantics, permissions, compatibility, deployment order, and what happens when something fails.

Coverage

Design and audit contracts across boundaries: modules, services, event producers/consumers, background jobs, APIs, webhooks, database integration surfaces, and agents. Covers:

• Boundary identity: producer, consumer, owner, dependency direction, audience class, stability level, release channel, and who may approve a breaking change.
• Semantic promise: purpose, allowed states, invariants, forbidden states, preconditions, postconditions, side effects, and source-of-truth rules.
• Data shape: inputs, outputs, required/optional/nullable/deprecated fields, types, units, identifiers, defaults, examples, and redaction rules.
• Operational promises and SLOs: availability, latency percentiles, throughput, concurrency, data freshness, quality thresholds, consistency windows, durability, quotas, measurement windows, and violation response.
• Failure and delivery behavior: typed errors, retryability, timeouts, cancellation, rate limits, ordering, duplicate delivery, idempotency keys, dedup windows, and replay behavior.
• Trust and authorization: authn/authz, tenant isolation, object/property/function-level permissions, data sensitivity, least privilege, and agent/tool permission boundaries.
• Compatibility and evolution: source, wire, and semantic compatibility; backward/forward/full compatibility direction; additive vs breaking changes; versioning, deprecation, sunset, and migration windows.
• Deploy choreography: who upgrades first, whether old and new versions overlap, feature flags, consumer registration, canarying, rollback expectations, and "can I deploy?" gates.
• The producer/consumer robustness split: conservative producers, tolerant readers, and where that principle stops (trust and security boundaries).
• Observability: metrics, logs, traces, correlation IDs, violation counters, SLO/SLA burn signals, freshness lag, and support handoff fields needed to prove the contract is being honored.
• Verification: schema validation, consumer-driven contract tests, provider verification, positive and negative fixtures, compatibility checks, and production monitors.
• Agent-facing contracts: tool schemas, output schemas, side-effect declarations, confirmation requirements, permissions, result formats, and machine-actionable errors for agents and orchestrators.

Philosophy of the skill

A boundary without a contract is a rumor. The implementation may work today because both sides accidentally agree, but the first independent change exposes the missing contract.

Contracts should be specific enough to protect both sides from drift and small enough that teams can keep them true. The contract is not the implementation. It is the stable promise at the boundary.

Design the promise before optimizing the mechanism. A contract should say what the caller may assume and what the callee must guarantee. The transport, framework, schema language, and generated code are implementation choices that support the promise; they do not replace it.

Observable behavior becomes contract — beware the implicit contract. With enough consumers, every observable behavior of your boundary — undocumented field ordering, incidental latency, a quirk in error text, null behavior, retry timing, headers, logs — becomes something someone depends on, regardless of what the written contract says (Hyrum's Law). The defense is to make the real contract explicit and narrow: decide deliberately which observations are public promises, then deliberately vary or hide what you do not guarantee (randomize undocumented ordering, avoid leaking incidental detail) so consumers cannot silently form shadow contracts you never agreed to.

Compatibility is relative to deployment independence. A co-deployed module can tolerate a narrower migration window than a public API, a third-party webhook, or an agent tool exposed through MCP. Design for the least coordinated consumer, not the most convenient producer.

Be conservative as a producer and tolerant as a reader, within limits. The classic framing is the robustness principle — "be conservative in what you do, be liberal in what you accept" (Postel's Law). In practice the producer emits exactly what it promised and changes only additively; the consumer is a tolerant reader that ignores unknown fields and supplies defaults for absent optional fields instead of failing. A consumer that deserializes strictly and throws on an unrecognized field turns every additive producer change into a production incident. Do not, however, tolerate malformed known fields, invalid types, authorization bypasses, money-movement ambiguity, or untrusted input at a security boundary.

Do not hide ambiguity behind Postel's Law. Unbounded tolerance reduces robustness: it lets sloppy producers proliferate, entrenches buggy behavior as a de-facto standard, and is dangerous at security boundaries where malformed input must be rejected (RFC 9413 — Maintaining Robust Protocols, Thomson & Schinazi, 2023). The resolution is not "always be liberal" but scoped tolerance: be tolerant of unknown fields (forward-compatibility), strict about known fields, types, and security-relevant invariants. At a trust boundary (untrusted input, auth, money movement), validate strictly and fail closed unless the contract says exactly what is tolerated, how it is validated, and why accepting it cannot expand authority or hide an attack.

Operational promises are contract terms when consumers plan around them. If a dashboard, data pipeline, tool, or downstream service depends on p99 latency, throughput, availability, freshness, durability, or a quality threshold, record the SLI, SLO target, measurement window, owner, alert threshold, and response when the objective is missed. An SLO without an error budget and a defined violation response is a wish, not a contract (Google SRE — Service Level Objectives). If performance is only aspirational, say it is non-contractual.

Use an anti-corruption layer for contracts you consume but do not control. When an external, legacy, vendor, or cross-team boundary can change independently, isolate it behind a translation layer that maps external shapes and meanings into the internal domain. The ACL owns normalization, defaulting, version bridging, validation, and alerting so external churn does not become internal semantic drift.

Agent consumers need contracts, not prose hints. An agent cannot reliably infer whether an error is retryable, a tool call is destructive, or a field contains sensitive data. Tool and agent contracts must encode structured inputs, structured outputs, permissions, side effects, and machine-actionable failure signals.

Boundary Triage

Use this skill when the task is the contract that lets two independently changing sides work together.

Contract Artifact Choice

Pick the artifact that matches the boundary. A Markdown contract is acceptable for a small internal module; an independently deployed or public boundary needs a machine-readable source of truth plus verification. Each row's compatibility model follows the rules in §Compatibility Rules.

Method

1. Name the boundary and parties. Identify producer, consumer, owner, approver, dependency direction, release cadence, audience class, and trust level. Record who is allowed to make a breaking change, who must adapt, and whether consumers are co-deployed, independently deployed, external, or agentic.
2. Choose the source-of-truth artifact. Decide whether the contract is Markdown, type/IDL, OpenAPI, AsyncAPI, CloudEvents, Protobuf, JSON Schema, Smithy, Pact, MCP, A2A, or a combination. Name which artifact wins when generated code, docs, and implementation disagree.
3. Define the semantic promise. State purpose, allowed states, invariants, forbidden states, preconditions, postconditions, side effects, and source-of-truth rules. Do not stop at field names.
4. Define the data shape. For every input and output field, record required/optional/nullable/deprecated status, type, unit, identifier stability, default, examples, redaction, and whether unknown fields are allowed. Optional-with-default is a distinct, contract-relevant case from required.
5. Define operational promises and SLOs. Record availability, p95/p99 latency, throughput, concurrency, data freshness, data quality, durability, consistency windows, quotas, and capacity limits when consumers rely on them. For each promised objective, name the SLI, target, measurement window, owner, alert threshold (often a burn-rate alert fired before the error budget is fully spent), and violation response (page, degrade, shed load, fail over).
6. Define failure and delivery semantics. Specify typed errors, retryability, retry budget, timeout, cancellation, ordering, duplicate delivery, deduplication, replay, and idempotency. Where duplicate delivery is possible, define the idempotency key source, request fingerprint, retention/expiration window, replay response, and same-key/different-payload conflict behavior. (Detail in §Error, Retry, and Idempotency Contracts.)
7. Define trust and authorization. State authentication, authorization, tenant boundary, object/property/function-level permissions, data sensitivity, least privilege, and whether user consent or confirmation is required before a side effect. An API can authorize the endpoint yet still over-return fields the caller is not entitled to see; name the permission granularity.
8. Protect the internal domain from uncontrolled contracts. If the producer or consumer is external, legacy, vendor-owned, or otherwise outside your control, put an anti-corruption layer at the boundary. Define translation rules, validation, defaulting, version bridging, telemetry, and the owner of external-change response.
9. Classify compatibility before the first change. Decide source, wire, and semantic compatibility obligations. Pick backward, forward, full, or transitive compatibility where schema evolution applies. Define additive, risky, and breaking changes against that mode. (Detail in §Compatibility Rules.)
10. Plan evolution and deploy choreography. A contract change is not atomic across a distributed system — producer and consumer deploy at different times. Record versioning scheme, deprecation policy, sunset date if known, support window, feature flags, consumer notification, rollout order (for a backward-compatible change, ship new consumers first; for a forward-compatible change, ship new producers first), the version-overlap window during which both contract versions are live and both must validate, rollback behavior (a rollback must not strand data already written under the new contract), and canary criteria.
11. Define observability and operational envelope. Add correlation IDs, request IDs, event IDs, trace attributes, contract-version labels, error-type counters, schema rejection counts, dedup collisions, SLO burn-rate signals, latency/reliability/freshness monitors, and support handoff fields. Name the signal that would reveal a violation in production.
12. Verify the contract before implementation drifts. Add schema validation, positive and negative fixtures, consumer-driven contract tests, provider verification, compatibility checks, SLO monitors, and production monitors. Gate deploys for independently deployed parties on verified consumer/provider compatibility. (Detail in §Verification Patterns.)

Compatibility Rules

"Additive vs breaking" is not precise enough by itself — the change is only well-defined relative to which side reads which side's data. First name the compatibility dimension:

This source/wire/semantic distinction is the one Google AIP-180 codifies; it is the missing bridge between schema evolution and real consumer expectations.

Then name the schema-evolution direction when data moves between versions. The cleanest vocabulary comes from the Confluent schema-evolution model; it originates in Kafka schema registries but is a general contract-evolution model that governs synchronous APIs and RPC too:

⚠️ Do not import schema-registry vocabulary blindly into request/response API contracts. In serialization-schema ecosystems (Avro/Protobuf with a compatibility registry), deleting an optional field may be labeled backward-compatible because new readers process old records and old readers safely ignore absent optional writer fields — but field deletion is safe only under that default-on-absence condition, never unconditionally. For request/response APIs, RPC surfaces, and agent tool parameters, the opposite governs: existing public components are treated as immutable, so removing or renaming a field, parameter, endpoint, or enum value is a breaking change regardless of direction (the rule Google AIP-180 codifies). Keep "schema evolution over stored or streamed records" separate from "API surface stability for callers." Pick the model that matches your artifact, then classify every proposed change against it.

Treat these as breaking unless proven otherwise: removing or renaming a field, changing a type or unit, tightening validation, adding a required field, changing default behavior, changing enum meaning, reusing a Protobuf tag number, changing ordering or pagination semantics, changing retryability, weakening auth, changing side effects, or returning a different error class for the same failure.

For Protobuf/typed IDLs, never reuse field numbers or enum numbers that were ever live; reserve deleted tags/names. For JSON-like contracts, prefer optional additions, open enum handling where consumers can safely ignore unknown values, and explicit deprecation before removal. Anything that violates the chosen mode is a breaking change and needs a new version + deprecation window, never a silent edit.

Treat tolerant-reader behavior as a declared compatibility rule, not a blanket excuse to accept anything. Unknown fields can be ignored only when extension semantics allow it. Invalid known fields, malformed types, unsafe enum values, and ambiguous security-sensitive input should be rejected with a typed error so drift is visible instead of silently normalized.

Error, Retry, and Idempotency Contracts

Failures are part of the interface, not an afterthought. A consumer should not parse human prose to decide whether to retry, escalate, or correct input.

• Error identity: a stable, machine-readable type/code per error class so the consumer can branch on the error type; the human message is secondary.
• Retryability: retryable, retry_after (or the protocol-standard equivalent), backoff, retry budget, and the terminal failure class. Distinguish "invalid arguments, do not retry" from "transient, retry with backoff."
• Responsibility: whether caller, provider, owner, or operator action is required.
• Correlation: request ID, trace ID, event ID, tool call ID, or equivalent support handle.
• Idempotency: key source, fingerprinted request fields, retention/expiration window, replay response, conflict-on-mismatch behavior (when the same key arrives with a different payload, reject — do not silently apply), and dedup-store owner.

For HTTP-facing boundaries, RFC 9457 Problem Details (successor to RFC 7807, with an IANA problem-type registry) is the portable default error shape — type (a stable URI identifying the problem class), title, status, detail, instance, plus typed extension members — with Retry-After where appropriate. This is increasingly agent-driven: providers such as Cloudflare now return RFC 9457 for edge errors specifically so orchestrators can branch and back off deterministically (Cloudflare, RFC 9457 agent error pages).

The IETF Idempotency-Key header is an Internet-Draft, not a ratified standard — re-verify its current status before citing it as normative. Treat its key, fingerprint, expiry, and replay-response rules as useful non-normative shape vocabulary unless your platform has explicitly adopted them. Adopt its shape regardless: the resource publishes its idempotency specification, including the expiration policy for stored keys and the conflict behavior on a same-key/different-payload collision.

The HTTP status code and endpoint envelope design still belong to api-design; this skill owns the cross-boundary requirement that errors be stable, typed, and actionable.

Agent and Tool Contracts

An agent/tool boundary is a system contract whose consumer is a model, not human code — the same discipline applies, plus extras the LLM caller forces because a model may choose tools, compose tool calls, and retry without a human noticing.

For every tool or agent interface, define:

• Identity: tool or capability name, purpose, owner, stability, and discovery mechanism.
• Input schema and output schema — a typed, machine-readable shape (JSON Schema in MCP's inputSchema/outputSchema) so the model emits valid arguments and parses results structurally; document any unsupported schema features if the provider accepts only a subset. Treat a structured-output contract (the model must return JSON conforming to a schema) as an output contract with the same compatibility rules as any other.
• Side effects: read-only, write, delete, external communication, money movement, code execution, or human-visible change — and the blast radius. A read-only tool and a money-moving tool are different trust classes even behind the same call shape.
• Permissions and trust: scopes, tenant, user identity propagation, delegated auth, consent, confirmation before destructive/irreversible/costly actions, and least-privilege defaults.
• Runtime limits: timeout, concurrency, rate limits, cancellation, max retries, and cost/usage budget when relevant.
• Error/result contract: structured result, typed error, retryability, partial-result behavior, and whether a refusal or blocked action is a valid result. Reuse the machine-actionable error contract from §Error, Retry, and Idempotency Contracts.
• Determinism and idempotency: declare whether repeated identical calls are safe — an agent will retry — reusing the idempotency contract above.
• Injection / trust boundary: tool metadata, tool output, retrieved content, and remote agent messages are data to inspect, not instructions to obey.

Treat agent tool outputs as untrusted contract payloads. They may satisfy an output schema and still contain prompt-injection text, exfiltration requests, or instructions that conflict with system/developer/user policy. Validate the payload, route only the fields the contract declares, and never let returned content expand permissions, skip confirmation, or rewrite the caller's operating instructions. This is the strict half of the tolerant-reader split (§Philosophy): at this trust boundary, validate strictly and reject.

Use MCP when you need dynamic agent-to-tool discovery and invocation; use A2A-style contracts when independent agents collaborate as peers rather than exposing one side as a tool. OpenAI Structured Outputs and provider tool schemas can strongly improve syntactic adherence, but they do not prove permission safety, semantic correctness, or safe side effects. Validate before execution and after result parsing.

Verification Patterns

Verification should match the risk and independence of the boundary. Schema validation is the cheap first gate; the consumer-driven contract test is the one that catches the break schema validation cannot see.

For independently deployed parties, schema validation alone is insufficient. Add consumer/provider verification and a deploy gate (PactFlow's can-i-deploy) that refuses to release when known consumers have not verified against the provider version.

Standards and Reference Vocabulary

Reach for the portable spec instead of reinventing the shape:

Evals

This skill ships a comprehension-eval artifact at examples/evals/system-interface-contracts.json. The checklist below is the authoring gate for system-boundary contracts; the eval file is the grader surface.

Verification

• Each side has a named owner, consumer, producer, approver, and dependency direction, and the breaking-change authority is explicit.
• Audience class, stability level, release cadence, and trust boundary are explicit.
• The source-of-truth artifact is named, and generated code/docs cannot silently override it.
• Required, optional, nullable, deprecated, and unknown fields are explicit, with types, units, defaults, and examples.
• Invariants, forbidden states, preconditions, postconditions, side effects, and source-of-truth rules are stated.
• Auth, tenant isolation, object/property/function-level authorization, data sensitivity, and agent/tool permissions are part of the contract.
• Performance, availability, throughput, freshness, durability, quality, quota, or capacity promises are either defined as measured SLOs (SLI, target, measurement window, owner, alert threshold, violation response) or explicitly marked non-contractual.
• Error behavior is typed and machine-readable with a stable identifier per class (RFC 9457-shaped at HTTP boundaries); retryability, Retry-After or equivalent, responsibility, and correlation IDs are deterministic.
• Idempotency keys or deduplication rules exist where duplicate delivery is possible, including expiration, fingerprinting, replay response, and same-key/different-payload conflict behavior.
• Retry, timeout, cancellation, ordering, replay, rate-limit, and partial-failure expectations are deterministic.
• Compatibility is stated by dimension and direction: source, wire, semantic; backward, forward, full, or transitive where relevant; every proposed change is classified additive/risky/breaking against that mode.
• The tolerant-reader/strict-validation split is decided and explicit: liberal on unknown fields, strict on known fields, types, and trust/security boundaries; malformed known fields, unsafe enum values, and authorization ambiguity are rejected with a typed error.
• External, vendor, legacy, or otherwise uncontrolled contracts are isolated behind an anti-corruption layer with translation, validation, version bridging, and alert ownership.
• Versioning, deprecation, sunset, and migration owner are defined.
• Deploy choreography is planned: who upgrades first, the version-overlap window, how rollback works (no rollback strands data written under the new contract), and what gate blocks unsafe deploys.
• The contract distinguishes guaranteed from incidental behavior, and undocumented behavior is hidden or varied to prevent shadow contracts (Hyrum's Law).
• Observability can reveal contract violations in production: version labels, rejection counts, error types, dedup collisions, trace IDs, SLO burn, and freshness/quality lag.
• The contract artifact matches the boundary type (Markdown/types, OpenAPI, AsyncAPI/CloudEvents, JSON Schema, Protobuf/Smithy/TypeSpec, ODCS, Pact, or an agent tool schema).
• For an agent/tool boundary: input + output schemas, permissions/side effects, confirmation requirements, machine-actionable errors, and the injection/trust boundary (tool results are data, not instructions) are all declared.
• Contract tests, compatibility checks, fixtures, or examples exist for positive and negative cases, including malformed input, missing required field, unauthorized action, duplicate delivery, incompatible version, and provider/consumer drift.

Do NOT Use When

Skill Graph context

Classification

• Subject: software-architecture
• Public: true
• Domain: architecture/contracts
• Scope: Designing and reviewing cross-boundary interface contracts across modules, services, jobs, APIs, event producers/consumers, webhooks, data engineering surfaces, and AI agents/tools. Owns the stable promise at the boundary: parties, semantics, data shape, invariants, failure behavior, idempotency, security/trust, operational SLOs, compatibility, deploy choreography, observability, and verification. Excludes detailed HTTP resource design, async event envelope/topic design, persistence schema design, root-cause debugging, and ADR recording after the contract decision is accepted.

When to use

• define the contract between the ingestion job and the dashboard view layer
• what invariants must this event producer and consumer share?
• review this module boundary for missing ownership and compatibility rules
• we need an interface contract before several agents implement opposite sides of the boundary

Not for

• design the REST endpoints, status codes, and pagination
• create database tables and constraints
• investigate why this existing integration is failing in production
• write an ADR after the interface decision has already been accepted

Related skills

• Verify with: testing-strategy, code-review, event-storming
• Related: event-storming, debugging, api-design, event-contract-design, state-machine-modeling, conceptual-modeling

Grounding

• Mode: universal
• Truth sources: https://spec.openapis.org/oas/v3.2.0.html, https://www.asyncapi.com/docs/reference/specification/v3.1.0, https://github.com/cloudevents/spec, https://modelcontextprotocol.io/specification/2025-06-18/basic/index, https://modelcontextprotocol.io/specification/2025-06-18/server/tools, https://google-a2a.github.io/A2A/specification/, https://platform.openai.com/docs/guides/structured-outputs, https://docs.pact.io/, https://www.rfc-editor.org/rfc/rfc9457, https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/, https://protobuf.dev/best-practices/dos-donts/, https://google.aip.dev/180, https://json-schema.org/draft/2020-12, https://semver.org/, https://www.rfc-editor.org/rfc/rfc2119, https://sre.google/sre-book/service-level-objectives/, https://www.rfc-editor.org/rfc/rfc9413, https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html, `https://martinfowler.com/articles/consumerDrivenContracts.ht

…(truncated)