# Version and amend data structures
> Evolve your tracking design safely with backwards-compatible data structure versioning using JSON schema version numbers to control warehouse loader behavior.
> Source: https://docs.snowplow.io/docs/event-studio/data-structures/versioning/
> Documentation index: https://docs.snowplow.io/llms.txt

Every data structure is based on a [versioned schema](/docs/fundamentals/schemas/versioning/).

There are two kinds of schema changes:

- **Non-breaking** — a non-breaking change is backward compatible with historical data and increments the `patch` version (for example, `1-0-0` to `1-0-1`) or the `minor` version (for example, `1-0-0` to `1-1-0`).
- **Breaking** — a breaking change is not backward compatible with historical data and increments the `major` version (for example, `1-0-0` to `2-0-0`).

Different data warehouses handle schema evolution slightly differently. Use the table below as a guide for incrementing the schema version appropriately.

|                                              | Redshift     | Snowflake, BigQuery, Databricks |
| -------------------------------------------- | ------------ | ------------------------------- |
| **Add / remove / rename an optional field**  | Non-breaking | Non-breaking                    |
| **Add / remove / rename a required field**   | Breaking     | Breaking                        |
| **Change a field from optional to required** | Breaking     | Breaking                        |
| **Change a field from required to optional** | Breaking     | Non-breaking                    |
| **Change the type of an existing field**     | Breaking     | Breaking                        |
| **Change the size of an existing field**     | Non-breaking | Non-breaking                    |

> **Note: Size changes**
>
> In Redshift and Databricks, changing _size_ may also mean _type_ change. For example, changing the `maximum` integer from `30000` to `100000`. See our documentation on [how schemas translate to database types](/docs/api-reference/loaders-storage-targets/schemas-in-warehouse/).

## Automatic versioning with the data structure builder

Versioning is automated when using the data structure builder to create or edit your custom data structures.

It will automatically select how to version up your data structure depending on the changes you have just made.

In this example, a new required property has been added to the data structure. This is a breaking change, so the builder will increment the first digit:

![Data structure builder showing the \"add\_to\_cart\" event schema with properties user\_id, product\_id, quantity, and a newly added required property \"category\" highlighted in yellow. A banner at the bottom reads \"Version increased to 2-0-0 — your current version is 1-0-0, based on your changes the new version will be 2-0-0.\"](/assets/images/data-structures-2-1133e290be8b44d1ed1d0f74dcef1c3a.png)

In this example, an additional enum option has been added to `category`. This is a non-breaking change, so the builder is incrementing the middle digit:

![Data structure builder Properties section showing the \"category\" field highlighted in yellow with an updated enum list — books, technology, games, and newly added \"appliances\". A banner at the bottom reads \"Version increased to 2-1-0 — your current version is 2-0-0, based on your changes the new version will be 2-1-0.\"](/assets/images/data-structures-1-984215ae8aba92b496bfca0378c9e0be.png)

## Versioning with the JSON editor

When using the JSON editor, at the point of publishing a data structure you'll be asked to select which version you'd like to create.

![Publish version to development environment dialog for \"subscription\_payment\_failed\" showing four version options: Non-breaking (1-0-1), Non-breaking (1-1-0), Breaking (2-0-0) — currently selected with a recommended upgrade warning — and Patch (1-0-0). A caution banner warns about the impact of selecting the wrong version increment.](/assets/images/json_editor_version_options-bf9596ad2af60a2639de1ee5107f87cd.png)

In this example, for a schema at version `1-0-0`, the dialog offers:

- **Non-breaking**: `1-0-1` or `1-1-0`
- **Breaking**: `2-0-0`
- **Patch**: [patch the current version](#patch-a-schema), which overwrites the existing schema and leaves it at `1-0-0`

For the deployment steps, see [Deploy data structures to your development environment](/docs/event-studio/test-and-publish/#deploy-data-structures-to-your-development-environment).

## Patch a schema

To [patch a schema](/docs/fundamentals/schemas/versioning/#overwrite-a-schema), which means applying changes to it without updating the version, select the **Patch** option when saving the schema.

Note that various pipeline components, most importantly Enrich (including Enrich embedded in Snowplow Mini and Snowplow Micro), cache schemas to improve performance. The default caching time is 10 minutes (it's controlled by the [Iglu Resolver configuration](/docs/api-reference/iglu/iglu-resolver/)). This means that the effect of patching a schema will not be immediate.

> **Note: Self-Hosted users**
>
> If you are using Snowplow Self-Hosted, to patch a schema, don't increment the schema version when [uploading it with `igluctl`](/docs/api-reference/iglu/manage-schemas/).
>
> You'll need to explicitly enable patching in the [Iglu Server configuration](/docs/api-reference/iglu/iglu-repositories/iglu-server/reference/) (`patchesAllowed`) at your own risk.

## Mark a schema as superseded

To [mark a schema as superseded](/docs/fundamentals/schemas/versioning/#mark-a-schema-as-superseded), use the JSON editor and add a `$supersedes` field.

To roll out a new data structure version to the event specifications and tracking code that use it, see [Evolve a tracking design](/docs/event-studio/evolve-tracking-design/).