Skip to content

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.web exports READ_MASK_PARAM, FieldTree, ReadMask, parse_read_mask and InvalidReadMask, with the contracts in Shared pieces.
  • tests/test_read_mask.py covers every wire rule: dotted paths, whitespace, *, overlap, lists of objects, empty lists, a leaf reached through a list, and each 400.
  • ConformanceArea gains read-mask. The cases in New conformance cases are added to CASES in 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.drf exports ReadMaskMixin, and BaseModelViewSet includes it.
  • The Django conformance fixture serves /conformance/profiles from a viewset with a nested address serializer and a phones list serializer, and the read-mask cases 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 ignoring readMask.
  • The drf-spectacular schema documents readMask on retrieve, list and batchGet only.

S12.9.4 — FastAPI binding

State: Closed (2026-10-04)

Acceptance:

  • rn_forge.fastapi exports read_mask_param and masked. batch_get_router applies the mask unless read_mask=False.
  • CASES gains the read-mask cases. The ASGI example (asgi_app.py), the Django and FastAPI conformance fixtures and the scaffold driver serve /conformance/profiles, and every read-mask case passes on each.
  • The FastAPI conformance fixture serves /conformance/profiles through read_mask_param.
  • tests/ covers a field alias differing from its attribute name, and Optional[Model] and list[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.md entries exist for rn-forge-web, rn-forge-django and rn-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 no Typing :: Typed classifier and no declared requires_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 from display_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.