Smoke the data contract before go-live—not after the first bad write.
Everyone agreed on the payload in a document. Then the first production write used a field the document forgot, and retries started duplicating. An hour of checks against the real edge in staging is cheaper than learning it from customers.
Before an API or sync edge goes live, assemble the TWIMCO Data Contract Smoke Pack: sample payloads, an idempotency check, a schema-drift assert, and a named failed-write owner. Run the pack in staging with evidence dated. Ownership terms alone are not enough—you need executable smoke checks.
Contracts need smoke, not only signatures
Teams agree on a payload shape in a document. Go-live arrives. The first production write uses a field the document forgot. Retries duplicate. Schema drifts on one side. A failed write has no owner.
An ownership page names who is responsible. A smoke pack proves the edge behaves before traffic. You want both. They are not substitutes.
Keep the pack small. It is not a performance test or a security audit. It checks the promises that hurt when they are wrong: shape, replay safety, drift, and who owns a failed write. It should be runnable in under an hour, or people will not run it.
A vendor certification is not your test. Run the pack against the assumptions your side actually has.
What is in the pack
Sample payloads. A normal one, one that should fail validation, and one boundary case: empty optional field, max length, a timezone edge. Store them as fixtures, not screenshots.
Replay check. Send the same key twice. Confirm you do not get two side effects. Write down who ran it and when.
Schema drift. The consumer checks required fields and types against a known version, and the pack fails if a drift would have slipped through.
Failed-write owner. A named role, and a link to what they do, when a write is partial or rejected.
Dated evidence. The staging output, attached to the go-live ticket.
Optional: a caller without permission is denied cleanly.
Keep the fixtures next to the code that consumes them. When the schema version moves, the fixtures move in the same change, or the pack fails. For a critical consumer, drift should fail the build. A warning-only check is how production becomes the test environment.
How the work moves
Assemble the smoke pack
- Sample payloads
Happy, validation fail, boundary fixtures.
- Idempotency check
Replay same key; no duplicate side effect.
- Schema-drift assert
Consumer fails closed on undetected drift.
- Failed-write owner
Named role and runbook for partials.
A data contract that has never been smoked is a PDF that has not met production.
Make the run honest
Name the environment and the identity the pack uses. A smoke test that only runs as an admin will miss the failure a normal caller hits.
If the edge carries timestamps that drive billing or a service window, include a clock-skew case on purpose. Those bugs are rare until they are expensive.
Include one payload that must be rejected without taking the consumer down.
Keep a short log of runs: date, version, pass or fail, notes. A flaky replay check is a signal, not noise.
When to run
Run it before the first production traffic on a new edge, after a breaking schema change, after a retry-policy change, and again at renewal for any vendor edge you depend on.
Do not go live if the replay check or the failed-write owner is blank. A conditional is allowed only with a person and a date.
After a production incident on that edge, add the fixture that would have caught it. The pack should grow from real pain, not from a wish to be complete.
Failure modes
The contract is only a document. Nobody has executed it.
Only the happy payload. The boundaries show up in production.
Replay is assumed. Someone says the library should handle it.
Nobody owns a failed write. The smoke test fails and the ticket has no name.
Keep the ownership page and the smoke pack under the same edge name, so the next person can find both.
Decision guide
Signed vs smoked
| Consideration | Contract filed | Smoke pack passed |
|---|---|---|
| Payload | Described in a PDF. | Fixtures executed in staging. |
| Retry | Assumed safe. | Idempotency check evidenced. |
| Drift | Found in production. | Assert fails the pack first. |
| Failure | Unowned ticket. | Failed-write owner named. |
Run it while failure is still cheap
Pick the edge you are about to trust. Run the pack somewhere that is not production. Attach the dated result to the go-live ticket.
If you are about to connect this inside an application you own, that proof belongs with web applications.
Related work: Sutton Place.
We build alongside the people doing the work.
Bring us the problem you’re thinking about.