> ## Documentation Index
> Fetch the complete documentation index at: https://developer.affinity.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning & Deprecation

> How Data Share schemas are versioned and what to expect when things change

## Schema Versions

Data Share tables are organized into **versioned schemas** (e.g. `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:

| Step           | What Happens                                                         | Timeline      |
| -------------- | -------------------------------------------------------------------- | ------------- |
| Announcement   | Deprecation notice communicated with migration guidance              | Day 0         |
| Overlap period | Both old and new versions are available and kept up to date          | 30 days       |
| Frozen period  | Deprecated version is retained but no longer refreshed with new data | 30 days       |
| Removal        | Deprecated version is removed                                        | After 60 days |

<Warning>
  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.
</Warning>

## 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 documentation change log.
3. After 30 days, the column may return `NULL` or be removed in the next schema version.