[new] atddiff: report incompatibilities after modifying a typed interface

Community
,
1

Background

ATD stands for “Adjustable Type Definitions”. The ATD project consists of a language for specifying types and their JSON representation and code generators that make it safe and easy to read and write JSON data. It currently offers interoperability for 6 programming languages (D, Java, OCaml, Scala, TypeScript, Python/Mypy).

Tracking incompatibilities with atddiff

Atddiff takes two versions of an .atd file, which is a collection of type definitions, compares them and reports incompatibilities. Here’s a simple example:

(* example.v1.atd  *)
type t = {
  x: string;
}

(* example.v2.atd *)
type t = {
  ?x: string option;
}

Atddiff finds one problem:

$ atddiff example.v1.atd example.v2.atd
[221ed3ce] Forward incompatibility:
File "example.v1.atd", line 2, characters 2-11
File "example.v2.atd", line 2, characters 2-19:
Formerly required field 'x' is now optional.
The following types are affected:
  t

Incompatibilities can be backward (= can’t read older data), forward (= can’t read newer data), or both. Depending on the use case for a type, the user may care about just one direction. The documentation expands a bit on this and provides a command to use atddiff with git.

The recommended version of atddiff is the latest, >= 2.15.0. It is installed as part of the atd opam package:

opam update
opam install atd.2.15.0
15 Likes