---
title: "Schema / Version Change Incident Playbook"
description: "Handle provider API or feed schema changes with version gates, quarantine, compatibility checks, shadow parsing and rollback."
slug: "schema-version-change-incident-playbook"
translationKey: "playbook-schema-version-change"
locale: "en"
type: "playbook"
category: "operations"
tags: ["schema","api-version","feed","incident","compatibility"]
publishedAt: "2026-09-26"
updatedAt: "2026-09-26"
reviewedAt: "2026-09-26"
---

A schema/version incident occurs when a provider contract change breaks parsing or normalization.

## Trigger

Parser errors, unknown enums, missing fields, rejection spikes or provider deprecation notices.

## Triage

Diff the last successful and first failing payload, check version markers, identify field/type/enum changes and determine whether bad data reached downstream storage.

## Containment

Quarantine the new shape behind a version gate. Roll back to the old parser or degrade the affected provider when necessary.

## Migration

Keep old/new DTOs explicit, version the mapper and run shadow parsing to compare normalized output.

## Stop condition and metrics

Error rates return to baseline, sampled payloads normalize correctly and no corrupted data remains. Track schema rejects, unknown enums, parser versions, quarantine size and migration mismatch.

## Prevention

Maintain contract fixtures, schema snapshots, deprecation calendars and provider-version inventories.