package atdj

4.0.0 (2026-03-16)

• Build: Dune >= 3.18 (April 2025) is now required to build the ATD tools from source. (#445)
• atdcat: read from stdin when no input file is given, like cat.

• ATD: Experimental. Module support via new from ... import ... syntax. Types to be used must be listed explicitly; the full syntax is:

  from module.path <annots> [as alias] import type1 <annots>, type2, ...

  Key properties:

  • Imported types must be listed explicitly (e.g. from mylib import date, status).
  • Supported languages: OCaml (atdml, not atdgen), Python (atdpy), TypeScript (atdts)
  • Parameterized types declare their arity: from mylib import 'a list_ne.
  • The arity of each imported type is enforced at all use-sites within the importing file.
  • Aliases are plain names without annotations: from foo as f import t.
  • Language-specific name annotations go on the module path: <python name="..."> for atdpy, <ts name="..."> for atdts, <ocaml name="..."> for atdml.
  • atdpy: alias names that are Python keywords are automatically suffixed with _ (e.g. alias class → class_ in generated code).
  • atdts: Dotted module paths in import declarations are now mapped to path-separator form in the generated TypeScript import path. For example, import long.module.path generates import * as path from "./long/module/path" rather than "./path".
  • A warning is printed to stderr when an imported type name is never referenced in any type expression.

  Examples:

        (* Import specific types from a module *)
  from mylib.common import date, status
  
  (* Import with alias *)
  from long.module.path as ext import tag
  
  (* Override OCaml module name *)
  from mylib.common <ocaml name="Mylib_common"> import date

• atdml: Experimental. New tool. Generates a single self-contained OCaml module (.ml + .mli) from a single .atd file, with JSON support via Yojson.Safe.t. No separate runtime library is required; the runtime helpers are inlined into each generated .ml. Atdml is the recommended successor to atdgen for OCaml JSON support. Supported features:

  • All primitive ATD types: unit, bool, int, float, string
  • abstract type, represented as Yojson.Safe.t
  • 'a list, 'a option, 'a nullable
  • Tuples: ('a * 'b * ...)
  • Records, including required fields, optional fields (?foo), and with-default fields (~foo) with implicit or explicit defaults (<ocaml default="...">)
  • <ocaml field_prefix="pre_"> on record types: prepends the given prefix to all OCaml record field names while keeping the labeled arguments of create_ unprefixed (e.g. create_point ~x ~y () : point). JSON field names are unaffected.
  • Classic sum types (regular OCaml variants) and polymorphic variants (<ocaml repr="poly">)
  • Parametric types
  • Mutually recursive types (detected automatically via topological sort; and is used only when strictly necessary)
  • wrap construct with <ocaml module="M"> or explicit <ocaml t="..." wrap="..." unwrap="...">
  • JSON adapters via <json adapter.ocaml="M"> (module providing normalize and restore) or <json adapter.to_ocaml="..." adapter.from_ocaml="..."> (inline expressions); supported on sum types and records
  • <json name="..."> to override JSON field or constructor names
  • <ocaml name="..."> to rename variant constructors in OCaml
  • <ocaml attr="..."> to attach ppx attributes (e.g. [@@deriving show]) to generated type definitions
  • <ocaml private> on any type definition forces private in the generated .mli; <ocaml public> on a primitive alias suppresses the default private, making the alias transparent to callers
  • Unparameterized aliases of primitive types (unit, bool, int, float, string) are generated as private in the .mli, preventing direct construction outside the module. A constructor function create_email : string -> email is generated (also exposed as val create in submodule Email). Coerce back with :> (e.g. (x :> string)).
  • <doc text="..."> documentation annotations, translated into ocamldoc (** ... *) comments in the generated code; supported on type definitions, record fields, variant constructors, and module-level head annotations
  • Automatic renaming of ATD type names that conflict with OCaml keywords or with the foo_of_yojson/yojson_of_foo naming scheme
  • Automatic renaming of record fields and variant constructors that conflict with OCaml keywords (e.g. end → end_)
  • (string * 'a) list <json repr="object">: encode association lists as JSON objects {"key": value, ...} rather than arrays
  • Graceful handling of atdgen annotations not supported by atdml: <ocaml module="..."> on type definitions and <ocaml name="..."> on record fields emit a warning and are otherwise ignored
  • ~field: user_type with no OCaml default: warns and treats the field as required in JSON (no create_ function generated for that type)
  • Record creation functions are named create_foo (not make_foo), matching atdgen's convention
  • Stdin mode: reads ATD from stdin, writes a copy-pasteable module type Types = sig ... end / module Types : Types = struct ... end snippet to stdout
  • Each generated type gets a submodule (module Foo) bundling the type and its conversion functions

3.0.1 (2025-12-09)

• atdgen: -j-std now implies -j like before to avoid breaking existing uses. A warning is now also printed to encourage migration (#443)

3.0.0 (2025-12-09)

• atdgen: Add option -j-gen-modules to generate JSON generic submodules (#420)
• atd-parser: improve (syntax) error messages (#426)
• atdts: Add support for <ts from...> annotations
• atdpy: Add support for <doc text=...> annotations, turning them into docstrings similar to the ocamldoc comments produced by atdgen.
• atdgen: Remove option -j-std, now it's the default, one cannot generate extended-JSON (#425). Options -j-std and -std-json are still available as backward-compatibility no-ops unless environment variable ATDGEN_FAIL_DEPRECATED_OPTIONS is set to true in which case their use results in an exception.

2.16.0 (2025-01-22)

• atdgen: Breaking change, migrate from Bucklescript to Melange (#375)
• atdd: Workaround d compiler bug regarding declaration order when using aliases (#393) Algebraic data types (SumType) now uses alias this syntax.
• atdgen: Add support for <json open_enum> in Melange (#401)
• atdcpp: Initial Release (#404)
• atdcpp: Use double c++ type as default floating point type (#411)
• atdgen: Fix JSON I/O for inline records (#419)
• atdgen: The deprecated atdgen library is no longer available. Use atdgen-runtime instead (#421)
• atddiff: To ensure that all the intended types are checked when new type definitions are added to an ATD file, an --ignore option is now available. It makes atddiff fail if some types are neither selected via --types nor ignored via --ignore.

2.15.0 (2023-10-26)

• atddiff: Breaking changes in the JSON output format of atddiff (#382)
• atddiff: Fix atddiff --version output (#379)
• atddiff: New experimental option --no-locations aimed at producing more stable results that allow diffing successive atddiff reports to spot new findings and ignore old ones (#377)

2.14.1 (2023-10-20)

• atddiff: Fixed reports for new variant cases. They are now correctly reported as forward incompatibilities (#373)

2.14.0 (2023-10-19)

• atdd: Fix various issues with the interoperability of user defined types, used in or outside of records (#355)
• atdd: Generated .d files now have the suffix _atd.d (#355)
• atddiff now supports options for filtering the findings based on the direction of the incompatibility (--backward, --forward) or based on the name of the affected types (--types) (#365)
• atddiff: new option --output-format json for exporting the results to JSON (#360)

2.13.0 (2023-10-15)

• atdts: Stop compiler errors on generated typescript (#348)
• atdts: Don't fail on wrap constructs (#353)
• atdcat: New option -remove-wraps which pretty-prints the type definitions without wrap constructs (#353)
• atdd: Add dlang backend to generate D code from ATD definitions (#349)
• new tool: atddiff. Compares two versions of an ATD file and reports possible incompatibilities in the JSON data. Atddiff ships as part of the atd package together with atdcat (#352, #358)

2.12.0 (2023-05-12)

• atdgen: Annotate generated code with types to disambiguate OCaml classic variants (#331)
• atdpy: Support the option type more correctly so that it follows ATD's convention for JSON encoding. This allows compatibility with JSON produced by other tools of the ATD suite. The Python type, however, is still a nullable (Optional) to make things simpler for Python programmers. This prevents distinguishing ["Some", "None"] from "None" which both translate to None in Python. (#332)
• (BREAKING) atdgen: revert default encoding of int64 values as string (#330)
• atdgen: Support <json repr="string"> for int values (#330)
• atdpy: Treat default field values as expressions to evaluate each time they're assigned to a field. This allows the use of mutable defaults such as lists (#339)

2.11.0 (2023-02-08)

• atdpy: Support parametrized type definitions (#303)
• atdpy: Support options approximately by treating them as nullables (#320)
• atdts: Support parametrized type definitions (#303)
• atdts: Fix incorrect type for TypeScript readers/writers generated for type abstract.
• atdts: Fix incorrect type for TypeScript writers of optional fields. It was working only in special cases such as foo?: int.
• atdts: Eliminate the type alias type Int = number since it was more confusing than helpful. Occurrences of Int are replaced by number /*int*/.
• atdts: Disable all tslint and eslint rules in generated code so as to play well with all tslint and eslint configurations.

2.10.0 (2022-08-09)

• atdgen: use Yojson 2.0 API (#299)
• atdpy: Support recursive definitions (#315)
• atdts: fix nullable object field writer (#312)

2.9.1 (2022-06-10)

• atdgen: update abstract type validation to accept all input by default (#301)
• atdts: fix reader for case type (#302)

2.8.0 (2022-06-06)

• atdgen: use odoc syntax to disambiguate clashing names (#296)
• atdpy: propagate decorators on sum types to all constructor classes (#298)

2.7.0 (2022-05-17)

• Add ability to specify JSON/OCaml adapter with the arbitrary code using <json adapter.to_ocaml="..." adapter.from_ocaml="..."> (#184).
• atdcat: add option -jsonschema-no-additional-properties for JSON Schema output to specify that JSON objects may not have extra properties (#293, #294).
• atdcat: add title field to JSON Schema output containing the name of root type (#294).
• atdcat: add command-line option to choose the version of JSON Schema to target. Options are the latest version "Draft 2020-12" and the previous version "Draft 2019-09" (#294).
• ATD language: the abstract built-in can now be used like any other type to hold untyped data, if the implementation supports it. The supported targets so far are OCaml/JSON (atdgen), Python (atdpy), TypeScript (atdts), JSON Schema (atdcat) (#295).

2.6.0 (2022-05-03)

• atdcat: add option -jsonschema to translate from ATD to JSON Schema (#284)

2.5.0 (2022-04-23)

• atdpy: make atdpy --version print the version of atdpy itself rather than the version of the atd library (#270)
• atdpy: fix handling of nullable and improve error message on option types used without optional fields (#277)
• Add TypeScript backend called atdts (#274)

2.4.1 (2022-03-25)

• atdpy: don't apply the @dataclass decorator twice if explicitly added by the user via an ATD annotation such as <python decorator="dataclass(frozen=True)"> (#267)

2.4.0 (2022-03-24)

• atdpy: allow custom imports and class decorators to be added to the generated Python code.

2.3.3 (2022-03-16)

• Prevent incorrect validation errors for annotations of the form <ocaml field_prefix=...> and a few others (#258)

2.3.2 (2022-03-11)

• Fix package dependencies (#257)

2.3.1 (2022-03-10)

• Ensure that atdgen reports its own version rather than the version of the atd library.
• Fix version constraint on cmdliner.

2.3.0 (2022-03-10)

• Allow single-quoted strings as an alternative to double-quoted strings in ATD files (#239)
• Add Python backend called atdpy (#235)
• Add detection of misplaced annotations and misspelled annotation field names for atdgen targets and atdpy (#204, #227)
• atdpy: Downcase Python output files (#251)
• atdpy: Disable flake8 checks on generated code via a special comment (#252)
• atdgen: Add support for ppx attributes on individual type definitions (#238)
• (BREAKING) atdgen: change encoding of int64 values to string (#231)
• other enhancement and fixes (see git log)

2.2.0 (2020-09-03)

• Add support for merging double annotations (<ocaml from="ProtoA"><ocaml predef>)
• Add tests for annotation merging and target-specific annotations

2.1.0 (2019-12-3)

• Fix bug preventing generated code from compiling when using json adapters on recursive types.
• Improve automatic error messages shown in case of failed validation. Now include the validator's name or code.
• Add support for json adapters in the bucklescript backend. (#153)

2.0.0 (2018-05-31)

• Add support for json adapters in OCaml (<json adapter.ocaml=...>)
• Add support for json enums with a catch-all case (<json open_enum>)
• Remove <json tag_field=...> and <json untyped>

1.13.0 (2018-03-27)

• Introduce atdgen-runtime package. This package contains the runtime dependency introduced by the atdgen code generator. The old runtime library is deprecated
• Add atdj to set of released packages. atdj is a java code generator for .atd files.
• Improve generated code to emit ppx attributes to ignore harmless warnings
• Ag_version submodule has been replaced with Version.
• Transition atd aliases using the (wrapped true) mode of jbuilder. This is a breaking change for all of those who use atd the library. All modules are now accessible under the Atd. entry module.