# Shared schemas need a transition period

Principle `schema-changes-need-a-transition`. Keep old and new representations usable while consumers migrate.

Also searched as: transition period, expand and contract, backsliding prevention.

A shared schema change needs time for consumers to move. Discover old uses and prevent new uses before removing the obsolete interface.

> many refactorings require you to run both the original and new versions of the schema in parallel during a transition period that is long enough to allow any applications accessing that portion of the schema time to be redeployed.

Source: [Q19](/bibliography#q19); [B14](/bibliography#b14-refactoring-databases), [B15](/bibliography#b15-software-engineering-at-google).

## Failure it prevents

An independently deployed consumer breaks, or a migration never converges because new old-style uses keep appearing.

## Our Effect 4.0.5 reading

Schema decoding can express supported representations. Database migrations, consumer rollout, usage evidence, and static backsliding checks remain separate responsibilities.

Source: `packages/effect/src/Schema.ts`.

## How to check

Test old and new consumers during the transition. Prove old usage is gone before contraction. This is our proposed verification, not a quoted procedure.

Continue with [Old events must still decode](/principles/old-events-must-still-decode), [Recovery needs model tests](/principles/recovery-needs-model-tests).

Connect this to [the existing rat-stack guidance](https://ratstack.sh/lore/property-based-testing).

Use [the durability skill](/skills/durability) for the full review. Return to [the durability index](/principles/durability).

## Skills
- [Durability starts with a recovery record](/principles/durability)

## Sources
- Ambler, Scott W.; Sadalage, Pramod J. *Refactoring Databases: Evolutionary Database Design*. Addison-Wesley, 2006. [Link](https://www.amazon.com/Refactoring-Databases-Evolutionary-paperback-Addison-Wesley/dp/0321774515). ([b14-refactoring-databases](/bibliography#b14-refactoring-databases))
- Winters, Titus; Manshreck, Tom; Wright, Hyrum, editors. *Software Engineering at Google: Lessons Learned from Programming Over Time*. O’Reilly, 2020. [Link](https://abseil.io/resources/swe-book). ([b15-software-engineering-at-google](/bibliography#b15-software-engineering-at-google))

## References
- [Effect contributors. Effect 4.0.5. Schema.ts](https://github.com/Effect-TS/effect/blob/7f524e25cfb49a71ac39b0f44278d08d40dda5de/packages/effect/src/Schema.ts). Pinned source for our Effect mapping, not a claim from the book.