Convertissez n'importe quelle réponse JSON en un schéma Zod avec une seule requête POST

Vous accédez à une API tierce, obtenez une réponse JSON et vous avez maintenant besoin d'un schéma Zod pour cela. Le processus manuel : regardez la réponse, comptez les champs, déterminez lesquels sont nullables, gérez les objets imbriqués, tapez z.object et z.string() pour chaque propriété. Une faute de frappe et votre la validation transmet silencieusement les mauvaises données.

Pour un objet plat à cinq champs, cela prend quelques minutes. Pour une intention de paiement Stripe avec des frais imbriqués, métadonnées et plus de 30 champs, cela prend suffisamment de temps pour que vous commenciez à remettre en question vos choix de carrière.

Le botoï /v1/schema/json-to-zod le point final élimine cela. POSTez n'importe quel JSON, obtenez un aperçu complet Schéma Zod de retour. Une requête, pas de CLI à installer, pas de package npm à configurer.

L'appel API

Envoyez un objet JSON et un nom de schéma facultatif :

boucle

Réponse:

Noeud.js

Python

Le point de terminaison accepte tout JSON valide dans le json champ. Objets, tableaux, profondément imbriqués structures; tout fonctionne. Le name Le champ est facultatif et sa valeur par défaut est "Root".

Exemple concret : une intention de paiement Stripe

Voici une Stripe réaliste payment_intent réponse avec imbriqué metadata et charges objets. C'est le genre de charge utile où l'écriture manuscrite des schémas Zod ça devient vite douloureux.

Corps de la requête :

L'API renvoie ce schéma Zod :

Chaque objet imbriqué devient le sien z.object. La charges.data le tableau produit un z.array avec la forme correcte de l'article. Les booléens, les nombres et les chaînes sont détectés à partir de les valeurs. Copiez ceci dans votre base de code, ajoutez import { "z" } from "zod", et tu as types validés à l'exécution pour les réponses Stripe en moins de 30 secondes.

Fonctionne également pour les interfaces TypeScript

Si vous avez besoin de types TypeScript sans validation d'exécution, le /v1/schema/json-to-typescript le point de terminaison génère des interfaces à partir de la même entrée JSON.

Réponse:

Même format d'entrée, même name paramètre. Utiliser json-to-zod quand tu as besoin validation d'exécution (gestionnaires d'API, analyse de formulaire, charges utiles de webhook). Utiliser json-to-typescript lorsque vous n'avez besoin que de la sécurité des types au moment de la compilation.

Créez un script codegen pour votre projet

Le véritable pouvoir apparaît lorsque vous automatisez la génération de schémas. Ce script récupère les réponses API en direct, convertit chacun d'eux en schéma Zod et écrit la sortie dans votre src/schemas/ annuaire.

#!/bin/bash
set -euo pipefail

API_BASE="https://api.botoi.com/v1"
OUTPUT_DIR="./src/schemas"

mkdir -p "\$OUTPUT_DIR"

generate_schema() {
  local name=\$1
  local url=\$2
  local output_file="\$OUTPUT_DIR/\$(echo "\$name" | tr '[:upper:]' '[:lower:]').ts"

  echo "Fetching \$url ..."
  local json_response
  json_response=\$(curl -s "\$url")

  echo "Generating Zod schema for \$name ..."
  local zod_response
  zod_response=\$(curl -s -X POST "\$API_BASE/schema/json-to-zod" \\
    -H "Content-Type: application/json" \\
    -d "{
      \\"json\\": \$json_response,
      \\"name\\": \\"\$name\\"
    }")

  local schema
  schema=\$(echo "\$zod_response" | jq -r '.data.zod')

  cat > "\$output_file" << SCHEMAEOF
import { z } from "zod";

\$schema

export type \$name = z.infer<typeof \${name}Schema>;
SCHEMAEOF

  echo "Wrote \$output_file"
}

# Add your API endpoints here
generate_schema "UserProfile" "https://api.example.com/users/1"
generate_schema "Order" "https://api.example.com/orders/latest"
generate_schema "Product" "https://api.example.com/products/42"

echo "Done. Generated \$(ls "\$OUTPUT_DIR"/*.ts | wc -l) schema files."

L'exécuter :

Fetching https://api.example.com/users/1 ...
Generating Zod schema for UserProfile ...
Wrote ./src/schemas/userprofile.ts
Fetching https://api.example.com/orders/latest ...
Generating Zod schema for Order ...
Wrote ./src/schemas/order.ts
Fetching https://api.example.com/products/42 ...
Generating Zod schema for Product ...
Wrote ./src/schemas/product.ts
Done. Generated 3 schema files.

Chaque fichier généré ressemble à ceci :

Ajoutez ce script à votre package.json comme "codegen:schemas" et exécutez-le chaque fois que l'API en amont change. Vos schémas Zod restent synchronisés avec la forme réelle de la réponse, et les types TypeScript sont automatiquement dérivés du schéma.

Quand c'est utile

• Intégration d'une nouvelle API tierce. Appuyez une fois sur l'API, convertissez la réponse en Zod schéma et commencez à construire avec des types validés au lieu de deviner les noms de champs.
• Migration de JavaScript vers TypeScript. Si vous avez des réponses API qui transitent par code non typé, générez des schémas à partir de données réelles pour obtenir rapidement une couverture de type.
• Garder les schémas synchronisés. Exécutez le script codegen dans CI selon un planning pour détecter lorsqu'une API en amont change la forme de sa réponse.
• Prototypage. Lorsque vous avez besoin de types validés pour une preuve de concept et que vous ne souhaitez pas pour passer du temps à créer manuellement des schémas pour les API que vous pourriez supprimer la semaine prochaine.