# Version compatibility

Identify the API, CanvasDocument, Design Lab, saved-design and Lottie version numbers, and migrate older source without losing newer state.

Glyphfield versions each boundary on its own. The HTTP envelope version, the portable canvas schema, the Design Lab metadata version, the generated compatibility document and the third-party Lottie version are separate numbers, and one does not replace another.

<DocsMedia alt="Glyphfield Design Lab with source-backed layers and output controls" caption="One visible design, several explicit contracts" meta="HTTP · CanvasDocument · Design Lab · export" src="/screenshots/studio-gt-design-lab-dark-2026.webp" />

## Current versions [#current-versions]

| Boundary                               | Current version                                                                                                       | Compatibility behavior                                                                      | Where to read it                                                                    |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Agent manifest                         | `schemaVersion: 3` (agent API `version` `0.3.0`)                                                                      | Stop when the version is one your client does not know                                      | `GET /api/agent`                                                                    |
| Generation contract                    | `schemaVersion: 3`                                                                                                    | Describes the request schema for `POST /api/generate`                                       | `GET /api/generate`                                                                 |
| Discovery catalogs                     | `/api/labs` and `/api/identities` are `schemaVersion: 2`. `/api/materials` and `/api/elements` are `schemaVersion: 1` | Stop when the version is one your client does not know                                      | Each route's response                                                               |
| `POST /api/generate` response envelope | `schemaVersion: 1`                                                                                                    | The envelope is not a CanvasDocument                                                        | `GET /api/generate` and `/openapi.json`                                             |
| CanvasDocument                         | `schemaVersion: 2`                                                                                                    | A valid schema 1 document migrates to schema 2. Other versions are rejected                 | `readSource()` after applying                                                       |
| Design Lab metadata                    | `sourceVersion: 4`                                                                                                    | Parsed inside the CanvasDocument metadata                                                   | The active Design Lab source                                                        |
| Expression tool metadata               | `metadata.studio.sourceVersion: 2`                                                                                    | Version-1 flat states migrate. A newer version is rejected                                  | OpenGraph, Terminal card, Partnership lockup, Blog cover and Slide templates source |
| Generated Design Lab sequence document | `version: 3`                                                                                                          | Apply-ready compatibility input that application normalizes into the current CanvasDocument | The `document` of a `design-sequence` response                                      |
| Saved-design database                  | IndexedDB database version 1                                                                                          | Moves valid older localStorage saves into IndexedDB. It is not a public interchange format  | Glyphfield's persistence layer                                                      |
| Lottie                                 | The file's own `v`, `fr`, `ip` and `op`                                                                               | Player support depends on the animation's features and the browser                          | The imported JSON or `.lottie` file                                                 |

Do not compare these values as if a higher number replaced a lower one. CanvasDocument schema 2 contains Design Lab source version 4, and both are current.

## Compatibility rules [#compatibility-rules]

1. Discover live contracts. Read the relevant route or the active Studio tool's Browser API instead of trusting an old sample.
2. Migrate through the tool that owns the source. Apply source with `applySource()` so the tool validator performs any supported normalization.
3. Reject unknown versions. Do not guess how to read a future schema.
4. Keep data you do not own. Start from the current source, keep stable IDs and unknown metadata, and change the smallest field that does the job.

## CanvasDocument migration [#canvasdocument-migration]

The canvas parser accepts schema 2 and migrates a valid schema 1 document. The migration creates schema 2 asset records from the old asset and font ID lists, adds empty element `data` where it is missing, and records `migratedFromSchemaVersion: 1` in the metadata. Any other schema version fails with `Canvas schema version <n> is unsupported.`

After applying an older document, read and store the normalized result right away:

```js
const studio = window.glyphfield.studio;
const imported = JSON.parse(legacySource);

await studio.applySource(imported);

const normalized = JSON.parse(studio.readSource());
if (normalized.schemaVersion !== 2) {
  throw new Error('Glyphfield did not return the current canvas schema.');
}

// Store `normalized` instead of the older input.
```

Migration does not create missing binary files. A migrated asset record without embedded bytes still needs the original authorized image or font before the document is portable.

## Generated sequence compatibility [#generated-sequence-compatibility]

`kind: "design-sequence"` returns a short version-3 document inside a response-schema-1 envelope. The document is built to create a composition. It does not carry every field of the current canvas scene graph.

To use it:

1. Read `GET /api/generate` and build a valid request.
2. Confirm that the response envelope has `schemaVersion: 1`.
3. Apply `response.document` to the active Design Lab workspace.
4. Read the normalized CanvasDocument.
5. Make later edits against that current document.

Stop editing the version-3 input once it has been applied, because it cannot hold the newer fields that the Studio adds.

## Unknown and future versions [#unknown-and-future-versions]

Stop when any of these occurs:

* A discovery or generation envelope has a `schemaVersion` your client does not know.
* A CanvasDocument schema is newer than the parser supports.
* The active tool does not report the expected source format in `describe().capabilities.source`.
* A Lottie source has no numeric frame rate (`fr`) or no `layers` array.

Keep the original bytes, record the Glyphfield commit or deployed version, and open the source in a compatible or newer release. Do not remove version fields to force acceptance.

## Checklist for schema changes [#checklist-for-schema-changes]

A change to a source format should update:

1. The serializer, parser, validation and migration code.
2. The Browser API `describe()` metadata and action behavior.
3. The HTTP request and response schemas when the deterministic API is affected.
4. `/api/agent`, `/openapi.json`, `/llms.txt` and the processed Markdown docs.
5. Round-trip, persistence, old-version migration and malformed-input tests.
6. A visual restore and export check with a realistic saved document.

[Source format reference](/docs/reference/source-formats), [Backup and restore](/docs/artifacts/backup-and-restore) and [Studio Browser API](/docs/reference/browser-api) cover the formats and the API in detail.