The ATD Project¶
The ATD project aims to facilitate the design and the implementation of APIs, and in particular JSON APIs. It offers type safety and automatic data validation by deriving boilerplate code from type definitions. The data ends up being represented with idiomatic data structures in the target programming language, removing the hassle of manually converting from/to the JSON representation.
Currently, the supported target languages are OCaml, Java, Scala, and Python. The project is run by volunteers and users from various organizations. Check out the ATD project on GitHub for any bug report, feature request, or question.
Some properties of interest of ATD schemas include:
support for optional fields and default field values
support for sum types aka algebraic data types or tagged unions
options to select alternate representations than the default, e.g. use a JSON object rather than an array of pairs
Feature Support Matrix¶
For each ATD feature, target languages are grouped by support level.
Basic types¶
unit, bool, int, float, string
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Abstract type¶
Any JSON value (abstract keyword)
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
List / array¶
The list type constructor
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Option type¶
ATD-style “None” / [“Some”, x] encoding
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Nullable¶
JSON null <-> None, other value <-> Some x
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Wrap type¶
Custom type wrappers (‘a wrap)
Supported: atdml (OCaml), atdgen (OCaml), atdts (TypeScript), atdd (D), atdcpp (C++)
Not yet: atdpy (Python), atdj (Java), atds (Scala)
Records¶
Record types with named fields
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Sum types¶
Tagged unions / variants
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Tuples¶
Fixed-arity product types
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Parametric types¶
Generic / parameterized type definitions
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Type aliases¶
Simple aliases (type t = int list)
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Optional fields¶
?field — absent JSON key <-> None
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Default-value fields¶
~field — absent JSON key uses a default
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Doc comments¶
<doc text=”…”> -> language docstrings
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala)
Not yet: atdd (D), atdcpp (C++)
JSON field names¶
<json name=”…”> on record fields
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
JSON variant names¶
<json name=”…”> on sum type constructors
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Assoc as JSON object¶
(string * v) list <json repr=”object”>
Supported: atdml (OCaml), atdgen (OCaml), atdpy (Python), atdts (TypeScript)
Not yet: atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Sum as JSON object¶
sum type <json repr=”object”>: {“Cons”: payload}
Supported: atdml (OCaml)
Not yet: atdgen (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
JSON adapter¶
Custom pre/post-processing hooks
Supported: atdml (OCaml), atdgen (OCaml)
Not yet: atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Cross-file imports¶
from module import type1, type2
Supported: atdml (OCaml), atdpy (Python), atdts (TypeScript)
Not yet: atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Not supported: atdgen (OCaml)
Binary serialization¶
Biniou format: faster than JSON, field/constructor names encoded as low-collision hashes
Supported: atdgen (OCaml)
Not supported: atdml (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)
Open enumerations¶
Unknown variants round-tripped as-is
Supported: atdgen (OCaml)
Not yet: atdml (OCaml), atdpy (Python), atdts (TypeScript), atdj (Java), atds (Scala), atdd (D), atdcpp (C++)