F12.9 — readMask partial responses
| State | Closed |
| Parent | E12 |
| Iteration | Release 3 |
| Start Date | 2026-10-04 |
| Closed Date | 2026-10-04 |
| Predecessors | F12.1 |
| Source | Owner request, 2026-10-04 |
Stories: 5 Closed
| Story | State | Depends on |
|---|---|---|
| S12.9.1 — Check for a maintained library | Closed (2026-10-04) | — |
S12.9.2 — The mask in rn-forge-web, and conformance cases |
Closed (2026-10-04) | — |
| S12.9.3 — Django binding | Closed (2026-10-04) | — |
| S12.9.4 — FastAPI binding | Closed (2026-10-04) | — |
| S12.9.5 — Documentation and release notes | Closed (2026-10-04) | — |
Google AIP-157 partial responses: a read accepts
readMask=displayName,address.city, and the response holds only those fields.
The API conventions list AIP-157 as "not adopted (deferred)"; this feature
adopts it for GET of one resource, GET of a collection, and :batchGet, on
both stacks. The mask is applied to the wire representation after serialization.
Every stack therefore validates and prunes identically, and the stacks'
serializers do not change.
Context
Outcome: the owner scheduled this feature for release 3 on 2026-10-04, ahead
of its original trigger; F12.1 is a predecessor because the mask also applies to
:batchGet's items.
Design
Outcome: readMask shipped on both stacks (2026-10-04). The
API conventions §20 own the
wire rules; the DRF views guide
and the
FastAPI wiring guide
show the bindings.
Shared pieces in rn-forge-web
Outcome: the
read-mask reference documents
rn_forge.web.read_mask.
New conformance cases
Outcome: the read-mask area's cases are in CASES, documented in the
conformance reference.
S12.9.1 — Check for a maintained library
State: Closed (2026-10-04)
Acceptance: drf-flex-fields (sparse fieldsets for DRF) is checked against
ADR-0001: release recency, typing, whether its
parameter can be named readMask, and whether it can reject an unknown path
with 400 instead of ignoring it. Pydantic's own model_dump(include=...) is
checked as the FastAPI-side engine. The outcome is recorded under Considered
and rejected, or the design is amended before S12.9.3 starts.
S12.9.2 — The mask in rn-forge-web, and conformance cases
State: Closed (2026-10-04)
Acceptance:
rn_forge.webexportsREAD_MASK_PARAM,FieldTree,ReadMask,parse_read_maskandInvalidReadMask, with the contracts in Shared pieces.tests/test_read_mask.pycovers every wire rule: dotted paths, whitespace,*, overlap, lists of objects, empty lists, a leaf reached through a list, and each 400.ConformanceAreagainsread-mask. The cases in New conformance cases are added toCASESin S12.9.4: every driver runs every case, so they land once both stacks and the ASGI example serve them.
S12.9.3 — Django binding
State: Closed (2026-10-04)
Acceptance:
rn_forge.django.drfexportsReadMaskMixin, andBaseModelViewSetincludes it.- The Django conformance fixture serves
/conformance/profilesfrom a viewset with a nested address serializer and a phones list serializer, and theread-maskcases pass on it once S12.9.4 adds them. tests/drf/covers a snake_case field reached by its camelCase path, a non-200 response left unmasked, and a write action ignoringreadMask.- The drf-spectacular schema documents
readMaskonretrieve,listandbatchGetonly.
S12.9.4 — FastAPI binding
State: Closed (2026-10-04)
Acceptance:
rn_forge.fastapiexportsread_mask_paramandmasked.batch_get_routerapplies the mask unlessread_mask=False.CASESgains theread-maskcases. The ASGI example (asgi_app.py), the Django and FastAPI conformance fixtures and the scaffold driver serve/conformance/profiles, and everyread-maskcase passes on each.- The FastAPI conformance fixture serves
/conformance/profilesthroughread_mask_param. tests/covers a field alias differing from its attribute name, andOptional[Model]andlist[Model]fields becoming subtrees.
S12.9.5 — Documentation and release notes
State: Closed (2026-10-04)
Acceptance:
- The API conventions gain a Partial responses section that states the wire rules and names each case id. §19 no longer lists AIP-157 as not adopted.
- The Django DRF views guide and the FastAPI wiring guide each show a masked read.
CHANGELOG.mdentries exist forrn-forge-web,rn-forge-djangoandrn-forge-fastapi.- The root and package sites build under
--strict, and the scaffold suite passes.
Acceptance
set -euo pipefail
absent() { local rc=0; rg -q --hidden --glob '!.git' "$@" </dev/null || rc=$?; [ "$rc" -eq 1 ]; }
for sym in READ_MASK_PARAM FieldTree ReadMask parse_read_mask InvalidReadMask; do
grep -q "\"$sym\"" packages/rn-forge-web/src/rn_forge/web/__init__.py # S12.9.2
done
grep -q '"read-mask"' packages/rn-forge-web/src/rn_forge/web/conformance/types.py # S12.9.2
(cd packages/rn-forge-web && uv run pytest -q tests/test_read_mask.py tests/test_conformance.py) # S12.9.2
grep -q 'class ReadMaskMixin' -r packages/rn-forge-django/src/rn_forge/django/drf # S12.9.3
(cd packages/rn-forge-django && uv run pytest -q tests/drf tests/test_conformance.py) # S12.9.3
grep -q 'def read_mask_param' -r packages/rn-forge-fastapi/src/rn_forge/fastapi # S12.9.4
(cd packages/rn-forge-fastapi && uv run pytest -q -m 'not scaffold') # S12.9.4
absent 'pytest.skip' packages/rn-forge-django/tests/test_conformance.py packages/rn-forge-fastapi/tests/test_conformance.py # S12.9.3, S12.9.4
uv run pyright # S12.9.2–S12.9.4
uv run lint-imports # S12.9.2–S12.9.4
absent 'AIP-157 `readMask`' packages/rn-forge-web/docs/guides/api-conventions.md # S12.9.5
for pkg in web django fastapi; do
grep -qi 'readMask' "packages/rn-forge-$pkg/CHANGELOG.md" # S12.9.5
(cd "packages/rn-forge-$pkg" && uv run --group docs mkdocs build --strict -q --site-dir "$(mktemp -d)") # S12.9.5
done
uv run pytest -q -m scaffold # S12.9.5
Considered and rejected
drf-flex-fields(checked 2026-10-04). The parameter can be renamed (REST_FLEX_FIELDS["FIELDS_PARAM"]) and dotted paths and*are supported, but it fails the other tests. Its latest release is 1.0.2 (March 2023), with noTyping :: Typedclassifier and no declaredrequires_python, so strict pyright sees untyped code. It silently ignores a name that matches no field, so an unknown path cannot return 400 without a second validation pass that duplicates the work. It reads the query only on the root serializer and prunes before serialization, which differs from the wire rules here and would leave the FastAPI side with a different implementation. It also adds a dependency. Adopting it would not delete any code.- Pydantic
model_dump(include=...). It prunes nested models and lists ({"phones": {"__all__": {"number": True}}}), but it takes attribute names, not aliases (include={"displayName"}returns{}for a field aliased fromdisplay_name), and it silently ignores unknown names. It would need the same alias translation and validation as a wire-level pruner, and it would give FastAPI different semantics from Django. A shared pruner over the wire representation gives both stacks one contract. - Query projection (
only(),load_only). It would cut database work as well as payload, but it ties the mask to each ORM's loader, and a serializer method field can depend on columns the mask does not name. Pruning the serialized representation is identical on every stack. Projection can be added later behind the same wire rules. - JSON:API sparse fieldsets (
fields[type]=...). The conventions follow AIPs for naming where no RFC applies (§19), and AIP-157 is the AIP for this. - Making response properties optional in OpenAPI. Every unmasked client would lose its required-field types to serve the masked case.
- Always including
id. AIP-157 returns exactly the mask. A client that needs the id asks for it. - Ignoring unknown paths. A typo would silently return an empty object,
which is the failure §4 already rules out for
orderBy.