An added API field needs a consumer contract

Adding an API response field is compatible only under a contract that allows consumers to receive it. A version label cannot create that tolerance after the fact. Providers should preserve the meaning of existing fields and establish what clients do with unfamiliar data before treating additive changes as independent releases. Consumers, in turn, need to decide where ignoring data is appropriate and where strict validation protects a real requirement.

In Sean Goedecke’s essay dated 24 August 2025, additive response changes are described as typically acceptable, with a strong normative argument that consumers should ignore unexpected fields. This November 2026 retrospective agrees with the value of that convention but challenges the leap from a desirable convention to a fact about existing consumers. Calling a client irresponsible does not stop it from failing.

The field count is not the whole contract

Imagine a proposed delivery-status API that adds an optional display label while leaving the existing status value unchanged. A consumer that reads only the documented status can continue its work if it permits unknown response members. A consumer that validates an exact object shape may reject the same response. This is an illustrative compatibility question, not a tested client result.

The provider has made one structural addition, but the two clients have different acceptance rules. Neither the unchanged endpoint nor a minor version number decides which behavior occurs. The important evidence is the agreed response policy and the actual behavior of supported consumers. A compatibility claim describes that relationship; it is not simply a property of the provider’s diff.

Existing semantics matter even when no key is removed. Suppose the provider adds a label but also changes what the old status means. The visible addition can distract from the behavioral change. If an established value previously meant delivery completed and now means delivery attempted, clients may make different business decisions while parsing exactly as before. This hypothetical shows why structural tolerance cannot stand in for semantic stability.

Requests and responses have different jobs

Ignoring unknown response members can let a provider extend information without coordinating every client. Rejecting unknown request members can protect a caller from a misspelled option that would otherwise be silently ignored. Those policies can coexist. “Be tolerant of JSON” is too vague to explain which side owns an unfamiliar field or what accepting it would mean.

For the proposed status service, a read-only client might discard a new display label after parsing. A command endpoint receiving an unknown delivery instruction might instead reject the request with an actionable error. The distinction follows who is expressing intent. A response addition offers information; a request field may be the caller’s attempt to instruct the system to do something consequential.

Round trips complicate that distinction. A consumer may fetch a resource and later submit a replacement document. Discarding unfamiliar fields during the read could lose information during the write if the protocol requires preservation. Before recommending permissive parsing, determine whether the client merely reads, selectively updates or replaces a complete representation. These are proposed contract questions, not findings from an integration inspected here.

Strict consumers can have legitimate constraints

The strongest counterargument is an integration that deliberately accepts only a certified schema, signs an exact representation or uses generated clients with a fixed validation policy. A new member may violate a real acceptance condition. That condition can be expensive to change and may belong to a different organization. It deserves investigation rather than a moral judgment about the consumer’s engineering.

Permissiveness can also conceal schema drift. A typo in a newly introduced field could go unnoticed if every unknown member disappears without observation. A design can distinguish accepting a response from silently ignoring all evidence of change. For example, a client could tolerate extensions at the designated boundary while surfacing unexpected shapes through an appropriate diagnostic process. This is a proposal, not a universal implementation recipe.

The provider still has a strong reason to establish an extension policy early. If strictness is unnecessary, consumers can preserve stability by validating the fields they depend on and allowing documented extension points. The useful debate concerns where that policy belongs and how it is communicated. It should not become an instruction to stop validating identifiers, permissions or values used for business decisions.

Make the compatibility claim falsifiable

A proposed contract should state that response objects may gain members, identify any closed portions and preserve the meanings of established members. It should distinguish absent values from explicit nulls wherever the application relies on that difference. Adding an optional member should not quietly make old clients responsible for an action they cannot express.

Acceptance work should then target the disputed relationship. Supply an additional unknown response member to a representative consumer and observe whether the documented operation still completes. Separately check that established values retain their meaning. Those are suggested tests for a team owning the integration; no generated client, parser or downstream application was executed for this article.

Where the consumer cannot change immediately, coordination may be the responsible choice. An opt-in representation or another agreed compatibility path can provide room to migrate. These options have operating costs and should not be introduced automatically. The decision depends on the clients the provider actually promises to support, including clients outside its own deployment schedule.

For custom software development, write the extension rule where both sides can find it and assign an owner to exceptions. A useful additive-change policy lets providers evolve without surprising supported consumers. It earns that independence through an agreed tolerance boundary and preserved semantics. “We only added a field” is the start of the compatibility argument, not its evidence.