> ## 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.

## 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.


## Related topics

- [Versioning](https://developer.affinity.co/pages/external-api-v2/versioning.md)
- [Version Migration](https://developer.affinity.co/pages/changelog/version-migration.md)
- [OAuth Apps and MCP Clients (CIMD)](https://developer.affinity.co/pages/external-api-v2/oauth-apps.md)
- [Previous Changes](https://developer.affinity.co/pages/changelog/previous-changes.md)
- [Beta Endpoints](https://developer.affinity.co/pages/external-api-v2/beta-endpoints.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.