Skip to content

F12.2 — Soft delete

State Closed
Parent E12
Iteration Release 3
Start Date 2026-10-04
Closed Date 2026-10-04
Predecessors F12.15
Source Owner request, 2026-10-04

Stories: 7 Closed

Story State Depends on
S12.2.1 — Decision: soft delete is a delete_time column in AIP-164's shape Closed (2026-10-04) —
S12.2.2 — Check for maintained libraries Closed (2026-10-04) —
S12.2.3 — Shared rules and the conformance area Closed (2026-10-04) —
S12.2.4 — ORM support Closed (2026-10-04) —
S12.2.5 — Django binding Closed (2026-10-04) —
S12.2.6 — FastAPI binding Closed (2026-10-04) —
S12.2.7 — Documentation and release notes Closed (2026-10-04) —

Soft delete in Google AIP-164's shape, on both stacks and both ORM packages. A DELETE on a resource that offers soft delete sets its deleteTime instead of removing it. POST {resource}:undelete reverses it, and showDeleted=true brings deleted resources back into a list. The API conventions list AIP-164 as "not adopted (deferred)"; this feature adopts it.

Context

Outcome: the owner scheduled this feature for release 3 on 2026-10-04, ahead of its original trigger. Taken up before the model-vocabulary idea, it settled that idea's status-based soft-delete question.

Design

Outcome: soft delete shipped on both stacks and both ORM packages (2026-10-04), with hard delete and purge out of scope. The API conventions §21 own the wire rules and case ids; the Django models guide, the rn-forge-sqlalchemy guide and the FastAPI soft-delete guide show the bindings, and the soft-delete reference lists the shared symbols.

Why a delete_time column, not a status

Outcome: ADR-0010 records the decision and its reasons.

New conformance cases

Outcome: the soft-delete area's cases are in CASES, documented in the conformance reference.

S12.2.1 — Decision: soft delete is a delete_time column in AIP-164's shape

State: Closed (2026-10-04)

Acceptance:

  • docs/adr/ADR-0010.md records the decision in Why a delete_time column, with status-based soft delete under Alternatives considered. It is listed in docs/adr/index.md.
  • The model-vocabulary idea's Soft delete section is rewritten to point at ADR-0010, and its summary row no longer lists status-based soft delete. The sentence about the conflict with F12.2 is gone.
  • The owner accepts the ADR.

S12.2.2 — Check for maintained libraries

State: Closed (2026-10-04)

Acceptance: django-safedelete and sqlalchemy-easy-softdelete are each checked against ADR-0001: release recency, typing, support for the current Django or SQLAlchemy major, and whether they can give the wire rules above without global query hooks. The outcome is recorded under Considered and rejected, or the library is adopted behind the package's extras and the design is amended before S12.2.4 starts.

S12.2.3 — Shared rules and the conformance area

State: Closed (2026-10-04)

Acceptance:

  • rn_forge.web exports ResourceDeleted, ResourceNotDeleted, SHOW_DELETED_PARAM and require_live. Both exceptions are registered in default_registry() through DomainConflict, and tests/ covers their rendered bodies.
  • ConformanceArea gains soft-delete. The cases in New conformance cases are added to CASES in S12.2.6: every driver runs every case, so they land once both stacks serve them.

S12.2.4 — ORM support

State: Closed (2026-10-04)

Acceptance:

  • rn_forge.django.models exports SoftDeleteModelMixin and SoftDeleteQuerySet. Tests cover soft_delete and undelete setting delete_time and updated_by, a version bump on a versioned model, .live() and .deleted(), and an unfiltered default manager.
  • rn_forge.sqlalchemy exports SoftDeleteMixin, live, soft_delete and undelete. Tests cover the same behavior on SQLite, and on PostgreSQL under the postgres marker.

S12.2.5 — Django binding

State: Closed (2026-10-04)

Acceptance:

  • rn_forge.django.drf.views exports SoftDeleteMixin, and BatchDeleteMixin deletes through perform_destroy.
  • The Django conformance fixture serves /conformance/notes from a SoftDeleteMixin viewset, and the soft-delete cases pass on it once S12.2.6 adds them. The existing transfer.batch-delete-* cases still pass.
  • tests/drf/ covers soft_delete_requires_if_match (428), a PUT on a deleted resource (409), and showDeleted values other than true and 1 excluding deleted rows.
  • The drf-spectacular schema names the undelete operation notesUndelete, documents showDeleted on the list, and documents DELETE as 200 with the resource.

S12.2.6 — FastAPI binding

State: Closed (2026-10-04)

Acceptance:

  • rn_forge.fastapi exports SoftDeleteStore, soft_delete_router and show_deleted_param.
  • CASES gains the soft-delete cases. The ASGI example (asgi_app.py), the Django conformance fixture from S12.2.5, the FastAPI conformance fixture and the scaffold drivers serve /conformance/notes, and every soft-delete case passes on each. The FastAPI fixture serves it through these symbols over an in-memory store. The rn-forge-sqlalchemy conformance driver serves the same routes over SQLite with SoftDeleteMixin, and passes them too.
  • tests/ covers require_if_match=True (428), a dependencies= guard, and the store never being asked to write after a failed precondition.
  • The OpenAPI document has notesUndelete and a 200 DELETE response, and both list their problem responses.

S12.2.7 — Documentation and release notes

State: Closed (2026-10-04)

Acceptance:

  • The API conventions gain a Soft delete section that states the wire rules and names each case id. §10 notes that a soft-deleting resource's DELETE is 200. §18 lists deleteTime among the standard fields. §19 no longer lists AIP-164 as not adopted.
  • The model conventions guide, the Django models guide and the rn-forge-sqlalchemy guide describe the mixins. The FastAPI guide shows a SQLAlchemy SoftDeleteStore built on live and soft_delete.
  • CHANGELOG.md entries exist for rn-forge-web, rn-forge-django, rn-forge-fastapi and rn-forge-sqlalchemy.
  • 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 ]; }

test -f docs/adr/ADR-0010.md && grep -q 'ADR-0010' docs/adr/index.md                    # S12.2.1
absent 'conflicts with this section' docs/specs/ideas/index.md                               # S12.2.1
for sym in ResourceDeleted ResourceNotDeleted SHOW_DELETED_PARAM require_live; do
  grep -q "\"$sym\"" packages/rn-forge-web/src/rn_forge/web/__init__.py                    # S12.2.3
done
grep -q '"soft-delete"' packages/rn-forge-web/src/rn_forge/web/conformance/types.py      # S12.2.3
(cd packages/rn-forge-web && uv run pytest -q)                                           # S12.2.3
grep -q 'class SoftDeleteModelMixin' -r packages/rn-forge-django/src/rn_forge/django/models   # S12.2.4
grep -q 'class SoftDeleteMixin' packages/rn-forge-sqlalchemy/src/rn_forge/sqlalchemy/models.py   # S12.2.4
(cd packages/rn-forge-sqlalchemy && uv run pytest -q)                                    # S12.2.4, S12.2.6
grep -q 'class SoftDeleteMixin' -r packages/rn-forge-django/src/rn_forge/django/drf/views   # S12.2.5
grep -q 'perform_destroy' packages/rn-forge-django/src/rn_forge/django/drf/transfer.py    # S12.2.5
(cd packages/rn-forge-django && uv run pytest -q tests/drf tests/models tests/test_conformance.py)   # S12.2.4, S12.2.5
grep -q 'def soft_delete_router' -r packages/rn-forge-fastapi/src/rn_forge/fastapi        # S12.2.6
(cd packages/rn-forge-fastapi && uv run pytest -q -m 'not scaffold')                    # S12.2.6
absent 'pytest.skip' packages/rn-forge-django/tests/test_conformance.py packages/rn-forge-fastapi/tests/test_conformance.py   # S12.2.5, S12.2.6
uv run pyright                                                                           # S12.2.3–S12.2.6
uv run lint-imports                                                                      # S12.2.3–S12.2.6
absent 'AIP-164 soft delete \(deferred\)' packages/rn-forge-web/docs/guides/api-conventions.md   # S12.2.7
for pkg in web django fastapi sqlalchemy; do
  grep -qi 'soft delete\|soft-delete' "packages/rn-forge-$pkg/CHANGELOG.md"                # S12.2.7
  (cd "packages/rn-forge-$pkg" && uv run --group docs mkdocs build --strict -q --site-dir "$(mktemp -d)")   # S12.2.7
done
uv run pytest -q -m scaffold                                                             # S12.2.7

Not scripted: the owner's acceptance of ADR-0010 (S12.2.1).

Considered and rejected

  • Status-based soft delete (status = DELETED), from the model-vocabulary idea. It cannot produce AIP-164's deleteTime once the resource is written again, and :undelete is such a write. It also mixes lifecycle state with retention.
  • A default manager or global session hook that hides deleted rows. A get must return a deleted resource (AIP-164), and a hidden row breaks related-object lookups and the Django admin in ways that are hard to see. Visibility is decided in the view or the query, where the action is known.
  • DELETE answering 204, as §10 does for a hard delete. AIP-164 returns the resource, and the client needs the new deleteTime and ETag. Answering 204 would cost every client a second request.
  • :batchDelete returning the soft-deleted resources, as AIP-235 allows. It would give the method two response shapes depending on the resource. It stays 204, and a client that needs the result lists with showDeleted=true.
  • A purge route or expireTime. Purging is a retention decision with its own authorization. Nothing in the kit schedules it, so the kit does not advertise an expiry.
  • django-safedelete 1.5.0 (checked 2026-10-04). It is maintained: 1.5.0 was released 2026-08-17 and its tox matrix covers Django 4.2 to 6.1. It ships no py.typed marker and its classifiers stop at Python 3.8, so strict pyright sees untyped code. It hides deleted rows through its default manager (DELETED_INVISIBLE), which ADR-0010 rejects. Its save() undeletes a soft-deleted row unless keep_deleted=True, so an ordinary PUT would undelete, where the wire rules answer 409. It adds cascade policies and deleted_by_cascade that the design does not use. soft_delete and undelete as a few lines on a nullable field are cheaper than overriding that much of the library.
  • sqlalchemy-easy-softdelete 0.9.1 (checked 2026-10-04). It is maintained (released 2026-06-16), typed (Typing :: Typed, py.typed), and supports Python 3.10 to 3.14. It installs a hook that rewrites every select on tables carrying its mixin, which ADR-0010 rejects, and GET of a deleted resource would need include_deleted on each query. Its SQLAlchemy range is >=1.4,<2.1, narrower than the package's sqlalchemy>=2.0. It provides no version bump and no updated_by, so the wire rules would still need our own helpers.