A request arrives containing {"role":"reader","role":"admin"}. If parsing keeps only one value, a schema validator sees a single role field, not the ambiguity that arrived over the wire.
Test duplicate-key rejection by sending raw request bytes through your actual decoding boundary and asserting that ambiguous input never reaches validation or the handler. Ordinary happy-path fixtures will not catch a parser replacement that changes which duplicate value reaches application code.
For an API whose policy is to reject duplicates, enforce that policy while object member pairs are still available, before converting those pairs into an ordinary dictionary.
An already-parsed object cannot reveal keys the parser discarded.
Keep the evidence as raw bytes
A fixture built as a Python dictionary cannot represent two entries with the same key. Serializing that dictionary afterward does not restore the lost input.
Store the request body itself. Use this raw-byte fixture matrix to preserve your policy across parser changes:
| Raw JSON body | Expected outcome | Reason |
|---|---|---|
{"role":"reader","role":"admin"} |
Reject | Duplicate name in one object |
{"user":{"id":1,"id":2}} |
Reject | The rule applies to nested objects |
{"users":[{"id":1,"id":2}]} |
Reject | Objects inside arrays need the same check |
{"role":"reader","\u0072ole":"admin"} |
Reject | Both names decode to role |
{"left":{"id":1},"right":{"id":2}} |
Accept | Each object has its own member names |
Compare decoded key names, not their source spellings. Otherwise, an escaped spelling can bypass a textual duplicate check. This example uses exact decoded-string equality; it does not add case folding or Unicode normalization. Duplicate detection belongs to each object, not the whole document.
The runnable suite below tests only this decoder. Before claiming application coverage, route these raw fixtures through your production decoding path and check that rejection prevents both validation and handler entry.
Detect duplicates before building each dictionary
The reference implementation uses Python's standard library. Duplicate rejection is the API policy being tested, not a universal JSON-decoder requirement.
Save it as json_boundary.py:
import json
class DuplicateKey(ValueError):
pass
def unique_object(pairs):
seen = set()
for key, _ in pairs:
if key in seen:
raise DuplicateKey(f"Duplicate JSON key: {key!r}")
seen.add(key)
return dict(pairs)
def reject_constant(token):
raise ValueError(f"Invalid JSON constant: {token}")
def decode_request(raw):
text = raw.decode("utf-8")
return json.loads(
text,
object_pairs_hook=unique_object,
parse_constant=reject_constant,
)
def dispatch(raw, validate, handler):
document = decode_request(raw)
validated = validate(document)
return handler(validated)
Python's object_pairs_hook documentation describes the hook that receives the decoded member pairs for each object. unique_object checks those pairs before constructing that object's dictionary, so duplicate entries have not yet been collapsed. Nested objects pass through the same hook.
The explicit UTF-8 decode sets the encoding policy. Separately, the parse_constant callback rejects nonstandard constants Python accepts, such as NaN. The boundary raises exceptions on invalid input; an HTTP request layer should translate those failures into your chosen client-error response.
Assert that rejection stops execution
Save this as test_json_boundary.py beside the implementation:
import unittest
from unittest.mock import Mock
from json_boundary import DuplicateKey, dispatch
REJECT_CASES = [
(
"top-level duplicate",
b'{"role":"reader","role":"admin"}',
),
(
"nested duplicate",
b'{"user":{"id":1,"id":2}}',
),
(
"duplicate inside an array",
b'{"users":[{"id":1,"id":2}]}',
),
(
"equivalent escaped name",
br'{"role":"reader","\u0072ole":"admin"}',
),
(
"nested equivalent escaped name",
br'{"user":{"id":1,"\u0069d":2}}',
),
]
ACCEPT_CASES = [
(
"ordinary object",
b'{"role":"reader"}',
{"role": "reader"},
),
(
"same name in separate objects",
b'{"left":{"id":1},"right":{"id":2}}',
{"left": {"id": 1}, "right": {"id": 2}},
),
(
"same name in separate array elements",
b'[{"id":1},{"id":2}]',
[{"id": 1}, {"id": 2}],
),
]
class JsonBoundaryTests(unittest.TestCase):
def test_duplicates_stop_before_validation_and_handler(self):
for name, raw in REJECT_CASES:
with self.subTest(name=name):
validate = Mock(side_effect=lambda value: value)
handler = Mock()
with self.assertRaises(DuplicateKey):
dispatch(raw, validate, handler)
validate.assert_not_called()
handler.assert_not_called()
def test_valid_controls_reach_the_handler(self):
for name, raw, expected in ACCEPT_CASES:
with self.subTest(name=name):
validate = Mock(side_effect=lambda value: value)
handler = Mock(return_value="handled")
result = dispatch(raw, validate, handler)
validate.assert_called_once_with(expected)
handler.assert_called_once_with(expected)
self.assertEqual(result, "handled")
if __name__ == "__main__":
unittest.main()
The raw byte literals prefixed with br preserve the literal backslash escapes in the request body. The JSON decoder, rather than Python's string-literal processing, interprets those escapes.
Run the check locally or as a CI step:
python -m unittest -v test_json_boundary
The negative tests require a specific duplicate-key exception and verify that neither downstream function ran. An eventual error response does not prove rejection happened before validation: a later validation error could hide the fact that ambiguous input crossed the decoding boundary.
The positive controls matter too. A decoder that rejects everything would satisfy the rejection assertions but fail the controls.
Make this test exercise your actual request path
This dispatch function is the integration seam for the standalone suite. In an existing service, adapt the tests to send the same raw fixtures through your application's real ingress path, rather than leaving them attached to an unrelated decoder. Retain at least one integration test at that boundary:
- Send bytes, not a JSON convenience argument. A test client's object-to-JSON helper can erase duplicates before sending the request.
- Observe validation and handler entry. Use test-only spies or injected mocks at those boundaries, with no live dependencies or customer data.
- Assert the external rejection contract. Check the application's chosen client-error response as well as the absence of downstream calls.
- Run the same fixtures against each candidate parser integration. Preserve the expected outcomes instead of accepting whichever interpretation the replacement produces.
If a parser exposes only completed dictionaries, a duplicate check afterward is too late. Choose a decoding path that exposes member pairs or explicitly supports duplicate rejection. Avoid a regular-expression precheck: it must understand string escapes and object nesting to enforce this policy correctly.
For parser differential testing, agreement alone is insufficient. Two implementations can agree to accept an input that your policy requires them to reject. The fixture matrix is the oracle; each implementation must meet it independently.
This focused suite does not cover request-size limits, nesting-depth limits, every malformed JSON input, or differences introduced by upstream parsing. If multiple components parse the body, exercise each relevant boundary, especially any gateway or other component that rewrites the payload before forwarding it.
A five-minute starting exercise is to add the escaped-name fixture to your current request test, send it through the real ingress path, and place spies on both validation and the handler. Assert that neither was called. That checks one easily missed ambiguity; it does not establish coverage of every parser path.