Migrate a dataset from one version of an API schema to another. The data must be described by a named type, the name of which is assumed not to change.

The db, rec and fld types must be enumerations of all the custom migration tags in the changelog, as generated by generateMigrationKind.

Check that a changelog adequately describes how to migrate from one version to another.

Check that a dataset matches an API, which is necessary for succesful migration. The name of the dataset's type must be specified.

When to validate the data against the schema (each level implies the preceding levels):

An API changelog, consisting of a list of versions with the changes from one version to the next. The versions must be in descending order (according to the Ord Version instance).

A single change within a changelog

Represents either a released version (with a version number) or the version under development, which is newer than any release

The earliest version in the changelog

The latest version in the changelog

Custom migrations used in the changelog must be implemented in Haskell, and supplied in this record. There are three kinds:

• Whole-database migrations, which may arbitrarily change the API schema and the data to match;
• Type migrations, which may change the schema of a single type; and
• Single field migrations, which may change only the type of the field (with the new type specified in the changelog).

For database and type migrations, if the schema is unchanged, the corresponding function should return Nothing.

The db, ty and fld parameters should be instantiated with the enumeration types generated by generateMigrationKinds, which correspond to the exact set of custom migration tags used in the changelog.

Lift a custom record migration to work on arbitrary values

Lift a schema change on record types to work on arbitrary type declarations

Use for databaseMigration, typeMigration or fieldMigration to indicate that changes to the data are not required

Use for databaseMigrationSchema or typeMigrationSchema to indicate that the schema should not be changed

Generate enumeration datatypes corresponding to the custom migrations used in an API migration changelog.

Within the changelog, custom migrations are represented as strings, so we have less type-safety.

The API type has too much extra info for us to be able to simply compare them with (==). Our strategy is to strip out ancillary information and normalise into a canonical form, and then we can use a simple (==) compare.

Our normalised API discards most of the details of each type, keeping just essential information about each type. We discard order of types and fields, so we can use just associative maps.

The normal or canonical form for a type declaration, an APINode. Equality of the normal form indicates equivalence of APIs.

We track all types.

The canonical form of a record type is a map from fields to values...

...similarly a union is a map from fields to alternatives...

...and an enum is a set of values.

Compute the normal form of an API, discarding extraneous information.

Compute the normal form of a single type declaration.

Errors that may be discovered when validating a changelog

Errors that may occur applying a single API change

Errors that can be discovered when migrating data values