Standard Schema - Una interfaz común para la validación en TypeScript

• Una especificación diseñada para que las bibliotecas de esquemas basadas en JavaScript/TypeScript implementen una interfaz común
• Su objetivo es permitir reutilizar la lógica de validación de tipos definida por el usuario entre distintas bibliotecas, haciendo que las herramientas sean compatibles entre sí sin adaptadores separados
• Fue diseñada en conjunto por los creadores de bibliotecas principales como Zod, Valibot y ArkType

Interfaz principal (StandardSchemaV1)

• Toda la especificación se implementa mediante una propiedad de objeto llamada ~standard
• Dentro de ~standard existen propiedades obligatorias como version, vendor, validate y types
• La función validate devuelve value si tiene éxito, y un arreglo issues si falla
• La propiedad types permite inferir en TypeScript los tipos de entrada (input) y salida (output) del esquema
• Todas las actualizaciones mantienen compatibilidad mientras no sean una versión mayor

Objetivos de diseño

• Soporte de validación en tiempo de ejecución: entrega la información de errores de forma estandarizada
• Soporte para inferencia de tipos estáticos: expone explícitamente la información de tipos inferida por bibliotecas basadas en TypeScript
• Simplicidad: puede implementarse agregando solo unas pocas líneas a funciones existentes de la biblioteca
• Evitar conflictos de API: todo se coloca dentro del espacio de nombres ~standard para no chocar con APIs existentes
• Mantener una buena experiencia de desarrollo: al comenzar con tilde (~standard), su prioridad baja en el autocompletado

Qué bibliotecas lo están implementando

• Zod, Valibot, ArkType, Arri Schema, TypeMap y otras ya ofrecen soporte para Standard Schema
• tRPC, TanStack Form, TanStack Router y Hono Middleware también aceptan esquemas de usuario basados en Standard Schema

Cómo implementar la especificación en tu propia biblioteca

• Copia la interfaz StandardSchemaV1 en tu biblioteca y agrega la propiedad ~standard
• Conecta la función validate con tu función de validación existente para que devuelva { value } en caso de éxito y { issues } en caso de error
• Si es necesario, también se puede hacer validación asíncrona, aunque se recomienda la validación síncrona

Cómo recibir esquemas definidos por el usuario con Standard Schema

• Si quieres usarlo directamente sin una biblioteca de esquemas, instala @standard-schema/spec o copia la interfaz para usarla
• Si un esquema tiene la interfaz estándar, como en la función de ejemplo standardValidate, puede validarse de la misma forma sin importar la biblioteca
• Si quieres permitir solo validación síncrona, basta con comprobar si el valor de retorno de validate es un Promise y lanzar una excepción

Preguntas frecuentes

• ¿Hay que agregar la dependencia @standard-schema/spec?: no es obligatorio añadirla como dependencia; puedes copiarla y usarla
• No puede agregarse solo como dev dependency: como forma parte de la API pública de la biblioteca, debe poder usarse también en el entorno de despliegue real
• Por qué se usa una tilde (~) antes de ~standard: se busca que aparezca después de otras propiedades en el autocompletado
• Por qué se usa una clave de texto en lugar de Symbol: porque en TypeScript las claves Symbol pueden causar problemas con el orden del autocompletado o la inferencia de tipos