- 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
Ainda não há comentários.