ajsc - Another JSON Schema Parser

ajsc is an npm package that transforms JSON Schema definitions into an intermediate representation (IR) called IRNode. This intermediate form is designed to be consumed by language-specific converters—such as the built-in TypeScript converter—or by any custom converter you create for languages like Kotlin or Swift. This library streamlines the process of converting API JSON Schema definitions into strong-typed code representations, ensuring consistency between your API contracts and client implementations.

Features

• Comprehensive Schema Parsing:
  Convert JSON Schema types including strings, numbers, booleans, nulls, literals, enums, unions, intersections, arrays, and objects into a unified IR.

• Intermediate Representation (IRNode):
  The IRNode provides a standard structure that captures type, constraints, and path information. This representation is ideal for further transformation into various target languages.

• Plugin-Based Architecture:
  Use the provided language plugin (currently, a TypeScript converter) or write your own converter to support additional languages such as Kotlin or Swift.

• $defs and References Handling:
  Resolve JSON Schema definitions ($defs) and references ($ref) seamlessly, ensuring reusable schema components are properly processed.

• Unique Signature Tracking:
  For objects and arrays, the library tracks unique signatures to avoid duplicate type definitions when converting to code.

Installation

Install ajsc via npm:

npm install ajsc

Usage

Basic Conversion to IRNode

The primary function of ajsc is to convert a JSON Schema into an IRNode. Here’s an example of converting a simple JSON Schema that defines a string type:

import { JSONSchemaConverter } from "ajsc";

const schema = { type: "string" };
const converter = new JSONSchemaConverter(schema);

console.log(converter.irNode);
// Output:
// {
//   type: "string",
//   constraints: {},
//   path: "",
// }

Converting Complex Schemas You can also convert more complex schemas including objects, arrays, unions, intersections, and even schemas with $defs:

import { JSONSchemaConverter } from "ajsc";

const complexSchema = {
  $defs: {
    Person: {
      type: "object",
      properties: {
        name: { type: "string" },
        age: { type: "number" },
      },
      required: ["name"],
    },
  },
  type: "object",
  properties: {
    person: { $ref: "#/$defs/Person" },
  },
};

const converter = new JSONSchemaConverter(complexSchema);
console.log(converter.irNode);

API Reference

JSONSchemaConverter

• Constructor: new JSONSchemaConverter(schema: object)
• Properties:
  • irNode: The resulting intermediate representation of the JSON Schema.
• Supported Schema Types:
  • Primitive Types: string, number, boolean, null
  • Literals: Using the const keyword.
  • Enums: Using the enum property.
  • Unions: When type is an array (e.g., ["string", "number"]).
  • Intersections: Using allOf to combine multiple schemas.
  • Arrays: With type: "array" and an items schema.
  • Objects: With type: "object" and a properties definition.
  • $defs and $ref: For defining and referencing reusable schema parts.

TypescriptConverter

The package includes a TypeScript language plugin that converts the IRNode into TypeScript type definitions.

• Constructor: new TypescriptConverter(schema: object, options?: { inlineTypes?: boolean })
• Properties:
  • code: A string containing the generated TypeScript code.

Usage Example:

import { TypescriptConverter } from "ajsc";

const schema = {
  type: "object",
  properties: {
    name: { type: "string" },
    age: { type: "number" },
    contacts: {
      type: "array",
      items: {
        type: "object",
        properties: {
          email: { type: "string" },
        },
        required: ["email"],
      },
    },
    profile: {
      type: "object",
      properties: {
        email: { type: "string" },
      },
      required: ["email"],
    },
  },
  required: ["name", "age"],
};

const tsConverter = new TypescriptConverter(schema, { inlineTypes: true });
console.log(tsConverter.code);

// Expected output (formatted):
// {
//   name: string;
//   age: number;
//   contacts?: Array<{ email: string; }>;
//   profile?: { email: string; };
// }