In a generated Pact file, what does one interaction contain and where do its matchingRules live?

## The shape of the file A pact file is plain JSON with four top-level keys: `consumer` and `provider` (each an object with a `name` — together they identify the pair the file belongs to), `interactions` (the array that carries the content), and `metadata` (which spec version and which library wrote it). The name matters because the file is the unit of exchange: one file records everything one consumer expects from one provider, and provider verification replays every interaction in it. ## Anatomy of one interaction An interaction is an object with roughly these members: - `description` — the human label from `uponReceiving`, and the identity of the interaction. - `providerStates` — an array of `{ name, params }`, naming the precondition the provider must set up before this interaction is replayed. The state name is a string the provider side is expected to recognise; the pact file itself carries no setup code. - `request` — `method`, `path`, and optionally `query`, `headers`, `body`, plus its own `matchingRules` and `generators`. - `response` — `status`, and optionally `headers`, `body`, plus its own `matchingRules` and `generators`. `generators` is worth recognising even though it is rarer: it produces a value at replay time (a fresh id or timestamp) rather than asserting one, which is the mechanism behind values that cannot be fixed in the file. ## Where the matching rules live `matchingRules` is **inside the request object and inside the response object of each interaction** — not at the top of the file, not inline in the body. Its structure is category → path → rules: ``` "matchingRules": { "body": { "$.rentalId": { "matchers": [ { "match": "integer" } ], "combine": "AND" } }, "header": { ... } } ``` Categories are the parts of the message a rule can apply to — `body`, `header`, `path`, `query`, `status`. Under `body`, keys are JSON-path expressions against that body, including wildcards such as `$.instruments[*].sku` for every element of a collection. Each entry holds a `matchers` array — `{ "match": "type" }`, `{ "match": "regex", "regex": "..." }`, `{ "match": "integer" }` and so on — and a `combine` value saying how multiple matchers on one path are combined. The body itself still contains ordinary example values. Those examples are what the consumer's mock provider served during the consumer test, and they are what a human reads to understand the interaction — but wherever a matching rule covers the path, the example is illustration, not assertion. ## Reading the obligation off the file That gives a mechanical procedure for answering "what is the provider now required to do?" without running anything. For each interaction: 1. Read `request.method` and `request.path`, adjusted by any `matchingRules` under `path` or `query`: that is the call the provider must accept. 2. Read `providerStates`: the provider must be able to reach each named state, or verification of that interaction cannot run. 3. Read `response.status`: that status is required — it is compared by equality unless a rule under the `status` category says otherwise. 4. Walk `response.body` leaf by leaf. For each leaf, look for a `matchingRules.body` entry whose path expression covers it. - **Covered** — the obligation is the matcher: same type, or matching the regex, and present. - **Not covered** — the obligation is the literal example. This is the step people skip, and it is where surprise red builds come from: an unremarkable-looking `"status": "ACTIVE"` with no rule beside it means exactly that string, every time. 5. Anything **not** mentioned in the response body is unconstrained — the provider may add, remove or change it freely as far as this consumer is concerned. Reading a pact this way is a genuinely useful review skill. Diffing the file across a change shows whether a consumer edit tightened the contract, and a file where nearly every leaf lacks a matcher is a contract that will fail on data rather than on breakage. ## Reading `metadata` first `metadata.pactSpecification.version` tells you which spec the file follows, which changes what you should expect to see. In V2 an interaction carried a single `providerState` string and matching rules were flat entries keyed with a `$.body.` prefix. V3 replaced that with the `providerStates` array, grouped rules under categories, and added `generators`. V4 additionally labels each interaction with a type, so synchronous HTTP interactions and asynchronous message interactions can live in one file. Check that key before concluding a file is malformed — more often it was written against a different specification version than the one you have in mind.