Standard Schema - une interface commune pour la validation TypeScript

• Une spécification conçue pour que les bibliothèques de schémas basées sur JavaScript/TypeScript implémentent une interface commune
• Son objectif est de permettre la réutilisation de la logique de validation de types définie par l’utilisateur d’une bibliothèque à l’autre, afin que les outils soient compatibles entre eux sans adaptateurs dédiés
• Conçue conjointement par les auteurs de bibliothèques majeures comme Zod, Valibot et ArkType

Interface principale (StandardSchemaV1)

• Toute la spécification est implémentée via une propriété objet appelée ~standard
• À l’intérieur de ~standard, on trouve des propriétés requises comme version, vendor, validate et types
• La fonction validate renvoie value en cas de succès, et un tableau issues en cas d’échec
• La propriété types permet d’inférer en TypeScript les types d’entrée (input) et de sortie (output) du schéma
• Toutes les mises à jour restent compatibles tant qu’il ne s’agit pas d’une version majeure

Objectifs de conception

• Prise en charge de la validation à l’exécution : transmettre des informations d’erreur standardisées selon une approche commune
• Prise en charge de l’inférence de types statiques : exposer explicitement les informations de types inférées par les bibliothèques basées sur TypeScript
• Simplicité : l’implémentation peut être ajoutée aux fonctions existantes d’une bibliothèque en seulement quelques lignes
• Évitement des conflits d’API : tout est placé dans un seul espace de noms ~standard afin d’éviter les conflits avec l’API existante
• Préservation de l’expérience développeur : le préfixe tilde (~standard) réduit sa priorité dans l’autocomplétion

Quelles bibliothèques l’implémentent ?

• Le standard des schémas est déjà pris en charge par Zod, Valibot, ArkType, Arri Schema, TypeMap et d’autres
• tRPC, TanStack Form, TanStack Router, Hono Middleware et d’autres acceptent également les schémas utilisateur via ce standard

Comment implémenter la spécification dans sa propre bibliothèque

• Copier l’interface StandardSchemaV1 dans la bibliothèque et y ajouter la propriété ~standard
• Relier la fonction validate à la fonction de validation existante pour renvoyer { value } en cas de succès et { issues } en cas d’échec
• La validation asynchrone est possible si nécessaire, mais la validation synchrone est recommandée

Comment accepter des schémas définis par l’utilisateur via le standard

• Pour l’utiliser directement sans bibliothèque de schémas, il suffit d’installer @standard-schema/spec ou de copier l’interface
• Avec une fonction d’exemple comme standardValidate, tout schéma exposant l’interface standard peut être validé de la même manière, quelle que soit la bibliothèque
• Pour n’autoriser que la validation synchrone, il suffit de vérifier si la valeur de retour de validate est une Promise, puis de lever une exception le cas échéant

FAQ

• Faut-il ajouter la dépendance @standard-schema/spec ? : il n’est pas nécessaire de l’ajouter comme dépendance ; il est possible de copier l’interface et de l’utiliser
• Impossible de l’ajouter en dev dependency : comme elle fait partie de l’API publique de la bibliothèque, elle doit être utilisable dans l’environnement de déploiement réel
• Pourquoi utiliser un tilde (~) devant ~standard ? : l’objectif est qu’il apparaisse après les autres propriétés dans l’autocomplétion
• Pourquoi utiliser une clé de chaîne plutôt qu’un Symbol ? : en TypeScript, les clés Symbol posent des problèmes pour l’ordre dans l’autocomplétion et l’inférence de types