How does a framework bind a repeated query parameter or a single delimited value into a collection handler argument?

## Two ways to say "more than one" A query string is a flat sequence of key/value pairs. It has no native list type, so multiplicity is expressed by convention, and there are two in common use: - **Repetition** — `?tag=red&tag=blue`. The key appears more than once; order is the order it appeared. - **Delimited value** — `?tag=red,blue`. One occurrence whose text encodes several values, usually comma-separated, sometimes with another separator. A third convention appears in some ecosystems: a bracket or other suffix on the key to mark it as a list. None of the three is mandated by the URL grammar or by HTTP. The server side decides what it understands, and the client has to match — which is exactly why a list parameter is worth documenting explicitly rather than assuming. ## What the binder does with each 1. Collect every raw occurrence of the key, in arrival order. 2. If the framework supports delimiters and the declaration asks for it, split each occurrence on the separator. 3. Look up the converter for the **element type**, not for the collection type. 4. Run it on every element. 5. If any element fails, binding normally fails and the request is answered as a client error; a list converts all-or-nothing rather than quietly dropping the bad element. 6. Assemble the results into the declared collection shape. Step 3 is the part worth saying out loud: a collection parameter is really a declaration of *element type plus multiplicity*, and the element converter is the same one a scalar of that type would use. ## The mismatch cases | Wire | Declared | Usual result | |---|---|---| | Key repeated | collection | every occurrence, in order | | Key repeated | scalar | one occurrence kept — first or last, framework-dependent — usually without an error | | Key once | collection | a one-element collection | | Key absent | collection | an empty collection, or an absent marker, depending on the declaration | | Key present, empty text | collection | one empty element, or an empty collection — this is the case frameworks most disagree on | The second row is the quiet one. A handler that expects a single value keeps working when a client starts sending two, and which of the two it keeps may differ between a service and its own test harness. When one value has to mean one value, the parameter should be checked, not assumed. ## Why a delimiter is ambiguous and repetition is not If values may themselves contain the separator, a delimited list cannot be parsed unambiguously: `tag=red,blue` and a single tag literally named `red,blue` produce the same text unless the client percent-encodes the separator inside the element. Repetition has no such problem, because the boundary is structural rather than lexical. That makes repetition the safer default for free-text values, and a delimiter acceptable mainly for closed vocabularies — identifiers, enumerated members, numbers — where the separator cannot legally appear in an element. Round-tripping is the practical test: if a client can take the values it received, put them back in a request, and get the same values, the encoding is sound. ## Operational edges - **Length has no natural bound.** Nothing stops a caller sending the key ten thousand times, or one value with ten thousand elements. Every element is converted, and the resulting collection is held in memory before the handler starts, so an element cap (and a request-size cap) belongs in the configuration, with a client error when it is exceeded. - **Duplicates survive.** Binding does not de-duplicate unless the declared collection shape is a set. If the handler treats the list as a set, say so in the declaration rather than downstream. - **Order is the arrival order**, not a sorted order, and clients should not rely on the server re-ordering. - **An empty element is not nothing.** `?tag=red,,blue` normally yields three elements, one of them empty, which will then fail conversion for any non-text element type. - **Trailing separators** behave the same way, and are a common artefact of client code that joins values with a separator inside a loop. ## What to specify For any list parameter, write down three things: which spelling the server accepts, what an absent key means versus an empty one, and the maximum number of elements. Those three answers remove almost every surprise in this area, and none of them can be inferred by a client from the parameter's name.