Skip to content

jsonschema.md

Latest commit

 

History

History
212 lines (185 loc) · 4.5 KB

jsonschema.md

File metadata and controls

212 lines (185 loc) · 4.5 KB
Raw
sidebar_position 3

JSON Schema

JSON Schema input support enables you to generate TypeScript models directly from JSON Schema documents. This is particularly useful when you have standalone JSON Schema files that define your data structures.

Supported Generators

The JSON Schema input type supports the following generators:

Preset JSON Schema
models ✅
custom ✅

Remote URL inputs

inputPath accepts an http:// or https:// URL. Optional authentication (bearer token, API key, or custom headers) is configured via the auth field. See the configurations guide for examples and the auth scope and security considerations section. Note: JSON Schema input does not resolve external $refs in the loader (Modelina handles refs downstream), so auth headers are only sent to the root URL.

Configuration

Basic Configuration

export default {
  inputType: 'jsonschema',
  inputPath: './user-schema.json',
  language: 'typescript',
  generators: [
    {
      preset: 'models',
      outputPath: './src/models'
    }
  ]
};

Advanced Configuration with Modelina Options

export default {
  inputType: 'jsonschema',
  inputPath: './complex-schema.json',
  language: 'typescript',
  generators: [
    {
      preset: 'models',
      outputPath: './src/models',
      options: {
        modelType: 'class',
        enumType: 'enum',
        mapType: 'record',
        rawPropertyNames: false,
        useJavascriptReservedKeywords: false
      },
      renderers: [
        {
          class: {
            property: ({ content, property }) => {
              return `/** ${property.property.description || 'Auto-generated property'} */\n${content}`;
            }
          }
        }
      ]
    }
  ]
};

Examples

Simple User Schema

Input: user-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["id", "name", "email"]
}

Configuration: codegen.mjs

export default {
  inputType: 'jsonschema',
  inputPath: './user-schema.json',
  language: 'typescript',
  generators: [
    {
      preset: 'models',
      outputPath: './src/models'
    }
  ]
};

Generated Output: src/models/User.ts

export class User {
  private _id: string;
  private _name: string;
  private _email: string;
  private _age?: number;

  constructor(input: {
    id: string,
    name: string,
    email: string,
    age?: number,
  }) {
    this._id = input.id;
    this._name = input.name;
    this._email = input.email;
    this._age = input.age;
  }

  get id(): string { return this._id; }
  get name(): string { return this._name; }
  get email(): string { return this._email; }
  get age(): number | undefined { return this._age; }

  public marshal(): string {
    return JSON.stringify({
      id: this.id,
      name: this.name,
      email: this.email,
      age: this.age,
    });
  }

  public static unmarshal(json: string): User {
    const obj = JSON.parse(json);
    return new User(obj);
  }
}

Complex Schema with Definitions

Input: complex-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "Address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "zipCode": { "type": "string" }
      },
      "required": ["street", "city", "zipCode"]
    }
  },
  "type": "object",
  "properties": {
    "person": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "address": { "$ref": "#/definitions/Address" }
      },
      "required": ["name"]
    }
  }
}

This will generate both Person and Address classes with proper type relationships.

File Format Support

JSON Format

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "example": { "type": "string" }
  }
}

YAML Format

$schema: "http://json-schema.org/draft-07/schema#"
type: object
properties:
  example:
    type: string