Summary

  • Accept-Patch advertises the patch-document media types a resource accepts. Its presence indicates PATCH capability at that resource, but does not authenticate the caller, grant write access, select a format or validate one proposed change.
  • A safe implementation treats discovery, media-type semantics, state preconditions and authorization as four separate decisions. The field can inform the first request; only the request as actually received can settle the other three.

An OPTIONS response says:

Accept-Patch: application/json-patch+json, application/merge-patch+json

A client has learned something precise. The resource advertises two patch-document media types. The client has not learned that its current account may edit the resource. It has not learned that the two formats mean the same thing. It has not learned whether the representation has changed since it was read, or whether a particular operation would violate a business rule. It certainly has not received a bearer token.

The distinction matters because discovery responses look authoritative. They arrive from the server, use registered names and often sit beside Allow. Software can easily compress that into a single boolean called writable. RFC 5789 provides no basis for that compression. It defines a capability advertisement and separately tells servers to authorize PATCH requests.

Three messages, four decisions

PATCH was standardized because PUT means complete replacement while partial modifications need a patch document whose media type defines how instructions operate on existing state. The target URI still identifies the resource. The request Content-Type identifies the patch language. Preconditions can bind the operation to state previously observed. Authentication and access control decide whether the principal may perform it.

Accept-Patch sits before those request-time decisions. The field lists a comma-separated set of media types, including optional parameters. RFC 5789 says it should appear in an OPTIONS response for a resource that supports PATCH. Its presence in a response to any method implicitly says PATCH is allowed on the resource identified by the request URI, and each listed media type says that format is allowed there.

The word allowed has a deliberately limited object. It describes the method and format at the resource, not the entitlement of every possible principal. The security section separately names authorization, access control and authentication. A public GET response can therefore advertise PATCH even when an anonymous PATCH would receive 401 or 403. A service can expose the same format list to two accounts while allowing them to modify different fields.

There are also useful absences. PATCH can appear in Allow while Accept-Patch is absent; in that case method support is advertised but the format list is not. Conversely, seeing Accept-Patch in a response other than OPTIONS still carries the implicit method indication. Neither form tells the client that policy will remain unchanged.

RFC 9110 says the actual allowed-method set is determined by the origin server at the time of each request and may change dynamically. Capability discovery is therefore an observation, not a lease. A client can cache it for convenience under an application policy, but must be prepared for the later operation to be refused.

The media type is the program

RFC 5789 does not assign PATCH one universal document grammar. It says there is no default patch format that every implementation must support. The server must ensure that the received document is appropriate for the target resource.

That boundary is reinforced by verified Erratum 3169. PATCH semantics come from the request media type. A server should not invent patch behavior for generic application/json or application/xml merely because it can parse those representations. Doing so would make meaning resource-specific and undermine interoperability.

This is why the Accept-Patch list is more than a collection of file formats. Each media type names an instruction system. application/json-patch+json, defined by RFC 6902, carries an ordered array of operations such as add, remove, replace, move, copy and test. application/merge-patch+json, defined by RFC 7396, resembles the target document; members are added or replaced by comparison, while null has the special meaning of removal.

Those formats can both manipulate JSON and still express different intentions. A JSON Patch test can guard a localized assumption inside the operation sequence. Merge Patch is compact for object-shaped documents, yet is unsuitable for structures that depend on explicit null values or require fine-grained array edits. Advertising both does not authorize automatic conversion, and server preference does not relieve the client of choosing the document it means to send.

The request Content-Type makes that choice visible. A negotiation library should not take the first Accept-Patch entry and silently rewrite a queued change. Parameters can matter, ordering does not establish universal preference, and an application may have only one correctly constructed representation of its intended modification.

Discovery survives refusal

The error model shows why a supported format is not a success promise. RFC 5789 identifies several independent ways a PATCH can fail.

A malformed patch document can produce 400. A media type unsupported for the target can produce 415, and that response should include Accept-Patch to advertise supported alternatives. A syntactically valid document that cannot be processed can produce 422. A format incapable of applying to a nonexistent resource can lead to 404. The current resource state or concurrent modification can cause 409. A failed explicit precondition is best reported as 412.

The 415 case is especially instructive. The server has just rejected the submitted format and supplies an advertisement that may help the client prepare another request. The header does not retroactively accept the failed document. It does not say that replay under another Content-Type is safe, because changing only the label without reconstructing the document would be wrong. Nor does it say that a correctly encoded alternative will pass authorization or application validation.

An API client should preserve the rejection, present the supported formats and decide locally whether it can construct a semantically equivalent new request. That is a new operation, with new state and authorization checks. Discovery reduces guesswork; it does not create a retry mandate.

Preconditions protect state, not privilege

Some patch formats require a known base. If two clients build changes from the same version, an apparently valid sequence can corrupt the later state. RFC 5789 recommends conditional requests for such formats and gives a strong ETag in If-Match as the model.

RFC 9110 defines If-Match as a precondition evaluated before the method. Strong comparison lets the client say, in effect, apply this only if the selected representation is still one I observed. A failed condition produces 412 rather than asking the server to guess how to rebase the patch.

That protects state coherence, not access rights. A matching ETag is not a credential. An authorized account can still provide a stale validator; an unauthorized account can know the current validator. The server evaluates both policy and precondition, and the evaluation order must not be collapsed into a single “can patch” flag exposed by discovery.

PATCH itself is registered by IANA as neither safe nor idempotent. RFC 5789 notes that a particular request can be designed to be idempotent, but that property depends on the patch semantics and state. Retrying an append operation, for example, differs from repeating a replace guarded by a test. Accept-Patch says nothing about the idempotence of the document the client is about to send.

Atomicity is the execution boundary

Once a request has been admitted, RFC 5789 requires the entire set of changes to be applied atomically. A server must not expose a partially modified representation during execution, and if the whole patch cannot be applied, none of its changes may remain.

RFC 6902 illustrates the consequence with a failed test operation: the JSON Patch as a whole makes no change. That is an execution guarantee for the accepted operation, not evidence that all side effects outside the target are universally reversible. RFC 5789 permits application-defined effects on other resources and extends its atomicity requirement to directly affected files in its example.

This boundary should appear in system design. Validation can parse the chosen media type. Authorization can constrain paths and operations. Preconditions can test state. Execution can stage changes and commit them together. Each failure needs a result that does not leave half of the advertised instruction language applied.

The field itself belongs outside that transaction. Reading Accept-Patch does not begin an edit, reserve a version or lock a resource. Treating discovery as a lock would create a hidden coordination protocol that neither clients nor intermediaries could reliably observe.

Cache consequences come after the unsafe method

Because PATCH is unsafe, a non-error response has cache-coherence consequences. RFC 9111 requires a traversed cache to invalidate stored responses for the target URI. Same-origin Location and Content-Location values can also be candidates, while cross-origin invalidation is prohibited under that rule.

Those effects follow an actual unsafe request and its non-error response. An OPTIONS response carrying Accept-Patch does not mutate the resource and does not trigger the PATCH invalidation path. The difference prevents a discovery probe from becoming a purge command.

Even after successful mutation, invalidation is not global. It reaches caches through which the request passed. Applications requiring stronger consistency need explicit mechanisms. Accept-Patch neither widens the invalidation set nor certifies that every reader sees the new state.

A signed advertisement is still an advertisement

HTTP Message Signatures can cover selected components, including an Accept-Patch field, under an application-defined profile. Verification can protect the integrity and authenticity of those covered bytes. It cannot supply the missing access-control decision by itself.

RFC 9421 requires an application profile to specify required components, key resolution, algorithms and policy. An authorization protocol can bind a signature to credentials and target data, but that authority comes from the profile and its trust rules. Signing the list of patch formats establishes neither that the signer owns every affected resource nor that a later bearer may modify it.

This distinction is valuable across gateways. A gateway can preserve or attest the origin’s advertised capability. The downstream service still evaluates the principal, actual target, Content-Type, patch operations, validator and current policy. Cryptography preserves a statement; it does not broaden the statement’s semantics.

A durable client model

A client library should record at least five pieces of state separately:

  1. the resource URI and observation time;
  2. whether PATCH appeared in Allow or was implied by Accept-Patch;
  3. the exact advertised media types and parameters;
  4. the validator for the representation on which the intended patch was built;
  5. the credentials and policy context to be used for the new request.

The first three support discovery. The fourth supports concurrency control. The fifth is evaluated by the application’s security system. A user interface may combine them into a convenient workflow, but the stored model should not erase their provenance.

Servers benefit from the same separation. OPTIONS can expose stable protocol capability without leaking per-user policy. Request handling can then authenticate, authorize, validate Content-Type, parse the corresponding patch language, evaluate preconditions, check business constraints and commit atomically. A 415 response can advertise alternatives without promising that another request will pass the other stages.

Tests should exercise combinations rather than one happy path: PATCH in Allow without Accept-Patch; Accept-Patch on a GET response; anonymous and authorized principals seeing the same formats; stale If-Match; generic application/json rejected; JSON Patch and Merge Patch producing intentionally different effects; a failed JSON Patch test leaving no changes; and a signed advertisement followed by a forbidden write.

Sources