Use this exactly how you would use toJSON from Data.Aeson. Though most use cases will probably use one of the encode functions from Data.Aeson.Safe.

safeToJSON will add a version tag to the Value created. If the Value resulting from safeTo (by default the same as toJSON) is an Object, an extra field with the version number will be added.

Example value:
  {"type":"test", "data":true}

Resulting object:
  {"!v": 1, "type":"test", "data":true}

If the resulting Value is not an Object, it will be wrapped in one, with a version field:

Example value:
  "arbitrary string"

Resulting object:
  {"~v": 1, "~d": "arbitrary string"}

This function does not check consistency of the SafeJSON instances. It is advised to always testConsistency for all your instances in a production setting.

Use this exactly how you would use parseJSON from Data.Aeson. Though most use cases will probably use one of the decode functions from Data.Aeson.Safe.

safeFromJSON tries to find the version number in the JSON Value provided, find the appropriate parser and migrate the parsed result back to the requested type using Migrate instances.

If there is no version number (that means this can also happen with completely unrelated JSON messages), and there is a SafeJSON instance in the chain that has version defined as noVersion, it will try to parse that type.

N.B. If the consistency of the SafeJSON instance in question is faulty, this will always fail.

A type that can be converted from and to JSON with versioning baked in, using Migrate to automate migration between versions, reducing headaches when the need arrises to modify JSON formats while old formats can't simply be disregarded.

This is an inpenetrable container. A security measure used to ensure safeFrom and safeTo are never used directly. Instead, always use safeFromJSON and safeToJSON.

Used when defining safeFrom or safeTo.

A simple numeric version id.

Version has a Num instance and should be declared using integer literals: version = 2

This is used for types that don't have a version tag.

This is used for primitive values that are tagged with a version number, like Int, Text, [a], etc.

But also when implementing SafeJSON after the fact, when a format is already in use, but you still want to be able to migrate from it to a newer type or format.

N.B. version = noVersion is distinctively different from version = 0, which will add a version tag with the number 0 (zero), whereas noVersion will not add a version tag.

The kind of a SafeJSON type determines how it can be migrated to.

Used to define kind. Base types do not extend any type.

Used to define kind. Extends a previous version.

Used to define kind. Types that are extended_base, are extended by a future version and as such can migrate backward from that future version. (cf. extended_extension, base)

Used to define kind. Types that are extended_extension are extended by a future version and as such can migrate from that future version, but they also extend a previous version. (cf. extended_base, extension)

Type name string representation of a nullary type constructor.

Type name string representation of a unary type constructor.

Type name string representation of a binary type constructor.

Type name string representation of a ternary type constructor.

Type name string representation of a 4-ary type constructor.

Type name string representation of a 5-ary type constructor.

Profile of the internal consistency of a SafeJSON instance.

N.B. noVersion shows as null instead of a number.

Version profile of a consistent SafeJSON instance.

This instance is needed to handle the migration between older and newer versions.

Note that, where (Migrate a) migrates from the previous version to the type a, (Migrate (Reverse a)) migrates from the future version to the type a.

Example

instance Migrate NewType where
  type MigrateFrom NewType = OldType
  migrate OldType = NewType

instance Migrate (Reverse OldType) where
  type MigrateFrom (Reverse OldType) = NewType
  migrate NewType = Reverse OldType

This is a wrapper type used migrating backwards in the chain of compatible types.

This is useful when running updates in production where new-format JSON will be received by old-format expecting programs.