Sites

Menu

Backward compatibility

When you change your schema, it’s important you keep it compatible with previous versions of the schema, so that old snapshots can be loaded. Schemalang supports backward compatibility by default.

When you’ve made a change to your schema, you can use the Worker SDK in C++, C# or Java to update a snapshot to the new schema.

Making changes to schema

These are the kinds of changes to the schema you can make and still maintain backward compatibility of your binary snapshots:

JSON snapshots have greater restrictions on backward compatibility than binary snapshots. The following sections outline the backward compatibility properties of binary and JSON snapshots with respect to changes to your schema. However, note that you can convert a JSON snapshot to a binary snapshot using the snapshot converter, allowing you to take advantage of the greater backward compatibility of binary snapshots.

Rename a field or component

Binary snapshots

You can rename fields or components as you like without risking breaking binary snapshots, because binary snapshots only store field and component IDs, not their names. (You’ll still need to update the worker code to use the new names.)

JSON snapshots

JSON snapshots store the names of fields and components, rather than field and component IDs. If you change the name of a field or component, you must replace the old name with the new name in any JSON snapshots using a JSON processor of your choice.

Remove a field

Binary snapshots

You can remove fields without breaking anything in binary snapshots, because unknown fields are ignored when reading a snapshot.

JSON snapshots

It is an error to have a field in your JSON snapshot which is not also present in the accompanying schema bundle. If you remove fields from your schema, you must remove them from your JSON snapshot using a JSON processor of your choice, or convert your JSON snapshot to a binary snapshot using the snapshot converter.

Add a new option, list or map field

Binary snapshots

You can add generic collection fields without breaking binary snapshots, because they can be empty. When a snapshot is loaded, all entities will have an empty data structure for the new field.

If the field needs to be populated with some initial data, do this with C++, C# or Java SDK before loading the snapshot.

JSON snapshots

You cannot add any new fields to your schema without breaking your JSON snapshots. If you add a new field to your schema, you must add the field to the corresponding JSON representation using a JSON processor of your choice, or convert your JSON snapshot to a binary snapshot using the snapshot converter and follow the instructions for binary snapshots.

Convert between collection and non-collection types

Binary snapshots

You can change types between an option<T> field containing a value, a list<T> field containing a single element, and a singular T field, as long as you migrate the snapshot using the C++, C#, or Java SDK first. (This works because the snapshot data formats for three types are identical.) You need to make sure that every entity has exactly one value for the field.

Similarly, you can replace an empty option with an empty list, and vice versa.

Furthermore, you can change a map<K, V> field to a list<T> field (and vice versa), where T is defined as:

type T {
  K key = 1;
  V value = 2;
}

JSON snapshots

You can change types between an option<T> field containing a value and a list<T> field containing a single element in JSON because these are both represented as JSON lists. However, in order to change between collection types a singular type in your schema, you must replace the JSON collection containing a single element of T with the JSON representation of T using a JSON processor of your choice, or convert your JSON snapshot to a binary snapshot using the snapshot converter and follow the instructions for binary snapshots.

Add a new non-collection field

Binary snapshots

Adding a field that isn’t a collection is trickier, as the data must be present for each entity in the snapshot. Adding a non-collection field without making sure the data is present will break existing snapshots.

To add a new non-collection field:

  1. Add an option<T> field.
  2. Migrate the snapshot using the C++, C# or Java SDK to fill in the value for every entity.
  3. Replace the option<T> field with a bare T field.

JSON snapshots

You cannot add any new fields to your schema without breaking your JSON snapshots. If you add a new field to your schema, you must you must add the new field to the corresponding JSON representation using a JSON processor of your choice, or convert your JSON snapshot to a binary snapshot using the snapshot converter and follow the instructions for binary snapshots.

Replace a field or group of fields with a different representation

Binary snapshots

You can’t directly change the type of a field or a group of fields (for example converting an integer into a floating-point value) without breaking binary snapshots.

You’ll need to:

  1. Add a new field or group of fields with the desired types.
  2. Migrate the snapshot using the C++, C# or Java SDK to compute and store the new values using the old values.
  3. Remove the old fields from the schema.

JSON snapshots

In JSON snapshots:

  • all integral types are represented as number, and you can change the type of an integral field to another integral field without breaking snapshots, as long as the values contained within the snapshot adhere to the size and sign of the new integral type.

  • float and double are both represented as number, and you can change the type of a float field to be double. You can change the type of a double field to a float as long as the values in your snapshots are within the size range of float.

For all other types, you must convert your JSON snapshot to a binary snapshot using the snapshot converter and follow the instructions for binary snapshots.

Search results

Was this page helpful?

Thanks for letting us know!

Thanks for your feedback

Need more help? Ask on the forums