[Announce] Tool to generate JSON Schema from TypeScript interfaces

Topics: General
Jan 7, 2014 at 8:24 PM
Typson is a pure-javascript tool running in node.js or the browser to generate json-schemas out of TypeScript interfaces.

Its primary goal is to provide a full expressive typed language to define JSON structure definitions in a modular way (with IDE support, syntax and type checking). TypeScript has been chosen thanks to its JSON compatibility and pure-javascript implementation.

I think, it may also be of use for TypeScript developers for exposing their type definitions accross technology boundaries.
Jan 8, 2014 at 12:16 PM
That looks interesting.

Can you elaborate on the intended usage of Typson? The blurb is rather abstract, what do you mean when you say "exposing their type definitions accross technology boundaries"?

Does that mean using it in a browser? What if I want to use the JSON for generating test objects? How would I incorporate Typeson into a Visual Studio build process?
Jan 8, 2014 at 5:17 PM
I have no definitive idea of what could be the different uses of Typson for TypeScript developers. It is possible that someone would use it in a way I did not imagine.

JSON is nowadays a common format for many cases from data exchange between applications to persistence. Its simplicity makes interoperability very easy to realize.

JSON schema is an attempt at standardizing the way we describe JSON data. There is an emergence of tools that uses JSON schema: validators, document generators, code generators (and vice-versa), see http://json-schema.org/implementations.html. There is quite a need for such a standard, I think.

Two cases I imagined where it could be useful:

1) A pure browser TypeScript application that renders/manipulate data. The data structure would surely be defined as TypeScript interfaces. Typson would provide a JSON schema version of this data structure. One may want to connect this application to different servers providing this data. These servers can be implemented in any technology (PHP, .NET, Java, Node.js, ...). So, one can use the JSON schema to document and validate the JSON data. We can even generate the server classes out of the JSON schema.

2) A Node.js server-side application written in TypeScript that expose a JSON/REST API to clients (any technology). Here again, one can generate the documentation (e.g. with Swagger) out of the TypeScript interfaces, validate the data sent by clients and also generate the client-side types.

This is actually a contract-last approach to interface definition.

There are some JSON schema tools able to generate fake data from JSON schema, so the use case you describe makes sense.

Now, I am not a Visual Studio user, so I don't exactly know how this could be integrated in a build process, but I imagine that spawning the node.js version of Typson during the build process is possible (after all, the TypeScript compiler is a node.js module).
Apr 30, 2014 at 7:04 PM
Edited Apr 30, 2014 at 7:08 PM
This is interesting because currently we're using YUIDoc to generate API docs for our library. However, it's extra verbose because we have to duplicate annotations that TS already can tell us.

I may look into using your project as input to my Assemble YUI doc generator and generate documentation from Typson instead, if it can meet our needs. Thanks for posting.

Edit: I see you also have Docson. This combo looks pretty awesome. I wonder if it can support what we currently get out of YUI (namely, custom templating, line numbers and filenames (to link back to GitHub), private members, derived members, inherited members, etc.). For example, here's what our Assemble YUI generator creates from our YUIDoc TS files:

http://excaliburjs.com/docs/api/