# ADR 0019: A list in the query string is written as the endpoint declares under `match.query_arrays`

- Status: accepted
- Date: 2026-09-30

## Context

A request field whose value is a list has two common wire forms in a query string: one item per value (`?state=WA&state=OR`, OpenAPI's default `explode: true`) and one item joining them (`?state=WA,OR`, `style: form, explode: false`). The mock knew only the first. It expands a recorded list into repeated items and compares those with the parsed query, so a client that sent `state=WA,OR` could never match its own recording.

api.weather.gov reads every array filter comma-separated, and a repeated key keeps only the last value. Measured on 2026-09-30: `/stations?id=KSEA&id=KPDX` returned KPDX alone, `id=KSEA,KPDX` returned both; `/zones?area=WA&area=OR&type=forecast` returned OR's 56 zones, `area=WA,OR` returned 124. The weather-gov cores sent repeated keys, so every multi-value filter dropped values without an error, and a mock that accepts only repeated keys pinned that bug in place.

Making the mock accept either form was rejected. It would pass a client that sends the form the API misreads, which is the bug that went unnoticed. A per-project setting was also rejected: the form is a property of how one endpoint parses its query, like `redacted` and `match.ignore` (ADR 0018), and one API can mix both.

## Decision

An endpoint declares `match: {"query_arrays": "comma"}` when its API reads a list in the query string as one comma-separated item. The default is `repeat`. For a `comma` endpoint, each recorded list expects one comma-separated query item. Its elements retain the existing scalar number/boolean matching tolerance (`1.0` matches `1`, and `True` matches `true`), while order and multiplicity stay strict. Scalar strings containing commas are compared whole. An empty list is left out, as it is for a repeated key. A repeated key, or the values in another order, is a 422.

This declaration applies to query-string serialization. Under ADR 0006, query-role fields can also arrive in a JSON body: arrays there are compared structurally, with their original order, rather than converted to comma text. Supplying the same array in both the query and JSON body is refused.

A JSON body must carry an array for a recorded array; a JSON string such as `"A,B"` does not match `["A", "B"]`. Form-urlencoded bodies retain the declared comma wire form. Pooled JSON arrays distinguish booleans from numbers at every nesting level, while equivalent numbers such as `1` and `1.0` still match.

HTTP mismatch and ambiguity diagnostics name each candidate's `query_arrays` form alongside its recorded request. Declared redacted names are removed from that diagnostic request, including inside recording envelopes.

`match` now holds `ignore`, `query_arrays` or both, and a `match` block with neither is refused.

The core writes the wire form. The declaration tells the mock what that form is; the generated code does not read it.

## Consequences

A recording with two values in one filter now proves the wire form in every language that replays it through `truewire mock`, because a core that sends the other form gets a 422. A recording with one value per filter proves nothing about the form, since `[x]` renders `x=x` either way.

A value containing a comma cannot be told apart from two values on the wire. That is the API's own ambiguity, and it is not solved here.

Other forms (`pipeDelimited`, `spaceDelimited`, `deepObject`) are not admitted until an API needs one.