Skip to main content

​
Schema Versions

Data Share tables are organized into versioned schemas (e.g. beta, beta_v0_2, v1.0). Each version defines a stable contract — the set of tables, columns, and their data types. Your queries reference a specific schema version, allowing you to gradually adopt the new version.

​
What Changes Without a New Version

The following changes can happen within an existing schema version and will not break your queries:
  • New columns added to existing tables
  • New tables added to the schema
  • Bug fixes to column values (e.g. correcting a calculation)

​
What Triggers a New Version

A new schema version is released when a change would break existing queries:
  • Removing a column from a table
  • Renaming a column
  • Changing a column’s data type
  • Changing row granularity (e.g. a table starts returning more rows per entity)
  • Changing the meaning of a column’s values (e.g. a score changing from 0–100 to 0.0–1.0)
When this happens, a new schema version is created and the previous version continues to work during a deprecation period.

​
Schema changes announcements

Schema changes will be published as a change log in the documentation website, along with email comminication.

​
Deprecation Policy

When a schema version is deprecated:
StepWhat HappensTimeline
AnnouncementDeprecation notice communicated with migration guidanceDay 0
Overlap periodBoth old and new versions are available and kept up to date30 days
Frozen periodDeprecated version is retained but no longer refreshed with new data30 days
RemovalDeprecated version is removedAfter 60 days
Once the frozen period begins, the deprecated schema version will stop receiving data updates. Migrate your queries to the new version before the frozen period starts to avoid working with stale data.

​
Column Deprecation

Individual columns may also be deprecated within a version. When a column is deprecated:
  1. The column continues to return data during the deprecation period.
  2. A notice is published in the Changelog.
  3. After 30 days, the column may return NULL or be removed in the next schema version.

​
Beta Schemas

Schemas labeled beta (e.g. beta, beta_v0_2) are pre-release. Breaking changes may occur without notice during the beta period. Once a schema is promoted to stable, the full deprecation policy above applies.