[ANN] jsonschema2atd, Generate an ATD file from a JSON Schema / OpenAPI document

Ecosystem
1

Ahrefs has released jsonschema2atd, a cli tool to convert an OpenAPI or Json Schema specification into an atd file.

Quite a lot of api out there are now publishing some kind of spec for their expected input our output. It’s often done through a a JSON Schema or OpenAPI document. The goal of this tool is to save time for large api by doing a mechanical translation to an atd file instead of writing all the types by hand.

Unfortunately the world is kind of a mess. Most of the specs we have seen are not following a specific version of openapi/jsonschema but contain a bit of everything. jsonschema2atd does its best to do the right thing, but there are probably cases that aren’t covered.

The generated code might also not be optimal. It often deserves some hand cleanup and a bit of renaming. Hopefully it still gives a good head start.

Thanks to Egor Chemokhonenko for this work.

The code is available at GitHub - ahrefs/jsonschema2atd: Generate ATD types from a JSON schema / OpenAPI document
And there is a package that is published on opam jsonschema2atd 0.0.2 (latest) · OCaml Package

15 Likes
2

Many thanks for this tool! I’ve used it already to create an atd spec for json schema of CycloneDX spec. As you noticed, it didn’t work out of the box, but it saved me like 98% of typing, which is truly awesome!

For versioned specifications like CycloneDX it’s probably fine to have some hand-edits, for something more dynamicly evolving in-place it might be more cumbersome/error-prone to re-apply hand edits on top of freshly generated atd schema…

Is it a matter of supporting numerous different edge-cases? Or it’s like not a solvable problem and JSON schema is broken?

1 Like
3

maybe it could be done with more efforts, but we haven’t had the need yet so didn’t really try to solve it. Open to suggestion/contribution to make it happen though.

4

It is a sign of a healthy ecosystem that we had 3 OpenAPI related posts this week (this one, [ANN] v0.17 release of Jane Street packages ocaml_openapi_generator generator and my Scaling factors when compiling mutually recursive definitions which is based on Nomadic Lab’s Json Schema). Side note: At some point it would be good to commonalize the OpenAPI parsing in one place.

I do think it is a solvable problem. For example, I’ve started to place Stripe’s extensions to OpenAPI in a module in my own code:

That module is passed as an optional ~vendor:(module StripeExt) first-class module argument to the OpenAPI generator.

3 Likes