In WireMock, when does matchingJsonPath() beat equalToJson() for a large peatland survey body?

## Two shapes of assertion A body matcher is an assertion, and WireMock offers it in two shapes. WireMock's `equalToJson(` is a **closed** assertion: it describes the entire document, so anything you did not describe is by implication forbidden. WireMock's `matchingJsonPath(` is an **open** assertion: it describes one place in the document and says nothing about the rest. On a small fixed payload the closed form is fine. On a large one it is a liability, because you end up committing the stub to fields that have nothing to do with why the stub exists. The peatland carbon-survey submission at `POST /carbon/v1/surveys` is the large case. A real submission from a field device carries site identifiers, a `readings` array with one entry per plot, instrument metadata, a client version and a timestamp. Perhaps two of those fields decide which response the stub should return. ## What WireMock's `matchingJsonPath(` actually evaluates WireMock parses the body, evaluates the JSONPath expression against it, and matches when the result is a non-empty selection: - In WireMock, `matchingJsonPath("$.siteId")` matches any submission that carries a `siteId` at all. - In WireMock, `matchingJsonPath("$.readings[0].plotId")` matches when the first reading has a `plotId`, and says nothing about the readings after it. - In WireMock, `matchingJsonPath("$.readings[?(@.waterTableCm < -20)]")` uses a filter, so the stub fires only when at least one plot is drained below twenty centimetres. - WireMock's two-argument form, `matchingJsonPath("$.siteId", equalTo("PEAT-114"))`, constrains the value of the selected node rather than merely its existence. - A body that does not parse as JSON selects nothing, so the pattern fails; there is no text fallback. The value-pattern overload is the part people forget, and it is what makes the matcher genuinely competitive with whole-document matching. Without it you can only say "this field is present"; with it you can say "this field is present and equals this", which is usually the assertion you meant. ## Composing several paths WireMock keeps every pattern handed to `withRequestBody(` in a list and requires **all** of them to match. That turns narrow path predicates into building blocks: ```java stubFor(post(urlPathEqualTo("/carbon/v1/surveys")) .withRequestBody(matchingJsonPath("$.siteId", equalTo("PEAT-114"))) .withRequestBody(matchingJsonPath("$.readings[?(@.waterTableCm < -20)]")) .willReturn(aResponse().withStatus(202))); ``` Read that mapping cold and you know exactly what the stub is for: this site, at least one drained plot. The equivalent written as a relaxed WireMock `equalToJson(` would be a block of expected document in which those two conditions are invisible among a dozen fields that are there only because the recorder captured them. ## When the whole-document form still wins Open assertions are not free. WireMock's `matchingJsonPath(` will happily match a body that has gained a field with real meaning, because it never looked. Prefer the closed form when: 1. The payload is small and stable, and its shape is genuinely what the test is about. 2. You are standing in for an endpoint whose validation rules you want the stub to mirror. 3. A reviewer needs to see the exact request the client is supposed to send, in one place. Outside those cases the open form is usually the honest one, because a stub that pins fields nobody reads is making an assertion nobody chose. ## The same idea elsewhere MockServer expresses the selective JSON matcher as `jsonPath(` on the request body, which is the same idea under a different spelling - a stub author moving between the two products has to change the name, not the thinking. ## Diagnosing a path predicate that never matches When a WireMock `matchingJsonPath(` stub does not fire, the cause is almost always one of a short list: - The expression is valid but selects nothing, for example an index past the end of `readings`. - The body is not JSON at all, so nothing can be selected. - A filter expression compares a string to a number, so it silently selects nothing. - The value pattern is stricter than intended, for instance an exact match where the client sends a trailing space. - The path is right but a second body pattern on the same stub is the one failing, because every pattern must match. Working down that list beats rewriting the expression at random, and the last item is the one that catches experienced people out: adding a path predicate to an existing stub tightens it, and the newly failing condition may be the pattern that was already there. ## The judgment to carry away Choose the matcher that says what the stub is for and nothing more. On a peatland carbon-survey payload with twenty fields, WireMock's `matchingJsonPath(` with a value pattern usually expresses the intent in one line, survives every additive change the client makes, and leaves a mapping the next reader can understand without diffing two JSON documents in their head.