Перейти к содержимому
Numio

Конвертировать TypeScript в схему JSON — Numio

Генерирует JSON Schema draft-07 из типов TypeScript с помощью ts-json-schema-generator. Каждый тип помещается в "definitions"; необязательные свойства не попадают в "required", а объекты получают "additionalProperties": false.

Типы запросов и ответов описаны интерфейсами TypeScript, и нужна JSON Schema для валидации через Ajv или для API-шлюза.

TypeScript

JSON Schema

Когда пригодится

  • Типы запросов и ответов описаны интерфейсами TypeScript, и нужна JSON Schema для валидации через Ajv или для API-шлюза.
  • Вы хотите опубликовать схему для конфигурационного файла JSON, структура которого уже описана типом TypeScript.

Как пользоваться

  1. Вставьте интерфейсы TypeScript или псевдонимы типов. Теги JSDoc вроде @minimum, @format или @pattern переносятся в схему.
  2. Исходный код отправляется на /api/typescript-to-json-schema, записывается на сервере во временный файл и обрабатывается с экспозицией всех типов.
  3. Скопируйте JSON Schema. Если во вводе только один тип, корень дополнительно получает $ref на него.

TypeScript

/** A product in the catalog */
export interface Product {
  /** @minimum 0 */
  price: number;
  name: string;
  tags?: string[];
}

JSON Schema (draft-07)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$ref": "#/definitions/Product",
  "definitions": {
    "Product": {
      "type": "object",
      "properties": {
        "price": {
          "type": "number",
          "minimum": 0
        },
        "name": {
          "type": "string"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "price",
        "name"
…

Подробности и ограничения

Страница отправляет ваши данные на серверный маршрут (/api/typescript-to-json-schema) для конвертации; они обрабатываются не только в браузере. API-маршруты Next.js по умолчанию принимают тело запроса размером до 1 МБ.

JSDoc разбирается в расширенном режиме: комментарий-описание становится "description", а теги вроде @minimum 0 или @minLength 1 — ключевыми словами.

Методы в интерфейсах пропускаются. Date становится string с format date-time, а объединения литералов — enum.

bigint не поддерживается и приводит к ошибке "Unknown node". Map и Set описываются своим интерфейсом — объектом только с числовым size, поэтому для JSON-данных используйте Record<string, T> или массивы.

FAQ

Включаются ли неэкспортируемые типы?

Да. Каждый тип из ввода, экспортируемый или нет, добавляется в "definitions", а ссылки между ними используют $ref.

Как представлены необязательные и nullable-свойства?

Необязательные свойства не попадают в "required". Объединение с null становится anyOf с {"type": "null"}.

Почему в корне есть $ref?

При единственном типе генератор указывает на него из корня через $ref. При нескольких типах выводится только "definitions".

Спецификации и справка