What should an API do when a research observation is withdrawn?

Why is a missing row not proof of withdrawal?

A record disappearing from a response has several possible explanations: a changed filter, incomplete pagination, a permission change, a source correction or an actual withdrawal. Treating every disappearance as deletion makes transport failures destructive. A reliable contract needs an explicit withdrawal event or a documented complete-snapshot rule before absence changes the accepted state of an observation.

Distinguish the observation key from its versions and from the event announcing invalidation. An economic period can remain a legitimate identity even when its published value is rejected. Keep a state such as withdrawn separate from a numeric null. Null can mean an unavailable measurement; withdrawal asserts that a previously usable version must no longer support the relevant view.

Specify the event before designing the display

A proposed teaching event can carry observation_key, affected_version, action, source_effective_at, received_at, reason_code and replacement_version. These are illustrative application fields, not a universal provider schema. The affected version must be unambiguous. Otherwise, a late withdrawal intended for an old version could accidentally remove a corrected replacement that arrived through another delivery path.

W3C PROV-O supplies a vocabulary for invalidation; RFC 6902 distinguishes removing a JSON member from replacing its value. Neither specifies the economic meaning of a dataset withdrawal. Declare that meaning locally, including whether the event invalidates one value, a complete period, or every version of an identity. Do not imply formal conformance merely by borrowing terminology.

Reconcile a synthetic three-observation example

Consider invented observations A=10, B=20 and C=30 in one accepted generation. Their mean is 20. A later explicit event withdraws B without replacement. The current eligible set becomes A and C: two observations, sum 40 and mean 20. The unchanged mean is precisely why a headline statistic cannot substitute for checking membership and withdrawal counts.

If an application instead turns withdrawn B into zero, its three-row mean becomes 13.333333. If it forward-fills B from its old value, it still reports three usable observations despite the source rejection. Both choices change the research evidence. Preserve the previous generation separately, label the revised denominator, and disclose that this example is synthetic rather than a real release.

Separate what was known from what is now accepted

A historical information-set query asks which source events were available by a stated cutoff. A corrected-current query asks which retained values remain accepted after subsequent invalidations. These are different products. An investigator may need both to explain an old decision and repair a current chart. Name the requested view instead of allowing the latest-state table to answer both questions.

A withdrawal received after an old cutoff must not be smuggled into the historical knowledge claim. Conversely, reproducing an old information set does not authorize presenting its rejected value as current. Preserve source time precision and receipt time independently. If only a date is documented, no ordering rule should manufacture an exact intraday withdrawal timestamp.

Trace dependent outputs without erasing their history

Record which datasets, joins, charts and exports consumed the affected version. A dependency locator should lead to an artifact generation and transformation version, not merely a mutable dashboard address. Then classify whether each dependent result needs withholding, recalculation or a correction note. A result can be numerically unchanged while its supporting evidence has materially changed.

Test a replacement arriving before its withdrawal notice, duplicate events, an unknown affected version and an attempted resurrection through an old snapshot. Keep unresolved ordering conflicts visible. Retention must follow actual permissions: an immutable public copy is not automatically lawful if the underlying content must be removed. Protected evidence and public corrections may require different storage and disclosure decisions.

Which questions belong in acceptance review?

Ask who can issue a withdrawal, how completeness is established, what identifies the affected version, and which views must change. Also ask what happens when the reason is unavailable or a replacement never arrives. These questions determine whether downstream users can distinguish a rejected observation from an ordinary missing measurement without reading operational logs or guessing from a chart.

Acceptance should demonstrate that replay does not restore invalidated current values, that historical cutoffs remain reproducible, and that denominator changes reach exported results. Fail the proposed contract if it hides withdrawal as zero, deletes unrelated versions, or claims stronger timing than its evidence provides. This is an interface-design exercise, not a claim that the publication implements a live correction service.

Keep in the decision record

• Absence requires a completeness contract before it becomes deletion evidence.
• Historical knowledge and corrected-current views need different selection rules.
• Inspect dependent membership even when a headline statistic does not change.

Source notes

1. W3C PROV-O Recommendation - invalidation and invalidatedAtTime; public full text reviewed 16 October 2026
2. RFC 6902 - JSON Patch remove, replace and test operations; public full text reviewed

Primary specifications support the interface descriptions. All downloadable response fixtures are synthetic. Access and rights checks are dated in the source inventory.

Continue the analysis