Change a schema after you've shipped

Once your app is in users' hands, its schema lives in two places you don't control: the local database on every device, and the EAS schemas that published items are attested under. Make additive changes, and rename or retype a property only as described below. The SDK has no migration runner: the migrations array in the schema file is a record that the client stores and never acts on (migrations). Renaming summary to excerpt in the file with a property_rename entry for it leaves excerpt empty and the values under summary.

You'll need: a schema you've already published items with, and the edit, raise-version, restart loop from Define a schema and add to it.

Where your schema lives

On each device, the client applies config.schema every time it starts. It adds new models and properties and updates changed ones, but it never deletes anything. A new app version brings its schema with it, so a device picks up the change the first time the new code runs. There's no server-side step and no migration to schedule.

On EAS, the only parts of your schema that exist are names and types. Each model and property is an EAS schema named after its EAS type and EAS name: Post is bytes32 post, title: Text is string title, and a List of Relation also includes the target model, so authors with ref: "Author" is bytes32[] author_author_ids (What's published where). Your schema's name, its version and its migrations aren't recorded on-chain. EAS schemas can't be changed or deleted, and they're shared by every app: any app whose Post has a title of type Text reads and writes the same string title attestations. The first publish of a model or property nobody has used before registers its EAS schema.

When a device syncs from EAS, the SDK matches each attested name to one of your model's properties, by default loosely: case, separators, a plural s and a relation's _id are ignored, so published_at, PublishedAt and publishedAts all reach a local publishedAt. nameMatch sets how loosely. The value is stored under your property's name, unless its EAS type doesn't fit your property's type, in which case sync skips it with a warning (How EAS sync works). That's why names and types are the contract.

Older SDKs published some models and properties differently: acronyms and digits weren't split (HTMLPage was htmlpage), a single relation could be published as author_id, and a Number was published as uint8. Sync still finds those values; nameMatch: 'exact' stops old names syncing in. Publishing uses the current name and type, so the first publish of such a model or property registers a new EAS schema, and readers that look only for the old one, such as older app versions, don't see values published under the new one.

Safe changes

These changes are safe on devices that already have data and for items that are already published:

Fill in a new property has a backfill script. Older app versions keep working after you add a property: they don't define it, so their code never asks for it.

Unsafe changes

Rename a property

To rename a property and keep its local values, give the new name the old property's id. The id is in the version file the SDK writes to the files directory ({id}_blog_v3.json, under models.Author.properties.bio.id) and on the loaded ModelProperty as property.id. To rename Author.bio to about, replace the bio entry with:

"about": { "type": "Text", "id": "e50bb83531" }

Raise version and ship. Each device that starts with the new file renames the stored property and moves its values to about. Without the id, about is a new, empty property and the values stay under bio.

That moves local values only. Values already published stay on EAS under string bio, sync stores them under bio rather than about, and other apps and older versions of yours keep reading bio. Once a property has published values, replace it instead, as in the next section.

The SDK also exports renameModelProperty(schemaName, modelName, oldName, newName), which writes a new version file with the property renamed and moves its values. The rename stays on this device after a restart, even though seed.schema.json still has the old name. Other devices don't get it, so the id in the file is the way to rename everywhere.

Replace a property you got wrong

A replacement is a new property that lives next to the old one. Say you shipped summary: Text and now want excerpt: Text with a higher length limit.

1. Add the new property and keep the old one

"summary": { "type": "Text", "description": "Deprecated: read through readExcerpt()" },
"excerpt": { "type": "Text", "validation": { "maxLength": 1000 } }

Raise version and ship. Every device adds excerpt on its next start.

2. Read the new name, falling back to the old one

Items published or synced before the change only have summary. Read through one helper so the fallback lives in one place:

type PostFields = { summary?: string | null; excerpt?: string | null }

export function readExcerpt(post: PostFields): string {
  return post.excerpt || post.summary || ''
}

3. Write only the new name

Every form and import writes excerpt. When a user edits an old post, the value they save goes to excerpt, and the next time they publish it, the item gets an excerpt attestation. Readers using the fallback see the right value either way.

4. Optionally copy local values

You can copy summary into excerpt on each device, for example once at startup after the update. Only copy items the user owns: other users' items are read-only, and nobody else can publish a new value for them.

import { Item, isItemOwned } from '@seedprotocol/sdk'
import type { IItem } from '@seedprotocol/sdk'

type Post = IItem<any> & { summary?: string; excerpt?: string }

export async function copySummaryToExcerpt() {
  const posts = (await Item.all('Post', false, {
    includeEas: true,
    waitForReady: true,
  })) as Post[]

  for (const post of posts) {
    if (post.excerpt || !post.summary) continue
    if (!(await isItemOwned(post))) continue
    post.excerpt = post.summary
    await post.properties.find((p) => p.propertyName === 'excerpt')?.save()
  }
}

Copying only changes the local database. Published items keep their old attestations until the user publishes again, and each publish costs gas, so don't republish every item only to move a value. The fallback in step 2 makes that unnecessary.

Leave summary in the file for good. Removing it doesn't delete it from devices, and keeping it documents why the data has two names.

Change a type

Use the same steps with a new name, and convert the values as you copy them. To turn wordCount: Number into a Text property, add wordCountText: Text, read wordCountText ?? String(wordCount), and write only the new property. Don't change the type of an existing property.

Rolling out a change

• Ship the schema with the code that uses it. The schema is applied when the new code starts, so a device never has code that expects a property its database doesn't have.
• Expect several app versions at once. Web apps update on reload, but installed apps, open tabs and other teams' apps that read your models keep the old shape for a while. Additive changes are safe for all of them.
• Don't read schema.version to decide what a device has. In the session that applies an update, a Schema instance still reports the previous version. The models and properties are current.
• Test the upgrade path, not only a fresh install. Run the old version, create and publish items, then start the new version on the same files directory and check that old items still render through your fallbacks.

Related

• Define a schema and add to it: naming rules and the edit, raise-version, restart loop
• Schemas, Models, Items, Properties and Permanence: why published data can't be changed
• ModelProperty: how each type is attested
• Schema: nameMatch and the migrations field
• Publishing and revoking and Syncing across devices
• Ownership and drafts: which items a user can change