# Deprecating a Spatial Data Product Safely

Most deprecations overrun because nobody knew who the consumers were. An announcement goes out, a sunset date is set, and on the date half the callers are still calling — because the consumer list came from a wiki rather than from telemetry, and the window came from a template rather than from the slowest affected release cycle. This guide runs a deprecation that lands: identify callers from access records, derive the window from their cadence, enforce in graduated stages, and retire only when the caller set is empty. It implements the deprecation discipline in Spatial Product Lifecycle Management within Geospatial Data Mesh Fundamentals, and it is the transition automated in Automating Lifecycle State Transitions.

# Prerequisites

# Step-by-Step Implementation

# 1. Identify the callers from telemetry

# Every identity that called this version in 90 days, with volume and last-seen.
curl -sS "$PROM/api/v1/query" --data-urlencode \
  'query=sum by (caller) (increase(product_requests_total{product="'"$PRODUCT"'",version="'"$VERSION"'"}[90d]))' \
  | jq -r '.data.result[] | "\(.metric.caller)\t\(.value[1]|tonumber|floor)"' \
  | sort -k2 -rn | tee /tmp/callers.tsv

Verify the window is long enough by comparing caller counts at three windows — a set that keeps growing means slower consumers exist:

for d in 30 90 180; do
  printf '%3dd: ' "$d"
  curl -sS "$PROM/api/v1/query" --data-urlencode \
    "query=count(count by (caller) (increase(product_requests_total{product=\"$PRODUCT\",version=\"$VERSION\"}[${d}d])))" \
    | jq -r '.data.result[0].value[1]'
done

# 2. Derive the window from the slowest affected consumer

# window.py — a sunset date the affected teams can actually meet.
CADENCE_DAYS = {          # published by each consuming team, not guessed
    "logistics/router": 7,
    "planning/reporting": 90,
    "public/portal": 14,
}
CYCLES_REQUIRED = 2       # one to plan, one to ship


def sunset_days(callers: list[str]) -> tuple[int, str]:
    """Two release cycles of the slowest affected consumer. Publishing the
    derivation is what makes the date credible rather than negotiable."""
    known = {c: CADENCE_DAYS[c] for c in callers if c in CADENCE_DAYS}
    if not known:
        return 90, "no cadence published for any caller; defaulting to 90 days"
    slowest, days = max(known.items(), key=lambda kv: kv[1])
    return days * CYCLES_REQUIRED, f"{CYCLES_REQUIRED} cycles of {slowest} ({days}d)"

# 3. Enforce in graduated stages

A hard cutover concentrates all the risk into one moment. Each stage below is announced, reversible, and impossible to ignore in turn.

# stages.py — escalating enforcement across the window.
def stage_for(day: int, window: int) -> dict:
    """Header first, so a consumer reading their own logs finds out unprompted.
    Throttling next, which is impossible to ignore and breaks nothing. Errors last."""
    if day < 7:
        return {"header": True, "throttle": None, "error": False}
    if day < window * 0.6:
        return {"header": True, "throttle": None, "error": False}
    if day < window:
        # Deliberate, well-labelled throttling: latency, never failure.
        return {"header": True, "throttle": {"delay_ms": 2000}, "error": False}
    return {"header": True, "throttle": None, "error": True}


def response_headers(version: str, successor: str, sunset_iso: str) -> dict:
    return {
        "Deprecation": "true",
        "Sunset": sunset_iso,                       # RFC 8594
        "Link": f'</products/{successor}>; rel="successor-version"',
        "X-Spatial-Deprecated-Version": version,
    }

Verify the header reaches consumers before the throttle stage begins:

curl -sS -o /dev/null -D - "https://api.internal/products/$PRODUCT/$VERSION/items?limit=1" \
  | grep -iE '^(deprecation|sunset|link):'

# 4. Track progress and retire on an empty caller set

# The progress signal: call volume per caller against the deadline.
watch -n 3600 'curl -sS "$PROM/api/v1/query" --data-urlencode \
  "query=sum by (caller) (rate(product_requests_total{product=\"'"$PRODUCT"'\",version=\"'"$VERSION"'\"}[24h]))" \
  | jq -r ".data.result[] | \"\(.metric.caller) \(.value[1])\""'

# Retirement is a guarded transition: the guard fails while any caller remains.
mesh-platform transition --product "$PRODUCT" --version "$VERSION" --to Archived
# BLOCKED: 1 caller in the last 7 days: planning/reporting

# Configuration Reference

# Common Failure Modes & Fixes

The sunset date passes with callers still active. Root cause: the window came from a template rather than from consumer cadence, or progress was never visible. Fix: derive and publish the window; publish per-caller volume against the deadline where both sides see it.

A consumer appears on the last day, having never been seen. Root cause: a telemetry window shorter than their cadence. Fix: 90 days minimum, and check the 180-day set before the error stage.

Throttling breaks a consumer. Root cause: added latency exceeding a client timeout, which turns a warning into an outage. Fix: keep the added delay well inside typical client timeouts — two seconds is noticeable and safe; twenty is a failure.

Consumers ignore the deprecation header. Root cause: nothing consumes it. Fix: this is why the throttle stage exists; also worth adding a platform-side alert that fires for any consumer calling a version with a Sunset header inside 30 days.

Retirement blocks indefinitely on one caller. Root cause: the deprecation is working; a consumer genuinely cannot move. Fix: this is a conversation, not a technical problem — and it is happening before the outage rather than during it, which is the entire purpose.

# FAQ

# Related

• Spatial Product Lifecycle Management — the parent topic and the lifecycle states
• Automating Lifecycle State Transitions for Spatial Products — the guard that enforces the empty caller set
• Detecting Breaking Changes in Spatial Contracts — the diff a successor must publish