jsoncodegen

JSON code generator CLI.

Takes a folder of JSON type declarations, and generates POJOs / TypeScript interfaces / Kotlin data classes. You can also write your own generator.

Input (MyObject.json):

{
  "name": "string",
  "flag": "boolean",
  "count": "number",
  "arrayOfStrings": "string[]",
  "mapStringToNumber": "number{}",
  "myOtherObject": "./MyOtherObject"
}

Output (MyObject.ts):

import { MyOtherObject as __type___MyOtherObject } from "./MyOtherObject"

export interface MyObject {
  readonly name: string
  readonly flag: boolean
  readonly count: number
  readonly arrayOfStrings: readonly string[]
  readonly mapStringToNumber: { readonly [key: string]: number }
  readonly myOtherObject: __type___MyOtherObject
}

Output (MyObject.kt):

package com.example

data class JsonInterfaceMixedTest(
  val name: String,
  val flag: Boolean,
  val count: Double,
  val arrayOfStrings: List<String>,
  val mapStringToNumber: Map<String, Double>,
  val myOtherObject: com.example.MyOtherObject
) {
}

Output (MyObject.java):

package com.example;

// ... imports

public final class MyObject {
  private final String name;
  private final Boolean flag;
  private final Double count;
  private final java.util.List<String> arrayOfStrings;
  private final java.util.Map<String, Double> mapStringToNumber;
  private final com.example.MyOtherObject myOtherObject;
  
  public JsonInterfaceMixedTest(Builder<...> builder) {
    Validate.notNull(builder.name, "Argument 'name' must not be null.");
    // ...
    this.name = builder.name;
  }
  // ... hashCode, equals, toString, Builder, etc.
}

Install

Install the CLI

npm i -D jsoncodegen

Install one or more generators

TypeScript:

npm i -D jsoncodegen-generator-typescript

Kotlin:

npm i -D jsoncodegen-generator-kotlin-jackson

Java Jackson:

npm i -D jsoncodegen-generator-java-jackson

PHP (Psalm):

npm i -D jsoncodegen-generator-php-psalm

Use

Warning: The output directory will be deleted. Back up your project.

./node_modules/.bin/jsoncodegen --generator typescript --inputDir src --outputDir build

Please note that the --generator option accepts only the end ("FOO") of "jsoncodegen-generator-FOO".

Options

| Long | Short | Meaning | |---|---|---| | --generator | -g | Generator to use: the FOO of jsoncodegen-generator-FOO, or a path to a generator package | | --inputDir | -i | Directory to read JSON declarations from | | --outputDir | -o | Directory to write generated code into — deleted before every run | | --config | -c | Path to a JS config module for the generator |

A --generator value containing / or \ (or a bare .) is treated as a path to a generator package rather than a package name. The path is resolved against the current working directory, and its package.json main is imported — this is how a generator repository tests itself with -g ..

The .js extension on --config is optional; it is appended if missing, which is why some scripts write -c test-project/jsoncodegen.config.

Because the output directory is deleted on every run, point it at a folder that holds nothing else — a dedicated generated/, json/ or Generated/ subdirectory. Never point it at a directory containing hand-written files.

Syntax

Every .json file under the input directory declares exactly one named type. The file's path relative to the input directory, minus .json, is its id: parent/tests/Person.json has the id parent/tests/Person, the directory path parent/tests and the name Person.

Interface

Put each interface in its own file. The file name will be the name of the interface. Start the name with a capital letter to match the TS / Java / Kotlin convention.

You can nest interfaces in folders. Folder names must not be reserved keywords in the target language. Prefer all lowercase names for folders, as they will become packages in Java / Kotlin.

When naming folders / files / properties, avoid using special characters, spaces and hyphens. Also, names starting and ending with double underscores (ex. __RESERVED__) are reserved for generator use.

An interface is expressed as an object in a JSON file:

{
  ".is": "interface"
}

".is": "interface" is optional. An object means an interface by default.

The interface can have a description. This will become a comment in the output.

{
  ".description": "A person."
}

You can declare properties like this:

{
  "name": "string"
}

Property names starting and ending with double underscores (ex. "__RESERVED__") are reserved.

Property names starting with a period (ex. ".is": "interface") are metadata and will not become properties.

An empty object ({}) is a valid, empty interface.

Property types

A property type is a base type followed by any number of ?, [] and {} suffixes.

String: "string"

Boolean: "boolean"

Number: "number"

Array: "string[]" or "boolean[]" or "number[]", etc.

Map: "string{}" or "boolean{}" or "number{}", etc.

Map keys are always strings, as required by JSON.

Interface: "com/example/MyOtherObject" or "./MyOtherObject"

Enum: "com/example/MyEnum" or "./MyEnum"

Enum value: "com/example/City.Budapest" or "./City.Budapest"

Reference paths

Paths use / as the separator. A path starting with . ("./Person", "../Person") is resolved relative to the folder of the declaring file. Any other path ("parent/tests/Person") is absolute, from the root of the input directory. From inside parent/tests/, both of those examples refer to the same type.

The enum value form splits on the last . of the base name, so "./CityID.Budapest" means the Budapest value of the CityID enum. Type names must therefore not contain dots.

Null

Types are not nullable by default.

Types can be made nullable by adding a question mark (?) after them. Example:

{
  "requiredFlag": "boolean",
  "optionalFlag": "boolean?"
}

In this example, "requiredFlag" must always be provided.

On the other hand, "optionalFlag" is optional. It can be boolean or it can be null, or it can be omitted entirely.

It is also possible to make an array (or map) required, but its values nullable. Like this:

{
  "arrayOfNumbersAndNulls": "number?[]"
}

Or the opposite:

{
  "optionalArrayOfNumbers": "number[]?"
}

Or both:

{
  "optionalArrayOfNumbersAndNulls": "number?[]?"
}

A note on undefined: JavaScript will return undefined when a nullable value is omitted. However, there is no undefined in JSON. It also does not exist in Java or Kotlin. Therefore this tool does not differentiate between null and undefined.

Reading a type string

Suffixes are applied left to right, each wrapping whatever came before it. Read them outward-in: "number?[]?" is number? (a nullable number), then [] (an array of those), then ? (and the array itself is nullable) — an optional array whose elements may be null.

| Type string | Meaning | |---|---| | "boolean" | required boolean | | "boolean?" | boolean, or null / omitted | | "string[]" | required array of strings | | "string[]?" | optional array of strings | | "string?[]" | required array, elements may be null | | "string?[]?" | optional array, elements may be null | | "number{}" | map of string to number | | "number{}{}" | map of string to (map of string to number) | | "boolean{}[]" | array of maps of booleans | | "boolean[]{}" | map of arrays of booleans | | "./Person[]" | array of Person | | "./CityID.Budapest" | exactly the Budapest value of CityID |

There is no depth limit, and arrays and maps may nest in any combination.

Property description

You can add a description for a single property like this:

{
  "name": ["string", "The full name of this person."]
}

Mixins

Mixins can be used to define common properties. To define a mixin, put it in a JSON file:

PersonMixin.json

{
  ".is": "mixin",
  ".description": "Common person properties.",
  
  "id": "string",
  "source": "string"
}

Then reference it in the target interface:

Person.json

{
  ".is": "interface",
  ".description": "A person.",
  "...": ["./PersonMixin"],
  
  "name": "string"
}

The properties of the mixin will be merged with the properties of the interface. Multiple mixins may be provided in the "..." array.

"..." also accepts a single path string instead of an array. Mixin paths resolve exactly like property type references — a leading . makes them relative.

Merging goes mixins first, in the order listed, then the properties of the file itself. So a later mixin overrides an earlier one, and the interface's own property overrides both. Property order in the output follows first appearance.

A mixin is never emitted as a type of its own; it only contributes properties. Mixins may also be used in enums, to contribute values, and a mixin may itself use "...".

There is no inheritance. Mixins are the only composition mechanism, and they are a pure copy-in: two interfaces sharing a mixin have no type relationship in the generated code.

Enums

Enums come in two flavors: string enums and number enums.

{
  ".is": "enum",
  ".description": "This is a number enum.",

  "Zero": 0,
  "One": [1, "The number one."],
  "Pi": 3.14
}

{
  ".is": "enum",
  ".description": "This is a string enum.",

  "Boston": "Boston",
  "Budapest": ["Budapest", "The capital of Hungary."]
}

Enum types must not be mixed.

The key is the name of the value and the value is its value. Empty string values are allowed. Value names must not contain whitespace. ".is": "enum" is required — unlike interfaces, enums are never the default.

Interfaces can refer to the enum, or to a specific value in the enum:

{
  ".is": "interface",
  ".description": "The city of Budapest.",
  
  "id": "./CityID.Budapest",
  "sisterCityId": "./CityID"
}

In the example above, the "sisterCityId" property can take any city ID.

On the other hand, the "id" property can only contain a single specific city ID. This pattern can be used to make sure each city gets its own unique ID.

Generators can provide assistance with enum value properties, generating a factory or making sure the value cannot be changed or identifying the correct city interface by ID.

Give one interface per enum value a property of that value's type, and you have a discriminated union — the TypeScript generator turns exactly this into a THas_cityId union type, and fills the property in for you in the factory.

Configure

You can configure the generator by providing a JavaScript file in the --config parameter. Example:

jsoncodegen-generator-typescript.config.js

export default {
  // options
}

jsoncodegen --generator typescript --inputDir src --outputDir build --config jsoncodegen-generator-typescript.config.js

For available options, please check the documentation of the generator.

The config file is loaded as a module, so its format follows the "type" field of the package that contains it: export default {...} when that package is "type": "module", module.exports = {...} otherwise.

Generator options at a glance

| Generator | Options | |---|---| | jsoncodegen-generator-typescript | isMutable, importFileExtension, noTypeImports | | jsoncodegen-generator-php-psalm | namespaceBase (required) | | jsoncodegen-generator-java-jackson | package | | jsoncodegen-generator-kotlin-jackson | package |

importFileExtension is the one that catches people out. Use '.js' for a Node ESM consumer and '' (the default) for a bundler-based frontend; the wrong choice fails at import resolution rather than at generate time. A schema feeding both keeps two config files and runs the TypeScript generator twice.

What the generators emit

TypeScript

• __type__/ mirrors the input tree: an export interface per interface, a real export enum per enum. Cross-references are imported under an alias derived from the absolute path, so same-named types in different folders never collide.
• __factory__/ has a make<Name>(props) per interface. Prefer these over object literals — they enforce exact type checks and fill in enum value properties for you.
• __union_type__/ appears only when some interface has an enum value property. It contains a THas_<propertyName> union per such property, which narrows on switch.
• __assert__/ has an assert<Name>(value) per type: a TypeScript assertion function that throws AssertionError naming the offending path. Use it at trust boundaries.
• __assert_utility__/ is support code for the above.

PHP (Psalm)

• Type/ — a final class per interface, folders becoming sub-namespaces. Enums are abstract classes with const values plus a @psalm-type union, so the output works from PHP 5.6 through 8.4.
• Builder/ — a <Name>Builder per interface, ensuring required fields get set.
• Assert/ — AssertMyObject::assert($value), throwing on mismatch and normalizing maps into JsonMap.
• Util/ — JsonMap<T>, an immutable string-keyed map that always serializes as a JSON object rather than an array.

namespaceBase is required, and the generator does not create the directories to match it — the output directory must already sit where your PSR-4 autoloader expects that namespace.

Java (Jackson)

A final class per interface with private final fields, hashCode / equals / toString, Jackson annotations, and a nested Builder. The builder is generic over __HAS_<field>__ phantom type parameters, so a missing required field is a compile error rather than a runtime one. Enums become Java enums with @JsonValue. Requires jackson-annotations and commons-lang on the classpath.

Kotlin (Jackson)

A data class per interface and an enum class per enum, one file per type, folders becoming sub-packages. There are no builders or asserts — constructors and Kotlin's null-safety carry that weight. Nullable properties are emitted as ? = null so they can be omitted at the call site:

val myObject = MyObject(name = "Budapest", flag = true, count = 3.0)

number maps to Double, never Int — every JSON number is a Double, including in number enums. Number enums also get a companion object with a @JsonCreator fun fromValue() that throws IllegalArgumentException on an unknown value.

This generator enforces reserved words rather than merely advising them: a Kotlin keyword used as a folder name fails the run with [q1c0ei]. That makes it the strictest of the four on folder naming, so a schema shared with Kotlin constrains every other target too.

When consuming the output, use com.fasterxml.jackson.module.kotlin.jacksonObjectMapper() rather than a plain ObjectMapper, or the data classes will not deserialize correctly.

Set up a project

The usual arrangement is one dedicated schema package that owns the declarations and every generate script. Consumers do not depend on jsoncodegen at all; they simply contain a generated folder.

my-product/
  my-product-json/            ← schema package: declarations + scripts
    src/                      ← the .json declarations (--inputDir)
    jsoncodegen-generator-typescript.config.js
    jsoncodegen-generator-php-psalm.config.js
    package.json
  my-product-webapp/
    src/json/                 ← generated, deleted and rewritten on each run
  my-product-server/
    src/Json/Generated/       ← generated

There are two reasons for the separate package. The output directory is deleted on every run, so it has to be a folder nothing else writes to; and one input directory usually fans out to several languages and several applications, which wants a single place to run from.

my-product-json/package.json

{
  "type": "module",
  "private": true,
  "scripts": {
    "json": "npm i --no-audit --no-fund && run-p json-webapp json-server",
    "json-webapp": "jsoncodegen --generator typescript --config jsoncodegen-generator-typescript.config.js --inputDir src --outputDir ../my-product-webapp/src/json",
    "json-server": "jsoncodegen --generator php-psalm --config jsoncodegen-generator-php-psalm.config.js --inputDir src --outputDir ../my-product-server/src/Json/Generated"
  },
  "devDependencies": {
    "jsoncodegen": "^1.1.1",
    "jsoncodegen-generator-typescript": "^1.2.0",
    "jsoncodegen-generator-php-psalm": "^4.0.0",
    "npm-run-all": "^4.1.5"
  }
}

A few things that are worth doing this way:

• Keep one aggregate script that fans out to the per-target sub-scripts with run-p or run-s from npm-run-all, and run that rather than a sub-script. Running one target on its own leaves the other consumers stale against the same schema, which is the easiest mistake to make here.
• Install before generating in the aggregate script, so that someone pulling a schema change that also bumps a generator gets the right generator automatically.
• Prefer the long option names in scripts. They are read far more often than they are typed.

Working on the schema

1. Edit or add .json files in the schema package's input directory.
2. Run the aggregate script.
3. Build every consumer. A removed or renamed property surfaces as a compile error there — jsoncodegen itself will generate it away without complaint.
4. Commit the schema and the regenerated output together, so the tree stays self-consistent.

Renames and removals deserve care. A renamed property is a silent remove-plus-add: every consumer reading the old name breaks, and any stored JSON using the old name stops validating against the generated asserts. If a change touches persisted or over-the-wire data, add the new property as nullable, migrate, and remove the old one later.

Do not hand-edit generated code; it will not survive the next run. Anything that is not derived from the schema belongs beside the generated folder, not inside it.

Versions

The CLI, each generator, and jsoncodegen-types-for-generator are versioned independently. A generator major changes the emitted code, so bumping one is a code-affecting change: bump it deliberately, regenerate, and build every consumer in the same commit. Pin with ^ in the schema package and let its lockfile be the record of what a given schema state generates.

Write your own generator

The --generator option also accepts a relative path to a JS file. Example:

jsoncodegen --generator ./my-generator.js --inputDir src --outputDir build

Have a look at https://github.com/jsoncodegen/types-for-generator to get an idea about the expected shape of a generator. You can install the types like this:

npm i -D jsoncodegen-types-for-generator

Generators should implement the IGenerator interface:

import { IGenerator, IGeneratorResult } from 'jsoncodegen-types-for-generator'

interface IConfig {
  // ... any configuration
}

export const generator: IGenerator = {
  async generate(config: IConfig, namedTypesById) {
    let result: IGeneratorResult[] = []
    for (const namedType of namedTypesById.values()) {
      switch (namedType.kind) {
        case 'Interface':
        case 'NumberEnum':
        case 'StringEnum':
          result.push({
            filePath: [
              ...namedType.directoryPath,
              namedType.name + '.java',
            ],
            content: '...',
          })
          break
      }
    }
    return result
  },
}

The export must be named generator. The CLI reads exactly that name off the imported module, so module.exports = generator will not be found — under Node's ESM interop it arrives as default. CommonJS is otherwise fine: exports.generator is picked up through await import().

Also, https://github.com/jsoncodegen/test-json has sample JSON you can use to test the output of your generator. You can install the sample JSON like this:

npm i -D jsoncodegen-test-json

It exercises every suffix combination, all five reference kinds, and cross-folder references in every direction, so it is a good corpus to generate from while developing:

jsoncodegen -i node_modules/jsoncodegen-test-json/dist -o test-project/src/generated -g . -c test-project/jsoncodegen.config

It is worth compiling that generated output in the real toolchain (tsc, psalm, mvn) as a second script. Unit tests over emitted strings do not catch code that fails to compile.

What a generator receives

generate is called with the config module's default export (or {} if there is no --config) and a Map of every named type, keyed by id — parent/tests/Person. Mixins do not appear: they have already been merged into the types that use them.

Each entry is an IInterface, IStringEnum or INumberEnum, discriminated by kind, and carries id, directoryPath, name and description. Switch on kind and ignore anything you do not recognize, so that a future kind does not break the generator.

Each interface property has a fieldType drawn from a union of eight kinds: PrimitiveValue, Array, Map, InterfaceReference, StringEnumReference, NumberEnumReference, StringEnumValueReference and NumberEnumValueReference. All of them carry isNullable.

Array and Map wrap another field type and nest arbitrarily, so recurse rather than assuming a single level: "boolean?{}?[]?" arrives as a nullable array of a nullable map of a nullable boolean.

The five reference kinds carry both an absoluteDirectoryPath (from the input root) and a relativeDirectoryPath (from the folder of the referencing type), plus a targetId you can look up in the map. Use the relative path for languages with relative imports, and the absolute path for package or namespace based languages — and for building collision-proof local aliases. Note that the relative path is only the right base when you emit a mirror of the input tree; a generator writing into subfolders has to compute its own way back to the root.

Returning results

Return one IGeneratorResult, or an array of them:

{
  filePath: ['some', 'folder', 'MyObject.ts'],  // segments, relative to --outputDir
  content: '...'
}

filePath is an array of path segments, not a string. An empty path, a path escaping the output directory, a non-string content, or two results claiming the same path are all rejected.

Troubleshooting

Errors carry a short code. Grep the source for it to find the exact throw site.

| Message | Cause | |---|---| | [q2cmbl] Type declaration not found: X (at Y) | A property type points at something that is not there. Paths are /-separated and absolute from the input directory root unless they start with . | | [q10dwq] Missing mixin: X | The mixin path does not resolve | | [q10e0h] Invalid mixin: X | The target exists but does not declare ".is": "mixin" | | [q0wxy5] Mixed enum type | One enum has both string and number values | | [q0wz2h] Unknown type: X | ".is" is not interface, enum or mixin | | [q163nh] White space in property name | Exactly that; the same applies to enum value names | | [q0wuct] Generator attempted to overwrite path | Two named types collide in the output | | [q1bep7] Empty file path | A generator returned a result with no filePath segments | | [q0x2cw] Invalid output path | A generator tried to write outside --outputDir | | [s7pzwk] / [s7pzxj] then [q1864g] Generator not found | The generator package is missing, the -g name has a typo, or the package exposes no generator named export |

Note that a failed run has already emptied the output directory, since that happens first. Fix the cause and re-run rather than trying to restore it.

Licence

MIT

Version history

1.1.0 require → import

1.0.0 Initial version.