Générateur de schéma JSON, gratuit

À quoi sert JSON Schema

JSON Schema est une façon déclarative de décrire à quoi un document JSON devrait ressembler : quelles propriétés il a, quels types ces propriétés portent, ce qui est requis vs optionnel et quelles valeurs sont valides. C'est l'équivalent côté JSON de XSD pour XML ou d'une définition de table de base de données. Le projet officiel vit à json-schema.org.

Là où vous le rencontrerez :

• Contrats d'API. OpenAPI 3.1 (sortie de février 2021) intègre directement JSON Schema : chaque corps de requête et chaque corps de réponse dans une spec d'API moderne est décrit avec un fragment de JSON Schema.
• Auto-complétion et validation IDE. Le settings.json de VS Code, les package.json et tsconfig.json de votre projet, les fichiers workflow.yml de GitHub Actions s'auto-complètent et se vérifient tous contre des JSON Schemas publiés.
• Validation côté serveur. Express / Fastify / Spring / Flask / FastAPI / Echo s'intègrent tous avec des validateurs JSON Schema (AJV, jsonschema, fastjsonschema) pour rejeter les corps de requête malformés avant qu'ils n'atteignent la logique métier.
• Génération de code. Des outils comme quicktype, json-schema-to-typescript et datamodel-code-generator transforment un schéma en structs Go, types TypeScript, dataclasses Python, POJOs Java, etc., fournissant des types agnostiques en langage à partir d'une seule source.
• Documentation. Un schéma fait office de documentation lisible par machine pour toute donnée en forme de JSON que vous publiez.

Les drafts que vous verrez en pratique

La spécification de JSON Schema a été publiée comme une série de drafts. Le draft stable actuel est 2020-12 (selon la page de spec officielle : « The current version is 2020-12 »). Les drafts que vous pourriez rencontrer :

• Draft 4, ancien mais encore utilisé ; OpenAPI 3.0 utilisait un sous-ensemble étendu de JSON Schema Specification Wright Draft 00 (parfois appelé informellement Draft 5), proche mais pas identique à Draft 4.
• Draft 6, Draft 7, Draft 7 (2018) a été le draft de production dominant pendant des années et reste très courant dans le tooling legacy.
• Draft 2019-09, premier draft à utiliser la convention d'identifiant année-mois ; a introduit $defs à côté du mot-clé legacy definitions.
• Draft 2020-12, le draft stable actuel et ce que ce générateur émet. Aligné avec OpenAPI 3.1.

En cas de doute, choisissez le draft qui correspond à votre validateur. AJV (le validateur JavaScript le plus populaire) supporte les Drafts 04, 06, 07, 2019-09 et 2020-12 avec opt-in explicite. jsonschema en Python fait pareil. Si vous ne savez pas ce que veut votre consommateur en aval, 2020-12 est un défaut sûr pour du nouveau travail.

Les types intégrés

JSON Schema décrit sept types de base correspondant aux sortes de valeurs JSON :

Les mots-clés de composition vous permettent de mélanger : oneOf (exactement un), anyOf (au moins un), allOf (tous), not (l'inverse). Plus enum pour une liste finie de valeurs autorisées et const pour une seule valeur fixe.

Ce qu'un schéma auto-généré peut et ne peut pas vous dire

Inférer un schéma à partir d'un seul exemple JSON est puissant mais limité. Le générateur peut détecter :

• Le type de chaque valeur feuille (string vs number vs boolean vs array vs object).
• La structure des objets et tableaux imbriqués.
• Les clés qui apparaissent dans l'exemple (et les marquer required si vous l'activez).

Il ne peut pas détecter :

• Champs optionnels. Une clé dans votre exemple peut être optionnelle dans la spec réelle, mais un seul exemple ne peut pas vous dire laquelle. Tout a l'air requis par défaut.
• Indices de format. La chaîne "2024-04-12" ressemble à une date, mais ça pourrait aussi être un libellé en texte libre qui se trouve avoir l'air d'une date. Ajoutez format: date à la main si le champ en est vraiment une.
• Contraintes de validation. Longueur max, valeurs enum autorisées, motifs regex : tout ça nécessite une saisie humaine.
• Chaînes de documentation. title, description et examples sur chaque champ améliorent l'expérience développeur mais nécessitent du soin.
• Variantes. Si un champ peut être soit une chaîne soit un nombre selon le contexte, un seul exemple en choisira un et ratera l'autre. Combinez plusieurs exemples ou utilisez oneOf à la main.

Traitez la sortie comme un point de départ fait à 70 %. Les ajouts précieux (quels champs sont réellement requis, quels formats de chaîne s'appliquent, quelles plages de valeurs sont autorisées, ce que chaque champ signifie) sont l'étape de curation humaine.

Deux pièges subtils à connaître

• format est consultatif par défaut en 2020-12. Le vocabulaire format-annotation marque format: email comme un indice, pas comme une règle de validation stricte, à moins que votre validateur ne s'inscrive explicitement dans format-assertion. Donc une chaîne qui ne correspond pas à la regex e-mail passe quand même par défaut. Le mode strict d'AJV et le package ajv-formats ajoutent une validation de format complète ; vérifiez les défauts de votre validateur avant de vous reposer sur des contrôles de format pour des entrées critiques côté sécurité.
• additionalProperties: false ne coopère pas bien avec allOf. Si vous composez des schémas avec allOf pour une validation style héritage, additionalProperties: false sur une branche ne voit pas les propriétés définies dans des branches sœurs, donc des champs légitimes échouent à la validation. Le correctif en Draft 2019-09+ est unevaluatedProperties: false, qui est conscient de la composition.

JSON Schema vs Zod / Joi / Yup vs types TypeScript

Plusieurs technologies se chevauchent avec le rôle de JSON Schema ; chacune a un sweet spot différent :

• JSON Schema. JSON déclaratif, validation à l'exécution, agnostique en langage. Gagne là où les contrats d'API traversent les frontières linguistiques (par ex. un serveur Go, un pipeline de données Python et un frontend TypeScript consommant tous la même API).
• Types TypeScript. Au moment de la compilation seulement. Magnifiques pour la sécurité de type intra-processus dans une codebase TS mais ils disparaissent à l'exécution, ne fournissant aucune validation du JSON entrant. Des outils comme json-schema-to-typescript génèrent des types depuis un schéma pour le meilleur des deux mondes.
• Zod / Joi / Yup. Validation à l'exécution code-first en JavaScript / TypeScript, avec inférence TypeScript intégrée. Un seul langage, mais une excellente expérience développeur dans ce langage. Les schémas sont des objets JS, pas du JSON portable.
• Pydantic / Marshmallow. Les équivalents Python : validation à l'exécution basée sur les classes avec les annotations de type Python.

Si votre schéma doit être consommé par plusieurs langages ou par des outils (IDEs, tooling OpenAPI, générateurs de code), JSON Schema est le bon foyer. Si vous restez dans un seul langage, l'option native de ce langage est généralement plus agréable à écrire.

Cas d'usage courants

• Bootstrap d'une spec OpenAPI. Collez une vraie réponse d'API, générez le schéma, déposez-le dans votre components.schemas.
• Génération de types TypeScript / Go / Python via quicktype ou similaire, fournissant des types agnostiques en langage à partir d'une seule source.
• Validation d'entrées non fiables sur un endpoint serveur avec AJV / jsonschema / Pydantic.
• Écrire de l'auto-complétion IDE pour un format de configuration personnalisé. VS Code, les IDEs JetBrains et d'autres lisent les JSON Schemas pour alimenter l'auto-complétion des fichiers JSON.
• Documenter la forme d'un fichier de configuration pour les consommateurs en aval.
• Migrer entre formats de données. Un JSON Schema généré depuis une source peut piloter la validation, la transformation ou la documentation en aval.

Erreurs courantes

1. Traiter le schéma auto-généré comme la spec finale. C'est un point de départ. Ajoutez des indices de format, marquez les champs vraiment optionnels, ajoutez de la documentation, fixez les plages de valeurs.
2. Manquer la déclaration $schema. Les validateurs l'utilisent pour savoir quel draft appliquer. Incluez-la toujours en haut du schéma.
3. Traiter required comme un attribut par propriété. Contrairement à XSD ou aux schémas Mongoose, le required de JSON Schema est un tableau au niveau de l'objet parent listant les noms des propriétés requises.
4. Oublier additionalProperties: false quand vous voulez une validation stricte. Le défaut est true, ce qui signifie que les clés inconnues sont silencieusement autorisées.
5. Confondre enum avec examples. enum = la liste des valeurs autorisées (validation). examples = des valeurs d'exemple pour la documentation seulement (aucun effet de validation).
6. Supposer que format est appliqué. Par défaut en Draft 2020-12 c'est une annotation, pas une assertion ; votre regex e-mail ne tournera pas tant que vous n'optez pas dedans.
7. Inférer l'optionalité depuis un seul exemple. Chaque clé de votre exemple devient requise par défaut. Les vraies specs ont presque toujours des champs optionnels ; retirez-les du tableau required dans le cadre de la curation.

Questions fréquentes supplémentaires

Le schéma fonctionnera-t-il avec OpenAPI 3.1 ?

Oui. OpenAPI 3.1 (sorti en février 2021) a aligné son langage de schéma entièrement avec JSON Schema Draft 2020-12, qui est ce que ce générateur émet. Déposez le schéma dans components.schemas dans votre document OpenAPI et référencez-le via $ref. L'ancien OpenAPI 3.0 utilisait un sous-ensemble antérieur ; vous pourriez avoir à ajuster si vous ciblez 3.0.

Puis-je générer des types dans mon langage à partir de ce schéma ?

Oui. quicktype génère TypeScript, Go, Python, Java, C#, Swift, Kotlin, Rust, Elm et d'autres à partir d'un JSON Schema. json-schema-to-typescript est une alternative spécifique à JS. La plupart des langages modernes ont au moins un outil schema-to-types ; le schéma généré sert d'entrée à tous.

Quelle est la différence entre $defs et definitions ?

Les deux sont des endroits pour mettre des sous-schémas réutilisables que vous pouvez $ref ailleurs dans le document. definitions est le nom legacy, utilisé en Drafts 04, 06 et 07. $defs est le nom actuel, introduit en Draft 2019-09 et continuant en 2020-12. Fonctionnellement équivalents, mais utilisez $defs pour du nouveau travail.

Mon JSON est-il envoyé quelque part ?

Non. La génération de schéma tourne entièrement dans votre navigateur. Le JSON collé est parsé localement, parcouru et émis comme un schéma dans la zone de texte de sortie. Rien n'est téléversé vers un serveur, journalisé ou conservé après la fermeture de l'onglet. Cela compte parce que les exemples JSON contiennent souvent des données réelles (enregistrements clients, réponses d'API internes, infos employés) que vous ne voulez pas voir transiter par un tiers.

Pourquoi le schéma de mon tableau ne décrit-il que le premier élément ?

L'inférence depuis un seul exemple traite les tableaux comme homogènes : elle regarde le premier élément et suppose que le reste correspond. Si votre vrai tableau peut contenir des formes différentes, vous devrez écrire les items comme { "oneOf": [...] } à la main. Ou faire tourner le générateur sur chaque variante séparément et combiner les schémas.

Devrais-je utiliser un générateur du tout, ou écrire le schéma à la main ?

Pour un petit schéma que vous contrôlez de bout en bout, l'écrire à la main vous apprend la spec plus vite. Pour une grosse réponse d'API avec des dizaines d'objets imbriqués, générer vous amène à un brouillon en quelques secondes et vous passez le temps gagné à curer les contraintes, descriptions et tableaux required. La plupart des développeurs en activité font les deux : générer, puis curer.