jtd-codegen

jtd-codegen generates code (datatypes, classes, etc.) in many programming languages from JSON Typedef schemas.

For high-level guidance on how to use this package, see "Generating Code from JSON Typedef Schemas" in the JSON Typedef docs. For high-level guidance on how to use this package with your particular programming language of choice, see:

• "Generating TypeScript from JSON Typedef Schemas"
• "Generating Golang from JSON Typedef Schemas"

In addition to the general docs in this README, each programming language that jtd-codegen supports has its own set of specific documentation:

• jtd-codegen + TypeScript README
• jtd-codegen + Golang README

Installation

To install jtd-codegen, you have a few options:

Install with Homebrew

This option is recommended if you're on macOS.

brew install jsontypedef/jsontypedef/jtd-codegen

Install with Docker

This option is recommended on non-Mac platforms, or if you're running jtd-codegen in some sort of script and you want to make sure that everyone running the script uses the same version of jtd-codegen.

docker pull jsontypedef/jtd-tools

If you opt to use the Docker approach, you will need to change all invocations of jtd-codegen in this README from:

jtd-codegen [...]

To:

docker exec -it jsontypedef/jtd-tools /jtd-codegen [...]

Install with Cargo

This option is recommended if you already have cargo installed, or if you would prefer to use a version of jtd-codegen compiled on your machine:

cargo install jtd-codegen

Usage

See the top of this README for links to high-level guidance and specifics for each programming language.

For help running jtd-codegen, run:

jtd-codegen --help

There are two prerequisites to invoking jtd-codegen:

1. You need to have your schema in a file. jtd-codegen will use the name of that file to infer the names of the datatypes/classes/etc it will generate.

2. You need to have a separate "output" directory for each output language you want to use. jtd-codegen will not create this directory for you.

For example, if you have a schema called user.jtd.json that looks like this:

{
  "properties": {
    "name": { "type": "string" },
    "created_at": { "type": "timestamp" },
    "favorite_numbers": {
      "elements": { "type": "float64" }
    }
  }
}

Generate code for a single programming language

To create code for a single programming language, run:

# Generate TypeScript into "out/" from user.jtd.json
jtd-codegen --typescript-out=out -- user.jtd.json

This will create a file called out/index.ts that looks like this:

export interface User {
  createdAt: string;
  favoriteNumbers: number[];
  name: string;
}

Each programming language has its own set of options. See jtd-codegen --help and the specific documentation for each programming language for more specifics.

Generate code for multiple programming languages

To create code for multiple programming languages at once, pass flags for each programming language you'd like to generate code for:

# Generate Golang into "go_out/" and Java into "java-out/" from user.jtd.json
jtd-codegen --go-out=go_out --java-out=java-out --java-pkg=com.example.user -- user.jtd.json

This will create two files, called go_out/index.go:

package go_out

import "time"

type User struct {
  CreatedAt time.Time `json:"created_at"`
  FavoriteNumbers []float64 `json:"favorite_numbers"`
  Name string `json:"name"`
}

And another called java-out/User.java:

package com.example.user;

import java.time.OffsetDateTime;

import com.fasterxml.jackson.annotation.JsonProperty;

public class User {
  @JsonProperty("created_at")
  private OffsetDateTime createdAt;

  @JsonProperty("favorite_numbers")
  private List<Double> favoriteNumbers;

  @JsonProperty("name")
  private String name;

  public User() {
  }

  public OffsetDateTime getCreatedAt() {
    return createdAt;
  }

  public void setCreatedAt(OffsetDateTime createdAt) {
    this.createdAt = createdAt;
  }

  public List<Double> getFavoriteNumbers() {
    return favoriteNumbers;
  }

  public void setFavoriteNumbers(List<Double> favoriteNumbers) {
    this.favoriteNumbers = favoriteNumbers;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }
}