Deprecation and Forwarding Notice¶

Lifecycle protocol — instantiates Source-of-Truth Assignment

Marks an obsolete representation as no longer authoritative and attaches a forwarding pointer to the current source, so anyone still holding the old copy is redirected rather than misled.

Deprecation and Forwarding Notice handles the retirement end of the archetype. It neither picks nor builds the truth; it manages what happens to a representation once it has stopped being authoritative — flagging it as superseded and attaching a pointer to the current source so that whoever still reaches for the old copy is steered to the live one. Its distinguishing idea is the active forward: a bare "this is out of date" leaves users stranded, so the mechanism pairs the deprecation status with a redirect and a sunset timeline, closing the loop that otherwise lets retired copies keep quietly governing.

Example¶

A company retires the v1 of its customer API in favor of v2. Deleting v1 outright would break every integrator still calling it; leaving it running would let it keep serving stale data indefinitely. Instead they apply a deprecation and forwarding notice: v1 responses carry a Deprecation and Sunset HTTP header announcing the retirement date, each response links to the v2 equivalent, and the docs banner points forward. Callers get an active, dated warning and a clear target, not silence. After the sunset date, v1 returns a redirect to v2. Integrators are steered off the dead endpoint on a known schedule instead of unknowingly depending on it — the retired representation is demoted and everyone is pointed to what replaced it.

How it works¶

The protocol runs a small lifecycle: (1) mark the representation non-authoritative — a visible "deprecated / superseded" status; (2) attach a forwarding pointer mapping the retired thing to its current successor, so the old reference resolves forward instead of dead-ending; (3) announce a sunset timeline; (4) eventually retire or redirect. The forwarding pointer is the distinctive part — it is an alias from the retired representation to the live source, which is what turns a demotion into a redirection rather than a broken link.

Tuning parameters¶

Sunset horizon — how long the deprecated representation lingers before retirement. Long horizons ease migration; short ones cut the window in which a stale copy can mislead.
Enforcement gradient — soft (a banner or warning header) versus hard (a forced redirect or removal). How firmly users are pushed off the old copy.
Forwarding precision — redirect to the exact successor versus a general "this has moved" page. Precise forwarding is more useful but must be maintained as targets change.
Announcement reach — passive tombstones and headers versus active notification of known consumers. Active reach catches dependents who never read the banner.

When it helps, and when it misleads¶

Its strength is closing the loop most source-of-truth work forgets: it stops a retired representation from continuing to govern, and does so without stranding the people who relied on it. Its failure modes are the two halves left undone — deprecating without a live forwarding target (a dead end that just breaks things) or without enforcement (a notice everyone ignores while they keep using v1 forever).^[1] The classic misuse is marking something "deprecated" to discourage use while it is still authoritative — a soft kill that confuses readers about what actually governs. The discipline that guards against this is that every deprecation carries a live successor to forward to and a real sunset date, never one without the other.

How it implements the components¶

deprecation_path — the retirement lifecycle and status: marking a representation superseded and moving it toward sunset on a schedule.
alias_mapping — the forwarding pointer from the retired representation to its current successor, so old references resolve forward.

It does not choose which successor is authoritative (that is System-of-Record Designation), maintain the canonical list of live identifiers and their name variants (that is Canonical Registry), or keep the current authoritative content itself (that is Authoritative Policy Repository).

Instantiates: Source-of-Truth Assignment — it governs the retirement of representations so superseded copies stop competing for authority.
Sibling mechanisms: Canonical Registry · Authoritative Policy Repository · System-of-Record Designation · Official Record Policy · Synchronization Job · Conflict Resolution Workflow · Change Log and Audit Trail · Master Data Management · Golden Record Consolidation · Access and Update Rights Matrix · Source-Control Main Branch

Notes¶

Its alias_mapping differs in direction and intent from Canonical Registry's: the registry maps variant names of a live entity to one canonical entry, while this notice maps a retired representation forward to its successor. One is about naming a current thing; the other is about redirecting off a dead one.

References¶

[1] The HTTP Deprecation and Sunset headers (the latter standardized in RFC 8594) and HTTP 301 Moved Permanently redirects are the canonical web-facing form of this protocol: they announce that a resource is obsolete, when it retires, and where its successor lives. The pattern generalizes to any retired document, endpoint, or dataset. ↩