SKILL.md
API contract test designer
An evidence-first workflow to design consumer-visible compatibility tests for an API boundary.
- Revision
- 2
- Verified
- 2026-10-20
Compatibility and paths
Codex
skills/contract-test-design/SKILL.mdClaude Code
.claude/skills/contract-test-design/SKILL.mdVS Code
.github/skills/contract-test-design/SKILL.mdTrust and provenance
Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.
Generated assetReady to copy or download
---
name: contract-test-design
description: Designs compatibility tests from a published schema AND a concrete old consumer's assumptions. Use before changing an API representation; preserve independent failing field/type/enum examples and a limited additive control without assuming all additions are safe.
license: CC-BY-4.0
compatibility: Offline review and the included owned Node22.13+ exercises need no credentials, network or package installation. Untrusted repository execution requires separate review.
metadata:
author: oneliners
version: "2.0.0"
---
# API contract test designer
## Name both sides of the boundary
Collect published server schema/revision, supported client versions, actual consumer parsing/validation assumptions, error contract, status/header behavior and rollout overlap. A server validating its own new schema proves neither old-client compatibility nor correct behavior on the wire. Pin the schema version and dialect used by your actual tooling rather than upgrading the specification during review. Treat sample JSON as evidence only when tied to a contract and consumer.
## Worked v1 consumer schema subset
This JSON Schema-style subset expresses the fixture's required object fields, permissive additional properties and closed enum. It is not a complete OpenAPI document, and the following small function implements only these explicitly named consumer checks.
```json
{
"type": "object",
"required": [
"id",
"amount_cents",
"currency",
"status"
],
"additionalProperties": true,
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"amount_cents": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"status": {
"type": "string",
"enum": [
"issued",
"paid"
]
}
}
}
```
Consumer function:
```js
function oldInvoiceConsumerContract(value) {
const errors = [];
if (!value || typeof value !== "object" || Array.isArray(value)) return ["object_required"];
if (typeof value.id !== "string" || value.id.length === 0) errors.push("id_string_required");
if (!Number.isSafeInteger(value.amount_cents) || value.amount_cents < 0) errors.push("amount_cents_nonnegative_safe_integer_required");
if (value.currency !== "USD") errors.push("currency_USD_required_by_this_consumer");
if (!["issued", "paid"].includes(value.status)) errors.push("status_not_supported_by_v1_consumer");
return errors;
}
```
Independent candidate responses:
```json
{
"legacy": {
"id": "invoice-fixture-42",
"amount_cents": 1250,
"currency": "USD",
"status": "issued"
},
"renamed": {
"id": "invoice-fixture-42",
"amount": "12.50",
"currency": "USD",
"status": "issued"
},
"newEnum": {
"id": "invoice-fixture-42",
"amount_cents": 1250,
"currency": "USD",
"status": "void"
},
"additiveForThisConsumer": {
"id": "invoice-fixture-42",
"amount_cents": 1250,
"amount": "12.50",
"currency": "USD",
"status": "issued"
}
}
```
## Reviewed compatibility matrix
Consumer contract: the supplied v1 client requires nonempty id, nonnegative safe-integer amount_cents, currencyUSD and status issued|paid; it explicitly ignores unknown fields. Schema/fixtures are synthetic invoice-shaped data, not a real payment integration.
| Candidate fixture | Old consumer result | Compatibility finding |
| --- | --- | --- |
| legacy | PASS | Current required fields/types/enum preserved. |
| renamed | FAIL amount_cents_nonnegative_safe_integer_required | A decimal amount string is not the required integer-cents field; renaming/removing it breaks the old consumer. |
| newEnum | FAIL status_not_supported_by_v1_consumer | Adding void to server output can break a client's closed enum even if the server's new schema accepts it. |
| additiveForThisConsumer | PASS | Old field retained and new amount field ignored under this client's explicit unknown-field policy. This is not proof every consumer accepts additive fields. |
Recommended gate: run the preserved v1 consumer contract against the proposed server representation AND its current fixture; add independent negative cases for missing/null/type/enum boundaries and error responses. Require a new-client contract separately; do not validate only against the new server schema. Treat renamed field and new status as separate mutations so one early error does not hide the other.
Overlap plan: retain amount_cents and supported status behavior for documented v1 consumers, or use a versioned representation with tested negotiation/migration. Define owner, supported client versions, deployment overlap and deprecation evidence before removal. A passing DTO check does not prove routing, authorization, pagination, cache behavior, atomic writes or real network compatibility.
This fixture's consumer function checks a named subset of the schema; it is not a complete JSON Schema/OpenAPI validator. No server/client was deployed and no invoice, account or money operation was accessed. The result identifies two concrete compatibility failures and one explicitly limited additive control.
## Prioritized suite
Keep the legacy response passing. Mutate one required field at a time: missing, null, wrong type, invalid enum and unsafe numeric boundary. Include a separate unknown-field case using the real consumer's permissive or strict policy. Test nullable versus optional behavior deliberately; do not let a convenience parser coerce a string into an integer and conceal a wire-contract change. Add error envelopes/statuses and relevant headers as distinct assertions. For request schemas, test both accepted old input and rejected invalid input; response compatibility and request compatibility can move in opposite directions.
## Provider and consumer verification
Run the old consumer contract against the provider candidate in an isolated approved environment, with exact build/schema/client identities recorded. Validate requests/responses using the project's supported schema tooling in addition to the actual consumer path. A stub returning a checked-in JSON file can prove the DTO expectation but cannot establish that the deployed provider emits it, enforces permissions or shares its transaction semantics. Keep those gaps explicit rather than claiming end-to-end coverage from this fixture.
## Output and stop conditions
Return contract/version, consumer assumption, proposed change, failing minimal response, precise error, safe overlap option, release gate and unverified layers. Preserve legacy fixtures as regression evidence. Do not generate client upgrades or remove fields just because the newest schema allows them. Unknown consumers, unsupported dialect/tooling or missing deprecation policy require owner review before a compatibility claim. The [OpenAPI specification](https://spec.openapis.org/oas/latest.html) describes contract structure; this example intentionally does not assert that a hand-written subset replaces a full validator.
Real example
Input
Review these synthetic candidate responses against the supplied old consumer, not just the new server schema.
{
"schemaSubset": {
"type": "object",
"required": [
"id",
"amount_cents",
"currency",
"status"
],
"additionalProperties": true,
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"amount_cents": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"enum": [
"USD"
]
},
"status": {
"type": "string",
"enum": [
"issued",
"paid"
]
}
}
},
"fixtures": {
"legacy": {
"id": "invoice-fixture-42",
"amount_cents": 1250,
"currency": "USD",
"status": "issued"
},
"renamed": {
"id": "invoice-fixture-42",
"amount": "12.50",
"currency": "USD",
"status": "issued"
},
"newEnum": {
"id": "invoice-fixture-42",
"amount_cents": 1250,
"currency": "USD",
"status": "void"
},
"additiveForThisConsumer": {
"id": "invoice-fixture-42",
"amount_cents": 1250,
"amount": "12.50",
"currency": "USD",
"status": "issued"
}
}
}Expected result
Consumer contract: the supplied v1 client requires nonempty id, nonnegative safe-integer amount_cents, currencyUSD and status issued|paid; it explicitly ignores unknown fields. Schema/fixtures are synthetic invoice-shaped data, not a real payment integration. | Candidate fixture | Old consumer result | Compatibility finding | | --- | --- | --- | | legacy | PASS | Current required fields/types/enum preserved. | | renamed | FAIL amount_cents_nonnegative_safe_integer_required | A decimal amount string is not the required integer-cents field; renaming/removing it breaks the old consumer. | | newEnum | FAIL status_not_supported_by_v1_consumer | Adding void to server output can break a client's closed enum even if the server's new schema accepts it. | | additiveForThisConsumer | PASS | Old field retained and new amount field ignored under this client's explicit unknown-field policy. This is not proof every consumer accepts additive fields. | Recommended gate: run the preserved v1 consumer contract against the proposed server representation AND its current fixture; add independent negative cases for missing/null/type/enum boundaries and error responses. Require a new-client contract separately; do not validate only against the new server schema. Treat renamed field and new status as separate mutations so one early error does not hide the other. Overlap plan: retain amount_cents and supported status behavior for documented v1 consumers, or use a versioned representation with tested negotiation/migration. Define owner, supported client versions, deployment overlap and deprecation evidence before removal. A passing DTO check does not prove routing, authorization, pagination, cache behavior, atomic writes or real network compatibility. This fixture's consumer function checks a named subset of the schema; it is not a complete JSON Schema/OpenAPI validator. No server/client was deployed and no invoice, account or money operation was accessed. The result identifies two concrete compatibility failures and one explicitly limited additive control.