Import file stability and versioning

If you build a feed, a migration script or an AI agent that writes Soundcheck import files (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.

The reader rejects keys it doesn’t know. Only send fields listed in the field reference 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: 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. 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 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:

Announcement. The change is posted in the changelog and on this page, with the affected paths and the replacement. A deprecated field is marked Deprecated in the field reference.
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.
Removal. After the window, the old shape is refused with an error that names the replacement.

Watch the changelog 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:

{
  "valid": true,
  "errors": [],
  "missing_required": [],
  "schema_version": "2.0"
}

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

{
  "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:

{
  "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 for every kind of error.

Field reference

Every field with its status

Import and export how-tos

Check, import and export import files

Overview

Account & profile

Home

AI assistant

Gigs

Contracts

Client portal

Setlists

Calendar

Mailbox

Availability

Chat

Mobile app

Everyday tools

Imports

Organization

Teams

CRM

Leads

Offerings

Import file stability and versioning

Versions

Stable and Preview

Deprecation and notice

How the checker reports the version

Field reference

Import and export how-tos

​Versions

​Stable and Preview

​Deprecation and notice

​How the checker reports the version

​Related

Field reference

Import and export how-tos

Versions

Stable and Preview

Deprecation and notice

How the checker reports the version

Related