Schema versions

The number is yours#

SchemaVersion describes your model's shape. It is passed on save and requested on load:

var request = new SaveRequestOptions { SchemaVersion = new SchemaVersion(3) };

var loaded = await NexusForgePersistence.Slots.LoadAsync<MySaveModel>(
    slot, new LoadRequestOptions { TargetSchemaVersion = new SchemaVersion(3) });

It is written into the save, so a build can tell what shape it is looking at before it parses anything.

When to change it#

Bump it when an old save would be read differently by the new build — a renamed field with different meaning, a type that changed, a default that must be recomputed. Do not bump it for adding an optional field with a sensible default: PreserveAndReport (the default policy) already keeps what it does not know.

Forward-incompatible by default, on purpose#

A save whose schema is newer than the build understands is refused unless you opt in, per call or in configuration, because reading it means guessing at a shape this build has never seen. See Unknown data.

The one thing the framework cannot detect#

Declaration catches gaps early#

Declare which versions your build can load in the settings asset (schema version in use and *supported schema versions*). The validation report then fails loudly at build time instead of a player finding out:

Save schema 5 cannot be loaded because migration 4 -> 5 is missing.

Next#

• Migration — writing the step that closes the gap.
• Unknown data — what happens to members this build does not know.
• Configuration reference — the versioning settings.