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 C++, C# or Java SDKs to update a snapshot to the new schema.

Making changes to schema

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

• Rename a field or component
• Remove a field
• Add a new option, list or map field
• Convert between collection and non-collection types
• Add a new non-collection field
• Replace a field or group of fields with a different representation

Rename a field or component

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

Remove a field

Fields can be removed without breaking anything, because unknown fields are ignored when reading a snapshot.

Add a new option, list or map field

You can add generic collection fields without breaking 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.

Convert between collection and non-collection types

You can change types between an option<T> field containing a value, a list<T> field containing 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;
}

Add a new non-collection field

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.

Replace a field or group of fields with a different representation

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 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.

Search results