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

# Import file stability and versioning

> What we promise not to break in the Soundcheck import file (UEF), what Stable and Preview mean, how you hear about changes, and how check_import_file reports the version

If you build a feed, a migration script or an AI agent that writes [Soundcheck import files](https://docs.soundchecklive.io/features/imports/universal-event-format.md) (also called UEF), it should keep working without you touching it. This page is our promise about that: what we may change, what we won't, and how you hear about a change before it affects you.

**In short:** while the version number starts with **2.**, a file that imports today keeps importing the same way. We only add new, optional fields. Anything that could break a working file waits for version 3, is announced first, and the old version keeps working for a while after.

The import file format, this policy and every field decision are owned by Soundcheck's Ontology Architect. These docs describe the decisions; they don't make them.

***

## Versions

An import file says which version it was written for in `schema_version`, such as `"2.0"`. The first number is the **major** version and the second is the **minor** version. The current version is **2.0**.

| What changes | New version |
| - | - |
| Something is added: a new optional field, a new list of records, a new allowed value | Minor (`2.0` → `2.1`) |
| Something that could break a working file: a field removed or renamed, its type changed, an optional field made required, a range or list of allowed values made smaller, a value's meaning changed | Major (`2.x` → `3.0`) |

**Within a major version, things are only added.** A file that works at `2.0` keeps working, and imports the same way, at every later `2.x`. New fields are always optional, so you never have to send something you didn't know about.

Soundcheck accepts `2.0` and any later `2.x` in `schema_version`, and reads the file against the current 2.x format. A file with another major version is refused before anything is read. Version 1.0 files are no longer imported: 2.0 replaced 1.0 before this policy was published, so 1.0 had no deprecation window. Move a 1.0 file to the 2.0 shape, or export again to get a 2.0 file.

> [!NOTE]
>
> The reader rejects keys it doesn't know. Only send fields listed in the [field
> reference](https://docs.soundchecklive.io/features/imports/import-format-reference.md) for the version Soundcheck serves; `get_import_format`
> always returns that version.

***

## Stable and Preview

| Status | What it means |
| - | - |
| **Stable** | Covered by the versioning rules above. It keeps its name, type and meaning for the whole major version, and it's only removed in a new major version, after the deprecation window below. |
| **Preview** | Usable now, but may change or be removed in a minor version. A Preview field is marked **Preview** in the Status column of the field reference. Don't build anything you can't easily change on a Preview field. |

**Every field in version 2.0 is Stable today.** No field is in Preview. To check one field, find it in the [field reference](https://docs.soundchecklive.io/features/imports/import-format-reference.md): its Status column says **Stable** or **Preview**. A field that isn't listed there isn't part of UEF 2.0, and import rejects it.

Some things are not covered by this policy:

* How a value is shown in Soundcheck (labels, layout, which tab it lands on).
* The wording of `check_import_file` error messages. Match on the error's `path` and `severity`, not its `message`.
* Tools and features labelled Private Preview, such as [AI file ingestion](https://docs.soundchecklive.io/features/ai/file-ingestion.md). The import files they produce follow this policy; the tools themselves don't.
* How a file's records are matched against records already in your workspace. The rules on [identity and safe re-imports](https://docs.soundchecklive.io/features/imports/universal-event-format.md#identity-and-safe-re-imports) can get safer, for example to refuse an ambiguous match.

***

## Deprecation and notice

When a field, a value or a whole major version is going to stop being accepted:

1. **Announcement.** The change is posted in the [changelog](https://docs.soundchecklive.io/changelog.md) and on this page, with the affected paths and the replacement. A deprecated field is marked **Deprecated** in the field reference.
2. **Window.** For at least **6 months** after the announcement, Soundcheck keeps accepting the old shape. A new major version is accepted alongside the previous one for that window, so you can move when it suits you.
3. **Removal.** After the window, the old shape is refused with an error that names the replacement.

Watch the [changelog](https://docs.soundchecklive.io/changelog.md) to hear about changes to the import file.

***

## How the checker reports the version

`check_import_file` (formerly `validate_uef`) checks a file on its own, with no login and nothing saved. Its result always carries `schema_version`: the version of the schema it checked against, which is the version `get_import_format` serves. It is not an echo of the document's own `schema_version`.

A file written for a later minor version (`"schema_version": "2.4"`) is checked against the served 2.x schema. If it uses only fields that schema knows, it's valid:

```json theme={null}
{
  "valid": true,
  "errors": [],
  "missing_required": [],
  "schema_version": "2.0"
}
```

A file for another major version is refused, and nothing else in it is checked:

```json theme={null}
{
  "valid": false,
  "errors": [
    {
      "path": "schema_version",
      "message": "schema_version must be \"2.0\" (any later 2.x is accepted); UEF 1.0 is no longer imported",
      "severity": "error"
    }
  ],
  "missing_required": [],
  "schema_version": "2.0"
}
```

A key that isn't a field of the served version is reported on its own path:

```json theme={null}
{
  "valid": false,
  "errors": [
    {
      "path": "events[0].guest_total",
      "message": "guest_total is not a UEF 2.0 field; import rejects it",
      "severity": "error"
    }
  ],
  "missing_required": [],
  "schema_version": "2.0"
}
```

Compare the result's `schema_version` with the version you built against. If the major version differs, your integration needs the migration announced in the changelog. See [Read the check results](https://docs.soundchecklive.io/features/imports/import-export-guide.md#read-the-check-results) for every kind of error.

***

## Related

> **[Field reference](https://docs.soundchecklive.io/features/imports/import-format-reference.md)**
>
> Every field with its status

> **[Import and export how-tos](https://docs.soundchecklive.io/features/imports/import-export-guide.md)**
>
> Check, import and export import files


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