Standard Schema - Interface comum para validação em TypeScript

• Especificação projetada para que bibliotecas de schema baseadas em JavaScript/TypeScript implementem uma interface comum
• O objetivo é permitir que a lógica de validação de tipos definida pelo usuário seja reutilizada entre bibliotecas, tornando as ferramentas compatíveis entre si sem adaptadores separados
• Foi projetada em conjunto pelos criadores das principais bibliotecas, como Zod, Valibot e ArkType

Interface principal (StandardSchemaV1)

• Toda a especificação é implementada por meio de uma propriedade de objeto chamada ~standard
• Dentro de ~standard, existem propriedades obrigatórias como version, vendor, validate e types
• A função validate retorna value em caso de sucesso e um array issues em caso de falha
• A propriedade types permite inferir em TypeScript os tipos de entrada (input) e saída (output) do schema
• Todas as atualizações mantêm compatibilidade, exceto em mudanças de versão major

Objetivos de design

• Suporte à validação em runtime: padroniza e transmite informações de erro no formato definido pelo padrão
• Suporte à inferência de tipos estáticos: expõe explicitamente as informações de tipo inferidas por bibliotecas baseadas em TypeScript
• Simplicidade: pode ser implementado adicionando apenas algumas linhas às funções já existentes da biblioteca
• Evitar conflitos de API: concentra tudo em um único namespace ~standard, evitando colisões com APIs existentes
• Manter a experiência do desenvolvedor: começa com til (~standard) para reduzir sua prioridade no autocompletar

Quais bibliotecas implementam isso

• O Standard Schema já é suportado por bibliotecas como Zod, Valibot, ArkType, Arri Schema e TypeMap
• tRPC, TanStack Form, TanStack Router e Hono Middleware também aceitam schemas de usuário com base no Standard Schema

Como implementar a especificação na sua biblioteca

• Copie a interface StandardSchemaV1 para a biblioteca e adicione a propriedade ~standard
• Conecte a função validate à função de validação existente, retornando { value } em caso de sucesso e { issues } em caso de erro
• Se necessário, a validação assíncrona também é possível, mas a validação síncrona é recomendada

Como aceitar schemas definidos pelo usuário com Standard Schema

• Para usar diretamente sem uma biblioteca de schema, instale @standard-schema/spec ou copie a interface para uso próprio
• Em funções de exemplo como standardValidate, qualquer schema que siga a interface padrão pode ser validado da mesma forma, independentemente da biblioteca
• Se quiser permitir apenas validação síncrona, basta verificar se o retorno de validate é um Promise e tratar isso como exceção

FAQ

• É preciso adicionar a dependência @standard-schema/spec?: não é obrigatório adicioná-la como dependência; é possível copiar e usar
• Não pode ser adicionada como dev dependency: como faz parte da API pública da biblioteca, ela precisa estar disponível também no ambiente real de distribuição
• Por que usar til (~) antes de standard: a intenção é fazer com que apareça depois de outras propriedades no autocompletar
• Por que usar uma chave de string em vez de Symbol: porque, no TypeScript, chaves Symbol podem causar problemas na ordenação do autocompletar e na inferência de tipos