F12.14 — JSON Merge Patch
| State | Closed |
| Parent | E12 |
| Iteration | Release 3 |
| Start Date | 2026-10-04 |
| Closed Date | 2026-10-04 |
| Predecessors | — |
| Source | Owner request, 2026-09-28 |
Stories: 6 Closed
| Story | State | Depends on |
|---|---|---|
| S12.14.1 — Check for a maintained library | Closed (2026-10-04) | — |
S12.14.2 — The framework-neutral merge in rn-forge-web |
Closed (2026-10-04) | — |
| S12.14.3 — Conformance cases | Closed (2026-10-04) | — |
| S12.14.4 — Django binding | Closed (2026-10-04) | — |
| S12.14.5 — FastAPI binding | Closed (2026-10-04) | — |
| S12.14.6 — Documentation and release notes | Closed (2026-10-04) | — |
The API conventions already
say PATCH is RFC 7396 JSON Merge Patch, but no package implements it.
rn-forge-django's only JSON parser accepts application/json, so DRF answers
a merge-patch request with 415, and DRF's partial update does not treat null
as "remove this field": it validates the null against the serializer field.
rn-forge-fastapi has no PATCH helper at all, and a
pydantic.ValidationError raised inside a route is not mapped to a 422: it
reaches the catch-all handler as a 500. Every application therefore writes its
own merge, and each gets null, nested objects or arrays slightly differently.
RFC 7396 in one paragraph: the body is a partial copy of the resource. A member
that is present sets the field, an absent member leaves it alone, a null
member removes it, objects merge recursively and arrays are replaced whole.
Context
Outcome: a browser client's resource screen fired the trigger; the client's
work did not gate this feature (ADR-0008). It
changed BaseModelViewSet's PATCH media type, a breaking change.
Design
Outcome: one framework-neutral merge in rn_forge.web.merge_patch
(ADR-0005), which each adapter only binds, shipped
on 2026-10-04; the
API conventions §10 Merge
patch own the wire rules, and the
merge-patch reference lists
the shared symbols. The merge is hand-rolled under ADR-0001 rule 1's third
condition: the S12.14.1 search found only json-merge-patch 0.3.0, untyped,
in-place and not clearly maintained, and no other RFC 7396 implementation.
Request order
Outcome: the API conventions' Merge patch section states the order: media type, precondition, body shape, then validation.
null on a declared field
Outcome: the API conventions state the top-level null rule. It exists
because DRF's full update skips a missing optional field instead of clearing it,
so a null that only removed the member would leave the stored value unchanged.
The conformance fixture
Outcome: each driver serves /conformance/documents/1; the patch area's
cases are in CASES, documented in the
conformance reference. All
three packages took a minor version with no deprecation window, rn-forge-web
tagged first, and F12.12's removals
shipped in the same rn-forge-django version.
S12.14.1 — Check for a maintained library
State: Closed (2026-10-04)
Acceptance: PyPI is searched for a maintained RFC 7396 implementation, per
ADR-0001 rule 1, and the result is recorded under
Design: either the package is adopted, with the owner's approval of the new
dependency, or the reason to hand-roll is named. If one is adopted, S12.14.2's
apply_merge_patch wraps it and the module docstring says so.
S12.14.2 — The framework-neutral merge in rn-forge-web
State: Closed (2026-10-04)
Acceptance:
- A new module
rn_forge.web.merge_patchdefines, andrn_forge.webre-exports:MERGE_PATCH_MEDIA_TYPE = "application/merge-patch+json";apply_merge_patch(target, patch), which follows RFC 7396 §2 exactly and mutates neither argument;merge_representation(current, patch), which applies the top-levelnullrule and thenapply_merge_patchbelow the top level;require_patch_object(body), which returns body when it is a JSON object and raisesInvalidMergePatchotherwise.
rn_forge.web.problemgainsUNSUPPORTED_MEDIA_TYPE = ProblemType("unsupported-media-type", 415, "Unsupported Media Type")andNULL_FIELD_DETAIL = "This field may not be null."(DRF's own wording, so both stacks already agree on it). Both are re-exported besideCONTENT_TOO_LARGEandREQUIRED_FIELD_DETAIL.rn_forge.web.exceptionsgains twoWebErrorsubclasses, both registered indefault_registry():UnsupportedMediaTypemaps to 415. LikeTooManyRequests, it carries aresponse_headers()result, hereAccept-Patch: application/merge-patch+json(RFC 5789 §2.2). Its detail isUse Content-Type: application/merge-patch+json for PATCH.InvalidMergePatchmaps to 422 with detailA merge patch must be a JSON object., and has noerrorsmember.
tests/test_merge_patch.pyruns every example in RFC 7396 Appendix A throughapply_merge_patch. It also covers: nested merge;nullremoving a member that is absent (a no-op); array replacement; a scalar or list patch replacing the target (RFC §2); no mutation of either argument;merge_representationkeeping a top-levelnulland still removing a nested one; andrequire_patch_objectrejecting a list, a string andnull.- The module imports no web framework, and
uv run pyrightanduv run lint-importspass.
S12.14.3 — Conformance cases
State: Closed (2026-10-04)
Acceptance: ConformanceArea gains "patch", and
rn_forge.web.conformance.CASES gains the cases in
The conformance fixture, with ids beginning
patch.. Both framework drivers serve /conformance/documents/1 and run every
case with no skips. Each driver's issue() sends the case's own Content-Type
for a JSON body, rather than forcing application/json.
S12.14.4 — Django binding
State: Closed (2026-10-04)
Acceptance:
rn_forge.django.drf.casinggainsMergePatchParser, aCamelCaseJSONParsersubclass whosemedia_typeisMERGE_PATCH_MEDIA_TYPE.rn_forge.django.drfgainsMergePatchMixin(inviews/mixins.py), and both are re-exported fromrn_forge.django.drf.MergePatchMixin.get_parsers()returns[MergePatchParser()]forPATCHonly. ForPUTandPOSTit keeps the view's other parsers and never includes the merge-patch parser.MergePatchMixin.partial_updateruns in this order:- It checks the media type before reading
request.data. AnyPATCHwhose media type, ignoring parameters, is notMERGE_PATCH_MEDIA_TYPEraisesrn_forge.web.UnsupportedMediaType. - It calls
get_object(). - When the instance is a
VersionedModelMixin, it callsenforce_version(request, instance, required=self.merge_patch_requires_if_match, codec=self.etag_codec). Both class attributes default toFalseandNone. - It calls
require_patch_object(request.data). - It calls
merge_representation(serializer.data, patch), whereserializer.datais the current instance serialized. - It validates the merged document with
get_serializer(instance, data=merged), a full update rather thanpartial=True, and saves it throughperform_update. - It answers 200 with the new representation, plus
ETagfrometag_forwhen the instance is versioned.
- It checks the media type before reading
MergePatchMixin.retrieveadds the sameETagheader for a versioned instance. That makes the read-then-If-Matchround trip work without view code.BaseModelViewSetincludesMergePatchMixin.- The generated OpenAPI document lists
application/merge-patch+json, and only that, as thePATCHrequest body's content type for aBaseModelViewSet. tests/drf/test_merge_patch.pycovers: each step's failure (415, 428 when required, 412, a non-object 422, a null on a non-nullable field 422);PUTrefusing the merge-patch media type; theETagonretrieveandPATCH; the audit fields still set byperform_update; and the OpenAPI content type.tests/test_conformance.pypasses with the new cases.
S12.14.5 — FastAPI binding
State: Closed (2026-10-04)
Acceptance:
- A new module
rn_forge.fastapi.merge_patchholds three functions, all re-exported fromrn_forge.fastapi:merge_patch_body()returns a dependency. The dependency raisesUnsupportedMediaTypeunless the request's media type, ignoring parameters, isMERGE_PATCH_MEDIA_TYPE, and returns the raw body bytes unparsed.merge_into(model, current, body)parses body as JSON and passes it throughrequire_patch_object, so unparseable JSON and a non-object both raiseInvalidMergePatch. It then dumps current through model (model_validate(current, from_attributes=True).model_dump(by_alias=True, mode="json")), appliesmerge_representation, and validates the result with model. On apydantic.ValidationErrorit raisesfastapi.exceptions.RequestValidationErrorwith eachlocprefixed by"body", so the existing handler renders a 422 with RFC 6901 pointers. It never lets aValidationErrorreach the catch-all handler.merge_patch_openapi()returns theopenapi_extramapping that declares the request body asapplication/merge-patch+jsonwith schema{"type": "object"}.
rn_forge.fastapi.problem._validation_errorsmaps an entry whoseinputisNoneand whosetypeis notmissingtoNULL_FIELD_DETAIL, as it already mapsmissingtoREQUIRED_FIELD_DETAIL.- The route order is the same as Django's and follows
the request order:
merge_patch_bodyis declared beforerequire_if_match, so the media type answers first; the route checks the stale version withcheck_precondition; and only then doesmerge_intoparse the body, check it is an object, merge and validate. FastAPI resolves dependencies in declaration order, so the object check cannot live in the dependency without answering before the precondition. The tests pin 415 before 428, 400 before a non-object 422, and 412 before a non-object 422. tests/test_merge_patch.pycovers each function and the ordering, andtests/test_conformance.pypasses with the new cases.
S12.14.6 — Documentation and release notes
State: Closed (2026-10-04)
Acceptance:
- The API conventions' §10 describes the semantics in Design: the request
order, the top-level
nullrule, ignored read-only members, 415 withAccept-Patch, and the conformance case ids. A newrn-forge-webreference page documentsrn_forge.web.merge_patch. Each adapter's wiring guide shows its binding, and each adapter's reference pages list the new symbols. - Each affected package's
CHANGELOG.mdhas an entry.rn-forge-django's entry is marked breaking:BaseModelViewSetanswers anapplication/jsonPATCHwith 415. - The root and package sites build under
--strict. - The scaffold tests
(F9.8) serve each
package's conformance fixture from built wheels. Each scaffold driver
creates and resets
/conformance/documents/1the way itstest_conformance.pydoes, and the scaffold suite (uv run pytest -m scaffold) passes.
Acceptance
set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
grep -q 'merge_patch' packages/rn-forge-web/src/rn_forge/web/__init__.py # S12.14.2
absent 'django|fastapi|starlette' packages/rn-forge-web/src/rn_forge/web/merge_patch.py # S12.14.2
(cd packages/rn-forge-web && uv run pytest -q tests/test_merge_patch.py tests/test_conformance.py) # S12.14.2, S12.14.3
grep -q '"patch"' packages/rn-forge-web/src/rn_forge/web/conformance/types.py # S12.14.3
grep -q 'id="patch\.' packages/rn-forge-web/src/rn_forge/web/conformance/cases.py # S12.14.3
absent 'pytest.skip' packages/rn-forge-django/tests/test_conformance.py packages/rn-forge-fastapi/tests/test_conformance.py # S12.14.3
(cd packages/rn-forge-django && uv run pytest -q tests/drf/test_merge_patch.py tests/test_conformance.py) # S12.14.4, S12.14.6
(cd packages/rn-forge-fastapi && uv run pytest -q tests/test_merge_patch.py tests/test_conformance.py) # S12.14.5, S12.14.6
uv run pyright # S12.14.2, S12.14.4, S12.14.5
uv run lint-imports # S12.14.2, S12.14.4, S12.14.5
for pkg in web django fastapi; do
grep -qi 'merge' "packages/rn-forge-$pkg/CHANGELOG.md" # S12.14.6
(cd "packages/rn-forge-$pkg" && uv run --group docs mkdocs build --strict -q --site-dir "$(mktemp -d)") # S12.14.6
done
grep -qi 'breaking' packages/rn-forge-django/CHANGELOG.md # S12.14.6
uv run pytest -q -m scaffold # S12.14.6
S12.14.1's search result and any dependency approval are read from Design.
Considered and rejected
- Rejecting read-only members with a 422. This is the strictest option, but it breaks a client that sends back a representation it read. It also differs from DRF's and pydantic's defaults, so each adapter would need its own detection.
nullon a field resets it to the column default. Hard to predict, because the default can live on the model, the serializer or the database. It also differs between the two stacks.nullremoves the member, as RFC 7396 says for documents. On a fixed-schema resource, DRF's full update then skips the field, so the stored value silently stays.- Accepting
application/jsononPATCHas a merge patch. The media type is how a client says which semantics it wants. RFC 5789 §2.2 has the server refuse a patch format it does not support, and name the ones it does inAccept-Patch. - JSON Patch (RFC 6902). The API conventions chose merge patch. JSON Patch's operation list is harder for a form-based client to produce and gives no benefit for flat resources.