Unknown data
What happens to members another build wrote — the three policies, the default, and why a downgrade must not wipe data.
Three policies, one default#
| Policy | What happens to a member this build does not know | Use when |
|---|---|---|
PreserveAndReport (default) | It is kept in the document, carried through a load/edit/save cycle, and reported | Almost always: this is what makes a rollback safe |
Preserve | It is kept, with no finding raised | You have a known, deliberate gap and do not want noise |
Reject | The save is refused as containing data this build cannot represent; nothing is modified | Strict modes, test scenes, regulated data |
The carried members are reported as CarryOver on the load result, so "the save contained three fields I do not know" is something you can log rather than guess.
Why preserving is the default#
Consider a player who tries a beta build, then returns to the previous release. Without preservation, every field the beta added is deleted the first time the older build saves — and the player loses progress they never agreed to lose. With preservation, the older build carries those fields through untouched.
The cost is honest and stated: documents that change schema often are somewhat larger, because unknown members are kept rather than dropped. See Limitations.
Reading a save from a newer build#
Preserving unknown members is not the same as accepting a newer schema. By default a save whose schema is newer than the build understands is refused, because the shape of the whole document may have changed. Opting in is explicit:
- per call through
LoadRequestOptions, or - globally through Configuration → Versioning → Allow forward-compatible read.
var loaded = await NexusForgePersistence.Slots.LoadAsync<MySaveModel>(
slot, new LoadRequestOptions { TargetSchemaVersion = new SchemaVersion(2), UnknownData = UnknownDataPolicy.PreserveAndReport });Next#
- Schema versions — the number that decides "newer".
- Migration — closing the gap deliberately.
- Configuration reference — the versioning settings in full.
Something wrong on this page? Every page here describes behaviour that is checked in the repository. If a page and the package disagree, the package wins.
Report a documentation problem · Frequently asked questions · Troubleshooting