J'ai expédié suffisamment d'API pour connaître le moment exact où un projet a besoin d'un schéma JSON Ce n'est jamais au début Il est trois semaines, quand une deuxième équipe commence à consommer votre point de terminaison, quelqu'un envoie un corps de requête mal formé, et un null glisse dans un champ que tout le monde supposait être toujours une chaîne Soudain, vous avez besoin d'un contrat - un document qui dit, sous une forme qu'une machine peut appliquer, " ; voici à quoi ressemble une charge utile valide." ; Ce document est un schéma JSON, et en écrire un à la main à partir d'un point final qui renvoie déjà des données réelles est l'un des travaux les plus fastidieux du travail backend.
tl;dr : Collez un échantillon JSON dans le Générateur de schéma JSON(, choisissez Draft-07 ou 2020-12), et cela déduit un schéma - tapez,
requiredchamps, éléments de tableau fusionnés et formats de chaîne tels quedate-timeetuuid. Il fonctionne entièrement dans votre navigateur, donc les charges utiles transportant des jetons et des données personnelles ne quittent jamais la page Traitez la sortie comme une première ébauche forte, puis serrez-la avec les contraintes que vous seul connaissez.
J'ai construit cet outil pour Toolz.dev parce que je n'arrêtais pas de faire la même chose à la main : ouvrir un corps de réponse, le plisser au carré et transcrire sa forme en un schéma clause par clause Il est répétitif, et la transcription répétitive est l'endroit où les erreurs se cachent Ce guide explique ce que fait le générateur, où l'inférence est fiable, où il a besoin de votre jugement, et comment un schéma généré s'intègre dans un véritable workflow de validation.
Qu'est-ce qu'un schéma JSON et pourquoi en générer un à partir de données ?
JSON Schema est un vocabulaire permettant de décrire la structure de JSON, maintenu comme une spécification à part entière plutôt que comme convention Un schéma est lui-même un document JSON qui déclare le type attendu de chaque champ, quels champs sont requis, quelle forme prennent les objets et tableaux imbriqués, et - avec des mots-clés comme pattern, enum, minimum, et format - quelles valeurs sont réellement autorisées Les validateurs de presque toutes les langues lisent un schéma et vous disent si un document donné est conforme C'est ce qui se rapproche le plus du monde JSON d'un système de types qui traverse les frontières de service.
La raison pour générer un schéma à partir d'un échantillon, plutôt que de l'écrire à partir de zéro, est que la plupart d'un schéma est mécanique Marcher une charge utile et enregistrer " ; c'est une chaîne, c'est un entier, cet objet a ces clés" ; est exactement le genre de travail qu'une machine devrait faire Ce qui est non mécanique est la couche sémantique : savoir que status peut-être seulement l'une des quatre cordes, ça age ne peut pas être négatif, ça email doit correspondre à un vrai modèle d'adresse La génération gère l'échafaudage mécanique afin que vous puissiez consacrer votre attention aux contraintes qui comptent Vous partez d'un document qui correspond déjà à la réalité et ajoutez des règles, au lieu de partir d'un fichier vierge et d'espérer vous souvenir de chaque champ.
Il y a une dimension de confiance aussi Quand vous tapez un schéma à la main, vous encodez ce que vous croire le point final revient Les croyances dérivent de la réalité - un champ est ajouté, un entier devient nullable, un point final qui a renvoyé un seul objet commence à renvoyer un tableau Un schéma généré à partir d'une réponse réelle est ancré à ce que le service a véritablement envoyé le jour où vous l'avez capturé Cette ancre vaut beaucoup lorsque vous déboguez pourquoi la validation passe en stadification et échoue en production.
Comment le générateur déduit un schéma
Le moteur analyse votre JSON et marche la valeur de manière récursive, émettant un nœud de schéma pour chaque partie de la structure Les règles sont délibérément conservatrices, car un schéma trop lâche est inutile et un schéma trop strict rejette les données valides.
Pour les scalaires, il distingue integer de number - 42 se transforme integer, 4.2 se transforme number - parce que cette distinction est significative pour les validateurs et pour quiconque lit le schéma. Booléens et null mapper à leurs propres types Les chaînes deviennent type: string(en), et si la détection de format est activée, le moteur vérifie la valeur par rapport à un ensemble de motifs bien connus et la marque : date-time, date, time, email, uri, uuid, et ipv4.
Pour les objets, il enregistre chaque clé, déduit un schéma pour chaque valeur, et - si required l'inférence est activée - marque une clé requise lorsqu'elle est présente dans chaque objet à cette position Pour un seul objet qui signifie toutes les clés ; le cas intéressant est les tableaux.
Pour les tableaux d'objets, le générateur fait quelque chose de plus utile qu'une marche naïve Au lieu d'émettre un schéma séparé pour chaque élément ou un étalement anyOf de formes presque identiques, il fusionne tous les objets du réseau en un seul items schéma qui décrit un seul élément Une clé présente dans chaque élément est requise ; une clé présente dans seulement certains éléments est laissée facultative Cela reflète le comportement des collections API réelles : une liste paginée où la plupart des enregistrements portent une avatarUrl mais quelques-uns ne le font pas Le schéma fusionné capture " ; ces champs apparaissent toujours, ceux-ci apparaissent parfois" ; dans une définition lisible Vous pouvez le voir dans l'échantillon intégré, où le members array a deux objets, dont un avec un active champ et un sans - et les marques de schéma d'élément générées id et role obligatoire mais part active facultatif.
Pour les réseaux de scalaires mixtes, le moteur regroupe les types d'éléments en un seul type tableau - ["integer", "string", "boolean"] - plutôt qu'une union verbeuse. Lorsque les formes objet et non-objet se mélangent véritablement dans un seul tableau, il s'en remet à anyOf(en), qui est la construction de schéma JSON correcte pour " ; l'une de ces alternatives." ;
Comment utiliser le générateur de schéma JSON
Étape 1 : Collez un échantillon représentatif
Déposez une réponse API, un luminaire, un fichier de configuration ou un corps de webhook. La chose la plus importante que vous puissiez faire pour plus de précision est de coller un représentant échantillon. Si vous avez plusieurs enregistrements d'une réponse réelle, incluez-les tous à l'intérieur d'un tableau - le générateur les fusionnera et déduira correctement l'optionalité Un échantillon à un enregistrement indique au moteur que chaque champ qu'il voit est toujours présent, ce qui est souvent faux Chargez d'abord l'échantillon intégré pour voir comment les objets imbriqués, les tableaux d'objets et les chaînes formatées sont gérés avant de coller le vôtre.
Étape 2 : Choisissez le dialecte
Choisissez Draft-07 pour la compatibilité la plus large parmi les bibliothèques de validation, ou 2020-12 pour la spécification actuelle. L'outil écrit le bon $schema identifiant sur la racine afin que votre validateur applique les bonnes règles Pour les formes d'objet et de tableau que ce générateur produit, la sortie structurelle est la même sur les deux dialectes ; la différence visible est l'identifiant Si vous n'êtes pas sûr de savoir lequel prend en charge votre outillage, Draft-07 est la valeur par défaut sûre - il a la plus large prise en charge de bibliothèque de toutes les versions.
Étape 3 : Définissez vos options
Ajouter un title si vous voulez que le schéma soit auto-documenté Décidez s'il faut émettre required - la plupart du temps, vous le voulez, mais au début de l'exploration, vous préférerez peut-être un schéma plus souple Gardez la détection de format sur sauf si vous voyez des faux positifs Et activez le mode strict (stricte mode)additionalProperties: false) lorsque le schéma garde quelque chose que vous contrôlez entièrement, comme un fichier de configuration ou un corps de requête, et que vous souhaitez que les clés inattendues soient rejetées plutôt qu'ignorées.
Étape 4 : Générer, réviser et exporter
Appuyez sur Générer, puis lisez la sortie de manière critique. Vérifiez cela required correspond à votre intention, cet entier contre numéro est sorti correctement et tous les formats détectés sont corrects plutôt que coïncidents. Quand cela semble correct, copiez le schéma ou téléchargez-le sous forme de .json fichier prêt à être déposé dans votre validateur ou référentiel.
Un exemple travaillé
Considérez cette réponse comme une hypothétique /projects point final:
{
"id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
"name": "Toolz",
"createdAt": "2026-01-14T09:30:00Z",
"score": 4.8,
"members": [
{ "id": 1, "role": "owner", "active": true },
{ "id": 2, "role": "editor" }
]
}
Le générateur produit un schéma où id est une chaîne avec format: "uuid", createdAt est une chaîne avec format: "date-time", score est un number (pas un entier, à cause de la décimale), et members est un tableau dont items schéma nécessite id et role mais pas active. Ce dernier détail est le gain : à partir de deux exemples de membres, il a correctement déduit cela active est facultatif Faire ce raisonnement à la main sur une grande charge utile est exactement le genre de travail prudent et ennuyeux qu'un générateur supprime.
Où s'arrête l'inférence et où commence votre jugement
Je veux être direct sur les limites, parce qu'un schéma généré remis directement à la production est une erreur L'inférence voit les types et la structure ; elle ne peut pas voir l'intention.
Il ne peut pas le savoir role est un enum de owner, editor, et viewer - de l'échantillon, il ne sait que role est une chaîne Il ne peut pas savoir que score va de 0 à 5, ça name a une longueur maximale, ou qu'un code qui ressemble à un UUID est en fait un identifiant opaque qui devrait rester une chaîne simple. Il en déduit required de la présence, donc un champ facultatif qui se trouve apparaître dans votre échantillon sera marqué requis jusqu'à ce que vous le corrigiez Et il fonctionne à partir des données que vous lui donnez : si votre échantillon ne comprend jamais un null pour un champ nullable, le schéma ne saura pas que le champ peut être nul.
Le bon modèle mental est l'échafaudage Le générateur construit le cadre avec précision - chaque champ, son type, l'imbrication, les formes du tableau, la liste requise basée sur la présence Vous ajoutez ensuite les contraintes sémantiques : enums, motifs, bornes numériques, et tous les formats que le moteur ne pouvait pas voir à partir d'une valeur C'est plus rapide et moins sujet aux erreurs que de partir de rien, car la transcription structurelle fastidieuse est déjà faite et correcte.
Draft-07 contre 2020-12 : que devriez-vous choisir ?
| considération | Projet-07 | 2020-12 |
|---|---|---|
| Support bibliothèque | Plus large ; soutenu presque partout | Grandir ; vérifiez votre validateur |
| situation | Largement déployé, stable | Spécification actuelle |
$schema évaluer |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| Mots-clés des éléments de tableau | items pour les schémas à un seul élément |
items / prefixItems split pour tuples |
| Meilleur quand | La compatibilité maximale est importante | Vous voulez les dernières fonctionnalités de spécification |
Pour les schémas générés par cet outil - objets, listes obligatoires, tableaux d'une seule forme d'élément - les deux dialectes expriment la même structure La décision pratique se résume à ce que prend en charge votre bibliothèque de validation Si vous câbler le schéma dans une pile établie, faites correspondre la version de vos documents de validateur Si vous commencez à nouveau et n'avez aucune contrainte, Draft-07 reste le choix pragmatique pour son support écosystémique inégalé.
Cas d'utilisation courants
Documenter une API existante. Lorsque vous héritez d'un point de terminaison sans schéma, en générer un à partir d'une réponse réelle vous donne un document de départ précis en quelques secondes Vous l'affinez ensuite dans un contrat publié Cela se compile naturellement avec des types générateurs pour votre code client - le même échantillon peut alimenter le JSON vers le script outil pour que votre contrat de serveur et les types de clients proviennent de la même source de vérité.
Validation des organes de demande. Pour un corps de requête que vous contrôlez, générez un schéma à partir d'un exemple valide, activez le mode strict pour rejeter les clés inattendues et ajoutez les énums et les limites appliqués par votre point de terminaison. Désormais, les requêtes mal formées échouent sur le bord avec une erreur de validation claire au lieu de provoquer des pannes confuses au plus profond de votre gestionnaire.
Validation du fichier de configuration. Les applications qui lisent la configuration JSON bénéficient énormément d'un schéma Générez-en une à partir d'une configuration connue, serrez-la et validez au démarrage afin qu'une faute de frappe dans une clé de configuration échoue bruyamment au lieu de désactiver silencieusement une fonctionnalité.
Essais et agencements. Un schéma sert également d'actif de test. Valider vos luminaires par rapport à lui dans CI afin qu'un luminaire qui dérive hors de forme soit attrapé avant de produire un test vert trompeur.
Tests contractuels entre services. Lorsque deux services s'accordent sur une charge utile, un schéma partagé est le contrat. Le générer à partir d'un message réel et l'affiner donne aux deux équipes un document contre lequel elles peuvent valider indépendamment.
Confidentialité : pourquoi cela s'exécute dans votre navigateur
Les échantillons d'API sont parmi les textes les plus sensibles qu'un développeur gère Ils contiennent régulièrement des jetons d'accès, des identifiants de session, des adresses e-mail, des identifiants d'enregistrement interne et parfois des données personnelles qui ne doivent jamais être collées dans un formulaire Web aléatoire C'est précisément pourquoi le générateur de schéma JSON effectue tout son travail côté client L'analyse, l'inférence et la sérialisation se produisent en JavaScript dans votre navigateur Rien n'est téléchargé, enregistré ou stocké sur un serveur Vous pouvez le vérifier en ouvrant votre onglet réseau pendant que vous générez, ou en vous déconnectant d'Internet - l'outil fonctionne toujours Je me soucie de cela car je n'utiliserais pas un outil qui expédiait mes charges utiles à quelqu'est pas quelqu'autre et vous demanderait pas le même serveur ; je fais le même argument et je ne le serveur. Confidentialité des données dans les outils en ligne écrire.
Comment il s'adapte à la boîte à outils JSON plus large
Un schéma est un artefact dans un flux de travail JSON plus grand Avant de générer un schéma, il est utile d'avoir une entrée propre et valide - le Formateur JSON formatera et validera une charge utile afin que vous n'alimentiez pas de texte mal formé dans le générateur Après avoir un schéma, vous voulez souvent des types pour votre code d'application, qui est où JSON vers le script entre. Et si votre pipeline se déplace entre les formats, le JSON vers Yaml converter gère la conversion attendue par de nombreux systèmes de configuration et de CI. J'ai écrit sur la façon dont ces pièces se connectent dans le Guide ultime des outils JSON(en), et à propos de l'assemblage d'un kit plus large dans le Boîte à outils pour les développeurs Web aperçu. Le but d'une boîte à outils connectée est qu'un seul échantillon peut circuler à travers plusieurs outils - schéma, types, conversion de format - sans jamais quitter votre navigateur.
FAQ
Comment générer un schéma JSON à partir de JSON ?
Collez votre JSON dans l'éditeur, choisissez Draft-07 ou 2020-12 et appuyez sur Générer L'outil infère le type de chaque champ, extrait les clés requises et génère un schéma que vous pouvez copier directement dans un validateur Rien n'est téléchargé - l'inférence s'exécute entièrement dans votre navigateur.
Quelle est la différence entre Draft-07 et 2020-2012 ?
Ce sont deux versions de la spécification JSON Schema Draft-07 a le support le plus large dans toutes les bibliothèques et est un défaut sûr. 2020-12 est la version actuelle et change la façon dont les tableaux et les sous-schémas sont exprimés, entre autres. Pour les formes d'objet et de tableau, cet outil produit la structure est la même ; la principale différence visible est la $schema identifiant.
Comment l'outil décide-t-il des champs requis ?
Une clé est marquée obligatoire lorsqu'elle apparaît dans chaque objet que le générateur voit. Pour un seul objet qui signifie chaque clé, pour un tableau d'objets, cela signifie des clés présentes dans tous les éléments. Les clés qui n'apparaissent que dans certains enregistrements sont exclues des éléments requis, reflétant la façon dont les API omettent les champs facultatifs. Vous pouvez désactiver complètement la détection de champ requis.
Que se passe-t-il avec un tableau d'objets ?
Les objets sont fusionnés en un seul items schéma décrivant un seul élément, et la propriété est tapé comme un tableau de celui-ci Les clés présentes dans chaque élément deviennent obligatoires ; les clés présentes dans seulement certains restent facultatives Cela maintient le schéma lisible au lieu de produire un grand anyOf de formes quasi-identiques.
Quels formats de chaîne détecte-t-il ?
Il reconnaît date-time, date, time, email, uri, uuid, et ipv4 enchaîne et ajoute la correspondance format mot-clé. La détection est le meilleur effort à partir d'un seul échantillon, alors examinez les résultats : un code qui ressemble à un UUID sera étiqueté comme tel. Vous pouvez désactiver la détection de format si vous préférez les types de chaînes simples.
Puis-je générer un schéma à partir d'un seul échantillon ?
Oui, mais un échantillon ne montre qu'une seule forme possible Un champ qui est un nombre dans votre échantillon pourrait être nul ou une chaîne ailleurs, et un champ facultatif qui se trouve être présent sera marqué requis Plus l'échantillon est représentatif - idéalement plusieurs enregistrements réels - plus les types déduits et la liste requise sont précis.
Un schéma généré est-il prêt pour la validation de la production ?
Traitez-le comme un point de départ fort plutôt que comme un document fini L'inférence capture les types, la structure et les champs requis avec précision, mais les contraintes sémantiques - enums, modèles de chaînes, minimums et maximums numériques, formats qu'elle ne peut pas voir à partir d'une valeur - doivent toujours être ajoutées à la main La génération supprime l'échafaudage fastidieux afin que vous puissiez vous concentrer sur ces règles.
Mon JSON est-il téléchargé sur un serveur ?
Non. L'ensemble du moteur d'inférence fonctionne comme JavaScript dans votre navigateur Rien n'est transmis, enregistré ou stocké. Vous pouvez le confirmer en surveillant votre onglet réseau pendant que vous générez ou en vous déconnectant d'Internet - l'outil fonctionne toujours.
