ADR-0010: Soft delete is a nullable delete_time column, in AIP-164's shape
Status: accepted (2026-10-04) · Scope: soft delete in both ORM packages and both HTTP stacks
Decision
A resource that offers soft delete carries a nullable delete_time timestamp,
NULL while the resource is live. It is the only soft-delete state: there is no
deleted flag and no status value for it. The column is independent of
status.
On the wire the timestamp is the read-only deleteTime of
AIP-164, and DELETE, :undelete and
showDeleted follow that AIP. Visibility is decided by the view or the query,
where the action is known. No default manager or session hook hides deleted
rows.
Consequences
deleteTime is a stored fact, so it survives later writes, including the write
that undeletes. A nullable timestamp serves the common filter,
delete_time IS NULL, with an ordinary index. It matches the column that
django-safedelete (deleted) and sqlalchemy-easy-softdelete (deleted_at)
use.
Every query that should hide deleted rows must say so, through .live() on
Django or live() on SQLAlchemy. A query that forgets returns deleted rows.
Django's existing Status.Deleted value does not mean soft-deleted, and whether
to remove it stays with the model-vocabulary idea.
Influences
This decision shapes F12.2, which holds the wire rules and the per-package design. It replaces the status-based soft delete proposed in the model-vocabulary idea.
Alternatives considered
- Status-based soft delete (
status = DELETED, no timestamp column).deleteTimecannot come from a status. Deriving it fromupdate_timebreaks on the first write after the delete, and:undeleteis such a write. It also mixes lifecycle state with retention. - A boolean
is_deletedflag. It records neither when nor by whom, and gives AIP-164 nodeleteTime. - A default manager or global session hook that hides deleted rows. AIP-164 says a get returns the deleted resource. A hidden row also breaks related-object lookups and the Django admin in ways that are hard to see.
Background
Decided by the owner's request on 2026-10-04, when F12.2 was scheduled ahead of the model-vocabulary idea. The idea had said that whichever was taken up first would settle the other.