Como escrever seu primeiro TOON Schema: guia prático para começar com o protocolo que pode substituir JSON + JSON Schema

Introdução

Se o JSON dominou a comunicação entre sistemas nos últimos 20 anos, o TOON Protocol tenta resolver suas limitações mais profundas: falta de tipagem forte, ausência de validação nativa e dificuldade de documentar regras sobre cada campo.

Escrever um TOON Schema significa criar um documento que combina dados + tipos + validação + semântica em um único arquivo legível. Isso reduz erros, aumenta segurança e facilita integração entre times e linguagens.

Este guia mostra, passo a passo, como criar seu primeiro schema.

1. Estrutura básica de um documento TOON

A sintaxe do TOON lembra YAML, mas com anotações de tipos usando ::.

Exemplo mínimo:

user:
  name: "Rafael Lins" :: string(required)
  age: 34 :: int(min=0, max=120)
  email: "rafael@adrock.com.br" :: email(required)

Regras básicas:

• tudo é indentado como YAML

• valores vêm primeiro, tipagem depois (valor :: tipo)

• cada campo pode ter múltiplos constraints

• nada é inferido automaticamente

O TOON é explícito e determinístico.

2. Tipos essenciais do TOON

Os tipos principais:

• string

• int

• float

• bool

• email

• url

• datetime

• list(tipo)

• object

• enum(…)

Exemplos:

price: 199.90 :: float(min=0)
isActive: true :: bool
site: "https://adrock.com.br" :: url
role: "admin" :: enum("admin", "editor", "viewer")

3. Criando listas e objetos aninhados

Lista simples:

tags: ["seo", "analytics", "python"] :: list(string)

Lista com validação:

scores: [10, 9, 8] :: list(int(min=0, max=10))

Objeto aninhado:

address:
  street: "Rua X" :: string(required)
  number: 120 :: int(min=1)
  city: "Curitiba" :: string
  zip: "80000-000" :: string(pattern="[0-9]{5}-[0-9]{3}")

Objetos TOON funcionam como dicionários fortemente tipados.

4. Campos obrigatórios, opcionais e nullables

Um dos pontos fortes do TOON é a clareza sobre o que é opcional ou obrigatório.

Campo obrigatório:

email: "client@example.com" :: email(required)

Campo opcional:

nickname: null :: string(optional)

Aceitando null explicitamente:

middleName: null :: string(nullable)

Diferente do JSON, null, “campo vazio” e “campo ausente” são INEQUIVOCAMENTE diferentes.

5. Validação embutida no próprio schema

O TOON traz validações comuns:

• min

• max

• length

• pattern

• enum()

• required

• optional

• nullable

Exemplos completos:

person:
  name: "Rafael" :: string(required, length(min=2, max=50))
  age: 34 :: int(min=0, max=150)
  salary: 5000 :: float(min=0)
  phone: "+55 41 99999-0000" :: string(pattern="^\+55")

As validações tornam o documento auto descritivo — não há risco de “documentação desatualizada”.

6. Como estruturar um TOON Schema completo

Aqui está um schema realista:

order:
  id: "ORD-2025-0001" :: string(required, pattern="^ORD-[0-9]{4}-[0-9]{4}$")
  createdAt: "2025-10-12T14:30:00Z" :: datetime(required)
  total: 499.90 :: float(min=0)
  customer:
    name: "Ana Souza" :: string(required)
    email: "ana@example.com" :: email(required)
    phone: "+55 11 90000-0000" :: string(pattern="^\+55")
  items: 
    - sku: "LED-123" :: string
      quantity: 2 :: int(min=1)
      price: 199.90 :: float(min=0)
    - sku: "LED-555" :: string
      quantity: 1 :: int(min=1)
      price: 99.90 :: float(min=0)
  status: "pending" :: enum("pending", "paid", "shipped", "canceled")

Compare o mesmo documento em JSON:

{
  "order": {
    "id": "ORD-2025-0001",
    "createdAt": "2025-10-12T14:30:00Z",
    "total": 499.90,
    "customer": {
      "name": "Ana Souza",
      "email": "ana@example.com",
      "phone": "+55 11 90000-0000"
    },
    "items": [
      {
        "sku": "LED-123",
        "quantity": 2,
        "price": 199.90
      }
    ],
    "status": "pending"
  }
}

O JSON é mais curto, porém não tem:

• tipo

• validação

• constraints

• enum

• coerção semântica

• auditoria

• garantia de integridade

O TOON entrega tudo isso no arquivo.

7. Como validar um arquivo TOON

Embora os parsers ainda estejam evoluindo, a lógica típica é:

valor → tipo → constraints → resultado

Erros comuns:

• tipo incompatível

• pattern inválido

• enum não permitido

• campo obrigatório ausente

• constraints violadas

O parser (dependendo da biblioteca) retorna erros estruturados.

8. TOON + Python / Node.js / Go (cenários futuros)

Ainda não existem SDKs oficiais maduros, mas a comunidade já discute:

• transformar TOON em modelos Pydantic

• gerar interfaces TypeScript automaticamente

• converter TOON para Protobuf

• usar TOON como contrato de API em OpenAPI 4.0

• uso em LLMs para garantir respostas tipadas

Quando surgirem ferramentas estáveis, TOON pode se tornar o “schema universal” de APIs modernas.

9. Boas práticas ao escrever seu primeiro schema

Seja explícito sempre.

Nunca deixe o parser inferir nada.

Valide o que importa.

Defina min/max, enum, pattern.

Use tipagem forte.

Evite aninhamento profundo.

Mantenha coerência entre schemas.

Documente regras críticas dentro do próprio arquivo.

Trate null corretamente.

Prefira enums a strings soltas.

10. Template pronto para iniciar seu próprio TOON Schema

Copie e personalize:

entity:
  id: "" :: string(required)
  createdAt: "" :: datetime(required)
  meta:
    version: 1 :: int(min=1)
    source: "" :: string(optional)
  data:
    # Adicione aqui seus campos
    example: "" :: string(optional)

Referências e análises técnicas

👉 https://json.org

👉 https://json-schema.org

👉 https://yaml.org

👉 https://protobuf.dev

👉 https://avro.apache.org

👉 RFCs sobre schema-driven contracts

👉 Discussões técnicas no GitHub sobre novos formatos estruturados