Pular para o conteúdo
Numio

Converter TypeScript em JSON Schema — Numio

Gera um JSON Schema draft-07 a partir de tipos TypeScript com ts-json-schema-generator. Todo tipo vai para "definitions"; propriedades opcionais ficam fora de "required" e objetos recebem "additionalProperties": false.

Seus tipos de requisição e resposta são interfaces TypeScript e você precisa de JSON Schema para validação com Ajv ou para um API gateway.

TypeScript

JSON Schema

Quando usar

  • Seus tipos de requisição e resposta são interfaces TypeScript e você precisa de JSON Schema para validação com Ajv ou para um API gateway.
  • Você quer publicar um schema para um arquivo de configuração JSON cujo formato já está definido como um tipo TypeScript.

Como usar

  1. Cole interfaces ou aliases de tipo TypeScript. Tags JSDoc como @minimum, @format ou @pattern são lidas para o schema.
  2. O código-fonte é enviado para /api/typescript-to-json-schema, gravado em um arquivo temporário no servidor e processado com todos os tipos expostos.
  3. Copie o JSON Schema. Se a entrada tiver só um tipo, a raiz também recebe um $ref para ele.

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"
…

Detalhes e limitações

A página envia sua entrada para uma rota do servidor (/api/typescript-to-json-schema) para conversão; ela não é processada apenas no navegador. As rotas de API do Next.js aceitam por padrão corpos de requisição de até 1 MB.

O JSDoc é analisado no modo estendido: um comentário de descrição vira "description", e tags como @minimum 0 ou @minLength 1 viram palavras-chave.

Métodos em interfaces são ignorados. Date vira uma string com format date-time, e uniões de literais viram enum.

bigint não é suportado e retorna um erro "Unknown node". Map e Set são descritos pela sua interface, um objeto só com um size numérico, então use Record<string, T> ou arrays para dados JSON.

FAQ

Tipos não exportados são incluídos?

Sim. Todo tipo da entrada, exportado ou não, é adicionado a "definitions", e as referências entre eles usam $ref.

Como são representadas as propriedades opcionais e anuláveis?

Propriedades opcionais ficam fora de "required". Uma união com null vira anyOf com {"type": "null"}.

Por que há um $ref na raiz?

Com um único tipo, o gerador aponta a raiz para ele com $ref. Com vários tipos, só "definitions" é gerado.

Especificações e referências