Skip to Content
📖 Guide DocumentsEnhanced JSONJSON Schema

typia.json.schemas — emit JSON Schema / OpenAPI from a TypeScript type

If you’ve ever hand-written a JSON Schema or an OpenAPI components block, you know how mechanical it is. typia generates it from the TypeScript type at compile time. Same model as the validators — no extra schema file to maintain.

signatures
namespace json {
  function schema<T, Version extends "3.0" | "3.1" = "3.1">(): IJsonSchemaUnit<Version, T>;
  function schemas<Schemas extends unknown[], Version extends "3.0" | "3.1" = "3.1">(): IJsonSchemaCollection<Version, Schemas>;
  function application<Class extends object, Version extends "3.0" | "3.1" = "3.1">(): IJsonSchemaApplication<Version, Class>;
}
FunctionUse case
json.schema<T>()A single top-level schema, plus a components map for any $refs the type pulls in
json.schemas<[T1, T2, ...]>()Multiple top-level types sharing one components map (the common case for an OpenAPI components.schemas)
json.application<Class>()Class methods → a list of {name, parameters, output} JSON Schemas — handy for framework-neutral tooling that wants per-method schemas without typia’s LLM-specific config

In json.application, each parameter’s required flag follows its selected TypeScript signature. A question token or default initializer permits omission, including a default before a later required parameter; that later argument still must be provided. A required public overload or contextual function type remains required even when its implementation has a default. Return schemas use the inferred return type as well as explicit annotations.

For the LLM-specific shape (with $defs, additionalProperties: false, strict mode, …), use typia.llm.parameters or typia.llm.application instead.

Version selects the JSON Schema dialect:

  • "3.1" (default) — OpenAPI 3.1, which is JSON Schema 2020-12. Supports tuples, pattern properties, null as a primitive.
  • "3.0" — OpenAPI 3.0 / Swagger compatibility. No tuples, no pattern properties.

Stick with "3.1" unless a downstream consumer demands the older dialect.

First example

hello-schemas.ts
import typia, { tags } from "typia";
 
interface User {
  id: string & tags.Format<"uuid">;
  age: number & tags.Type<"uint32">;
  email?: string & tags.Format<"email">;
}
 
const schemas = typia.json.schemas<[User]>();
// → an IJsonSchemaCollection with `User` under components.schemas

The output is a plain object. Use it directly with typia and @typia/utils, hand it to ajv when your JSON Schema consumer accepts typia’s emended shape, or save it to disk for tooling that wants schemas at rest.

When index-signature values are combined into a schema, their template-literal alternatives remain in the resulting value union.

When validating a schema with @typia/utils’s OpenApiValidator, supported string formats apply their registered checks. Unknown format names are annotations and impose no format check; string type, pattern and length constraints still apply. This also holds for custom names such as constructor or __proto__.

typia.json.schema, typia.json.schemas, and typia.json.application return typia’s emended schema representation. It is designed for typia and @typia/utils converters first, not for direct assignment to every third-party OpenAPI SchemaObject type. When a tool expects raw OpenAPI 3.1 schemas, convert the components with OpenApiConverter.downgradeComponents:

openapi-components.ts
import typia from "typia";
import { OpenApiConverter } from "@typia/utils";
 
const collection = typia.json.schemas<[User]>();
const components = OpenApiConverter.downgradeComponents(
  collection.components,
  "3.1",
);
 
// Use components.schemas in an OpenAPI 3.1 document or plugin option.

This matters for schema-level examples: typia keeps tags.Examples<T> as named examples in the emended schema, while OpenAPI 3.1’s Schema Object uses JSON Schema’s array-shaped examples keyword. The converter drops the names and emits the raw OpenAPI form.

The same boundary applies to tags.Format<"byte">. Typia keeps format: "byte" in its emended schema, OpenAPI 3.0 output retains that spelling, and raw OpenAPI 3.1 output uses contentEncoding: "base64". An explicitly supplied tags.ContentMediaType<...> is retained in the OpenAPI 3.1 Schema Object; typia does not invent a media type when none was declared.

For tuples, raw OpenAPI 3.1 uses prefixItems for positional schemas and items for the remaining elements. The converter writes typia’s emended rest constraint into items and preserves the required prefix length through minItems. When upgrading a raw schema, items: true or omitted items permits unconstrained elements, while items: false forbids them; without a prefix, false permits only an empty array, subject to the schema’s length bounds.

Swagger 2 document conversion

For Swagger 2 documents, OpenApiConverter.upgradeDocument composes each server URL from schemes, host, and basePath and rejects endpoint fields containing queries or fragments. Equivalent host casing and root URL spellings with and without a trailing slash normalize to one Swagger endpoint. An operation’s schemes, consumes, and produces override the document defaults; when neither media list is present, the converter uses application/json for compatibility. An explicit empty media list clears the inherited default, but it cannot accompany a body or response payload because the emended content model has no media key under which to retain that schema or example. Swagger formData parameters become one object-shaped request body; scalar enums, nullable scalar or array fields, and recursively nested arrays of those scalar shapes remain simple form fields. File-field validation metadata and x-* extensions remain on the binary property schema, and response examples remain associated with their MIME types.

OpenApiConverter.downgradeDocument(document, "2.0") keeps media types on each operation instead of guessing shared document defaults. Schema constants become typed Swagger enums, and supported annotations on individual constant branches, including nullable branches and their default: null, survive a downgrade and re-upgrade. An empty response content map normalizes to a response without a payload. Swagger 2 can express only one host and base path and one schema shared by a response’s media types, so the converter throws a TypeError when server descriptions, variables, credentials, unsupported schemes, different authorities or paths, streaming item schemas, encrypted bodies or responses, request bodies without at least one defined media type and schema, non-empty response media without a schema or example, mixed form and non-form request media, forms without a defined field, aggregate form-object constraints, non-simple form fields, mismatched form-body and field requiredness, media-specific schemas, or named examples would otherwise be lost. File form fields support both multipart/form-data and application/x-www-form-urlencoded, as defined by Swagger 2. Response examples may still differ by MIME type because Swagger represents them as a keyed map.

examples/src/json/schemas.ts
import typia, { tags } from "typia";
 
export const MemberSchema = typia.json.schemas<[IMember], "3.0">();
 
interface IMember {
  /** Unique user ID generated by server. */
  id: string & tags.Format<"uuid">;
 
  /** Email address of the member. */
  email: string & tags.Format<"email">;
 
  /**
   * Age of the member.
   *
   * For reference, only adult can be a member.
   */
  age: number &
    tags.Type<"uint32"> &
    tags.ExclusiveMinimum<19> &
    tags.Maximum<100>;
}

undefined

export namespace json {
  export function schemas<
    Schemas extends unknown[],
    Version extends "3.0" | "3.1" = "3.1",
  >(): IJsonSchemaCollection<Version>;
}

What gets included

Anything you express in the TypeScript type carries over:

  • tags.Format<"uuid"> → "format": "uuid"
  • tags.MaxLength<100> → "maxLength": 100
  • tags.Minimum<0> → "minimum": 0
  • JSDoc description on a property → "description": "..."

A few JSON-Schema-only comment tags are also recognized — they don’t affect runtime validation but they show up in the emitted schema:

TagEffect
@title SomethingSets title
@deprecatedSets deprecated: true
@hidden / @internalExcludes the field from the emitted schema
examples/src/json/schemas-comment-tags.ts
import typia, { tags } from "typia";
 
export const SpecialCommentTagSchema = typia.json.schemas<[Special], "3.1">();
 
interface Special {
  /**
   * Deprecated tags are just used for marking.
   *
   * @deprecated
   *
   * @title Unsigned integer
   */
  type: number & tags.Type<"int32">;
 
  /**
   * Internal tagged property never be shown in JSON schema.
   *
   * It even doesn't be shown in other `typia` functions like `assert<T>()`.
   *
   * @internal
   */
  internal: number[];
 
  /**
   * Hidden tagged property never be shown in JSON schema.
   *
   * However, it would be shown in other `typia` functions like
   * `stringify<T>()`.
   *
   * @ignore
   */
  hidden: boolean;
 
  /**
   * You can limit the range of number.
   *
   * @exclusiveMinimum 19
   *
   * @maximum 100
   */
  number?: number;
 
  /**
   * You can limit the length of string.
   *
   * Also, multiple range conditions are also possible.
   */
  string: string &
    (
      | (tags.MinLength<3> & tags.MaxLength<24>)
      | (tags.MinLength<40> & tags.MaxLength<100>)
    );
 
  /**
   * You can limit the pattern of string.
   *
   * @pattern ^[a-z]+$
   */
  pattern: string;
 
  /**
   * You can limit the format of string.
   *
   * @format date-time
   */
  format: string | null;
 
  /** In the Array case, possible to restrict its elements. */
  array: Array<string & tags.Format<"uuid">> & tags.MinItems<3>;
}

Custom fields

OpenAPI-style schema consumers commonly use the x-* prefix for non-standard extensions. To embed x-* properties (for vendor-specific tooling, internal flags, anything that isn’t part of the standard), use tags.TagBase.schema or the tags.JsonSchemaPlugin helper:

examples/src/json/schemas-type-tags.ts
import typia, { tags } from "typia";
 
export const SpecialTypeTagSchema = typia.json.schemas<[IAccount]>();
 
type Monetary<Value extends string> = tags.TagBase<{
  target: "number";
  kind: "monetary";
  value: Value;
  schema: {
    "x-monetary": Value;
  };
}>;
 
type Placeholder<Value extends string> = tags.JsonSchemaPlugin<{
  "x-placeholder": Value;
}>;
 
interface IAccount {
  code: string & Placeholder<"Write your account code please">;
  balance: number & Monetary<"dollar">;
}

For standard schema keywords that TypeScript cannot infer, such as OpenAPI 3.1 / JSON Schema patternProperties, use the same escape hatch when the annotation is only for schema consumers:

import typia, { tags } from "typia";
 
type XHeaders = Record<string, string> &
  tags.JsonSchemaPlugin<{
    patternProperties: {
      "^x-": { type: "string" };
    };
    additionalProperties: false;
  }>;
 
typia.json.schema<XHeaders>();

JsonSchemaPlugin is schema-only metadata. It does not change validator behavior; if runtime validation must reject keys outside the pattern, encode that rule with a validating custom tags.TagBase or validate the keys separately.

Restrictions

bigint is rejected

JSON Schema has no bigint. typia refuses to compile a schema for a type that contains one:

json.schemas.ts
import typia, { tags } from "typia";
 
interface Something {
  bigint: bigint;
  array: bigint[];
  nested: Nested;
}
interface Nested {
  uint64: bigint & tags.Type<"uint64">;
}
 
typia.json.schemas<[Something]>();

Native classes — only Date is allowed

Map, Set, Uint8Array, … are rejected. Date is special-cased: it serializes as string & tags.Format<"date-time">, so typia accepts it.

json.schemas.native.ts
import typia from "typia";
 
interface Native {
  date: Date;
}
typia.json.schemas<[Native]>();

Where to go next

Last updated on
Special Tagsstringify() functions