Version compatibility

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.

Current versions

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

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

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:

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

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

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

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, Backup and restore and Studio Browser API cover the formats and the API in detail.