openapi-ts-json-schema

openapi-ts-json-schema

Generate TypeScript JSON schema files (.ts modules with as const assertions) from OpenAPI definitions.

TypeScript JSON schemas serve various purposes, including:

• Validate data and infer validated data TS types with the same JSON schema (with any JSON schema validator like Ajv)
• Infer TS type definitions from JSON schemas (with json-schema-to-ts)
• Fastify integration: infer route handlers input types from their schema (with @fastify/type-provider-json-schema-to-ts)

Given an OpenAPI definition file, openapi-ts-json-schema will:

• Resolve external/remote $refs and dereference them with @apidevtools/json-schema-ref-parser
• Optionally inline, import or retain local $refs
• Convert to JSON schema with @openapi-contrib/openapi-schema-to-json-schema and openapi-jsonschema-parameters
• Generate a TypeScript JSON schema file for each definition (.ts files with as const assertion)
• Organizing schemas in a folder structure mirroring the original OpenAPI definition layout.

TypeScript JSON schemas are 100% valid JSON schemas.

Installation

npm i openapi-ts-json-schema -D

Usage

Generate your TypeScript JSON schemas:

import { openapiToTsJsonSchema } from 'openapi-ts-json-schema';

const { outputPath } = await openapiToTsJsonSchema({
  openApiSchema: 'path/to/open-api-specs.yaml',
  definitionPathsToGenerateFrom: ['paths', 'components.schemas'],
});

...and use them in your TS project:

import Ajv from 'ajv';
import type { FromSchema } from 'json-schema-to-ts';
import mySchema from 'path/to/generated/schemas/MyModel.ts';

const ajv = new Ajv();
// Perform data validation and type inference using the same schema
const validate = ajv.compile<FromSchema<typeof mySchema>>(mySchema);
const data: unknown = {};

if (validate(data)) {
  // data gets type inference
  console.log(data.foo);
} else {
  console.log(validate.errors);
}

Options

Property	Type	Description	Default
openApiSchema (required)	string	Path to the OpenApi file (supports yaml and json).	-
definitionPathsToGenerateFrom (required)	string[]	OpenApi definition object paths to generate the JSON schemas from. Only matching paths will be generated. (Supports dot notation: ["components.schemas"]).	-
refHandling	"import" | "inline" | "keep"	"import": generate and import $ref schemas. "inline": inline $ref schemas. "keep": keep $ref values.	"import"
schemaPatcher	(params: { schema: JSONSchema }) => void	Dynamically patch generated JSON schemas. The provided function will be invoked against every single JSON schema node.	-
outputPath	string	Path where the generated schemas will be saved. Defaults to /schemas-autogenerated in same directory as provided openApiSchema.	-
plugins	ReturnType<Plugin>[]	A set of optional plugin to generate any extra custom. See plugins docs. output.	-
silent	boolean	Don't console.log user messages.	false

Notes

Take a look at the Developer's notes for a few more in-depth explanations.

$refs handling

openapi-ts-json-schema provides 3 refHandling strategies for OpenAPI $ref properties:

refHandling option
inline	Replaces $refs with inline copies of the target definition, creating self-contained schemas with potential redundancy
import	Replaces $refs with a local variable pointing to the module of the target $ref definition
keep	Retains $refs values without modification

Circular $refs

Circular $refs references are supported, too:

refHandling option
inline	Nested circular references are substituted with {}
import	Completely resolves the JSON schema tree. However, the TypeScript engine will halt type recursion and assign the schema type as any, resulting in error ts(7022)
keep	Does not resolve circular references by definition

For further details, refer to the relevant tests.

Return values

Beside generating the expected schema files under outputPath, openapiToTsJsonSchema returns the following meta data:

{
  // The path where the schemas are generated
  outputPath: string;
  metaData: {
    // Meta data of the generated schemas
    schemas: Map<
      // OpenAPI ref. Eg: "#/components/schemas/MySchema"
      string,
      {
        id: string;
        // JSON schema Compound Schema Document `$id`. Eg: `"/components/schemas/MySchema"`
        uniqueName: string;
        // Unique JavaScript identifier used as import name. Eg: `"componentsSchemasMySchema"`
        originalSchema: JSONSchema | string;
        // Original dereferenced JSON schema
        isRef: boolean;
        // True if schemas is used as a `$ref`

        absoluteDirName: string;
        // Absolute path pointing to schema folder (posix or win32). Eg: `"Users/username/output/path/components/schemas"`
        absolutePath: string;
        // Absolute path pointing to schema file (posix or win32). Eg: `"Users/username/output/path/components/schemas/MySchema.ts"`
        absoluteImportPath: string;
        // Absolute import path (posix or win32, without extension). Eg: `"Users/username/output/path/components/schemas/MySchema"`
      }
    >;
  }
}

Plugins

Plugins are intended as a way to generate extra artifacts based on the same internal metadata created to generate the JSON schema output.

openapi-ts-json-schema currently ships with one plugin specifically designed to better integrate with Fastify, but you can write your own!

Read plugins documentation 📖.

Todo

• Consider removing required definitionPathsToGenerateFrom option in favour of exporting the whole OpenAPI definitions based on the structure defined in specs
• Improve external #refs handling (currently being inlined and duplicated)
• Find a way to merge multiple different OpenApi definitions consistently
• Consider adding a way to customize the values of the generated JSON schema ids. This could be beneficial even in case of multiple schemas being merged with plugins
• Consider implementing an option to inline circular $refs with a configurable nesting level

Changelog

0.9.0

Minor Changes

• 06b8d4f: Use _ as path separator to support Windows OS
• a8b4e24: Metadata props renamed (see documentation)
• a418ecb: PluginInput['makeRelativePath'] type renamed to PluginInput['makeRelativeModulePath']
• a418ecb: Support Windows OS
• 8ce3621: Merge operation and path level path parameters
• a418ecb: schemaFileName metadata prop removed

Patch Changes

• 7461657: Convert inlined definitions in other places then components prop