Strict JSON Parsing Is Part of Your API Contract

Two services can accept the same JSON bytes and still disagree about what the request means. One parser may keep the first occurrence of a duplicate member, another may keep the last, and a third may reject the object. If an API gateway, authorization layer, and business service make different choices, a request can pass one check and reach another component with changed meaning.

Go 1.27 has made that old interoperability problem newly visible. The Go team made encoding/json/v2 and encoding/json/jsontext generally available on November 4, 2026. The release attracted a substantial Hacker News discussion, but the lesson for API teams is larger than a Go package upgrade: JSON parsing behavior is part of the API contract, even when OpenAPI never mentions it.

The goal is not to demand one parser for every component. It is to define one accepted wire format, test it at every boundary, and make rejection explicit when components could interpret a payload differently.

Key Takeaways

• JSON syntax, schema validation, and business validation answer different questions.
• Go's v2 defaults reject invalid UTF-8 and duplicate object member names; v1 compatibility remains available.
• A gateway schema check should not be assumed to reproduce an application's parser semantics.
• Migration tests need malformed and ambiguous byte sequences, not only valid Go values.
• Rejecting ambiguity early is useful, but the service still owns authorization and business invariants.

The Contract Begins Before the Schema

An OpenAPI schema can say that role is a string with two allowed values. It cannot help if two parsers disagree about which role value exists:

{"user":"42","role":"viewer","role":"admin"}

RFC 8259 says object member names should be unique and warns that behavior becomes unpredictable when they are not. Implementations have historically differed: some report the last pair, some report an error, and some expose every pair. A schema engine usually receives a decoded object after that choice has already been made.

The same separation appears with invalid UTF-8, trailing data, case-insensitive field matching, unknown members, number precision, and null. These are not all syntax errors, and different APIs may intentionally choose different policies. The contract must say which bytes are acceptable and what each accepted value means.

Model the request path as four layers:

flowchart LR
    Bytes[HTTP body bytes] --> Syntax[JSON syntax policy]
    Syntax --> Schema[Schema and size policy]
    Schema --> Binding[Language data binding]
    Binding --> Rules[Authorization and business rules]

The layers can run in more than one component. What matters is that a later layer never receives a meaning that an earlier policy did not evaluate.

What Go 1.27 Changes

The original encoding/json package remains supported under the Go compatibility promise. Go 1.27 adds stable v2 packages rather than silently changing every v1 call site. That is important because stricter behavior can break an application that unknowingly depends on older defaults.

The Go announcement identifies several v2 defaults with contract impact:

• invalid UTF-8 produces an error;
• a duplicate object member name produces an error;
• object members match Go struct fields case-sensitively;
• nil slices and maps marshal as empty arrays and objects rather than null;
• time.Duration has no implicit representation and requires an explicit choice.

These are v2 defaults, not claims about every JSON implementation. Most behavior differences have compatibility options, and v1 and v2 can interoperate while call sites migrate. That makes a staged rollout possible, but it also creates a mixed-mode period in which two services—or two paths inside one service—may apply different rules.

Do not test the migration only by marshaling a struct with v1 and v2 and comparing happy-path output. Start with captured request bytes and include the cases that motivated the new defaults.

Keep Gateway and Application Responsibilities Separate

An API gateway is a useful place to enforce a documented request envelope: methods, content type, maximum body size, required properties, types, lengths, and enumerated values. It is not automatically the final authority on how an application parser binds JSON into language types.

In Apache APISIX 3.19, the request-validation plugin can validate headers and a decoded request body against JSON Schema. Its documented default maximum buffered request body is 67,108,864 bytes, and its default rejection status is 400. Configure a smaller route-specific limit when the API does not need such a large body.

The tagged APISIX 3.19 implementation reads the body, decodes it, and passes the resulting object to schema validation. After a JSON body passes, the plugin re-encodes that decoded object and replaces the request body sent upstream. This keeps the object checked by the schema aligned with the JSON representation forwarded on that managed path.

That normalization has a precise boundary. The documentation does not promise that duplicate JSON member names are rejected; their treatment occurs during APISIX's decode step before schema validation. Re-encoding also does not control how the application binds the normalized JSON into language types, and it does not cover a client that can reach the service without this plugin. Therefore, test the managed path, application binding, and any direct or alternate path rather than claiming that a body schema makes every parser equivalent.

That boundary supports a safer design:

Send the exact same raw-byte corpus through the complete managed route and every alternate path. Capture the normalized body forwarded by the gateway, then verify the application's binding and outcome. A decoded object used as the test input is insufficient evidence because it has already discarded the ambiguity you need to detect.

Build an Ambiguity Test Corpus

Create a small, versioned set of raw HTTP requests. It should include valid examples plus cases such as:

1. a duplicate security-relevant member with conflicting values;
2. an unknown member next to a valid object;
3. invalid UTF-8 inside a string;
4. a valid JSON value followed by trailing non-whitespace data;
5. field names that differ only by case;
6. integers beyond the exact range used by a downstream runtime;
7. null, absent, empty-array, and empty-object variants;
8. duplicate or conflicting Content-Type headers;
9. compressed and uncompressed bodies near the configured limits.

For each request, record the expected outcome at every hop: accepted or rejected, status code, stable error identifier, and whether the upstream received a request. Treat a disagreement as a release blocker when it can change authentication, authorization, money, quota, routing, or object ownership.

API tests should also compare versions during migration. Run the corpus against the current v1 path, the proposed v2 path, and any compatibility options. A deliberate behavior change belongs in release notes and consumer tests; an accidental difference belongs in the defect queue.

API7's guide to preventing breaking API changes covers broader compatibility practices. The strict-parser corpus adds a lower layer: it verifies that both versions agree on which request exists before comparing the response.

Return Errors Clients Can Act On

Strict rejection helps only when clients can distinguish a permanent contract error from a transient infrastructure failure. A duplicate member or invalid UTF-8 should not look like an upstream timeout that invites a retry storm.

Use a stable error code, a concise message, and a request identifier that is generated or overwritten at a trusted boundary. Avoid echoing the entire malformed body into logs or responses. The raw body may contain credentials or personal data, and some invalid byte sequences are unsafe to render.

The article on structured HTTP API errors explains the response side of that contract. Align those errors with gateway rejections so a client does not need unrelated parsers for every failure source.

Observability should count rejection classes without treating every rejected request as an attack. A deployment with new v2 defaults may initially expose legitimate clients that sent duplicate names accidentally. Measure by route, client identity when trustworthy, parser version, and reason; then fix or explicitly grandfather the contract instead of weakening the default invisibly.

Migrate One Boundary at a Time

A practical Go migration can proceed in four stages:

1. Inventory parser call sites. Include custom UnmarshalJSON methods, stream decoders, middleware, signature verification, and test helpers.
2. Run v1 and v2 in comparison mode. Use production-shaped samples in a protected environment and record accept/reject and bound-value differences. Do not process the request twice in production when that would repeat side effects.
3. Choose compatibility options explicitly. Document each retained v1 behavior, its owner, and an exit condition. Avoid a single global switch when routes have different contracts.
4. Change the authoritative path. Release client-facing behavior notes, watch rejection metrics, and keep a bounded rollback that restores the previous parser without changing unrelated API policy.

Go's migration support makes gradual adoption possible; it does not decide which behavior your API promises. That decision belongs to the API owner and must be reflected in specifications, examples, tests, gateway policy, and service code.

Make One Meaning the Success Condition

Strict JSON parsing is not a language preference. It is a way to prevent a request from changing meaning as it moves between enforcement points.

Start with one security-sensitive write API. Capture raw requests, define duplicate-name and UTF-8 behavior, set a route-specific body limit, and run the ambiguity corpus through the gateway and service. Then migrate the application parser with comparison evidence rather than assuming valid fixtures cover the contract.

For a managed gateway enforcement layer, review API7 Enterprise and the API7 Gateway documentation, while keeping parser-specific semantics pinned to the exact service runtime you deploy.