Générateur de JSON Schema

Générez un JSON Schema à partir d’un payload d’exemple. Draft 2020-12 par défaut, avec 2019-09 et draft-07 disponibles.

Générer un schéma depuis un seul échantillon, c’est de l’inférence, et l’inférence est l’endroit où ces outils mentent discrètement. Chaque supposition faite ici vous est rapportée, et la plus importante est traitée autrement que par la plupart des générateurs.

Le problème des champs obligatoires

La plupart des générateurs lisent le premier élément d’un tableau et prennent ses clés pour la forme. Cela produit un schéma qui rejette des données valides dès qu’un enregistrement ultérieur possède un champ optionnel absent du premier.

Ce générateur fusionne tous les éléments. Une clé présente dans tous entre dans required ; une clé présente dans certains apparaît dans properties mais pas dans required. Cette seule différence est la raison d’utiliser un générateur plutôt que d’écrire le schéma à la main après un coup d’œil au payload.

Les autres inférences, toutes signalées

integer face à number

Un champ n’est typé integer que lorsque toutes les valeurs observées l’étaient. Une seule décimale quelque part fait du champ entier un number.

Champs nullables

Un champ vu à la fois comme chaîne et comme null devient "type": ["string", "null"], et non un champ supprimé ni un simple "string".

format

Émis uniquement quand toutes les valeurs observées correspondent : date-time, date, time, email, uuid, ipv4 ou uri. Une seule valeur non conforme et l’annotation disparaît.

enum

Suggéré plutôt que supposé, et seulement quand un petit ensemble de valeurs se répète. Désactivé par défaut, car un enum inféré depuis un échantillon est une supposition sur un domaine que vous n’avez pas vu en entier.

Entiers non sûrs

Typés integer et signalés, car un validateur tournant sur un analyseur JavaScript a déjà perdu la valeur avant même de commencer à valider.

Le mot-clé format ne valide pas

Cela surprend et met en production des validations cassées. En draft 2019-09 et draft 2020-12, format est par défaut une ANNOTATION et non une assertion. La plupart des validateurs accepteront sans broncher "pas-un-email" pour un champ marqué "format": "email", à moins d’activer explicitement l’assertion de format.

S’il vous faut une vraie contrainte, ajoutez un pattern explicite à côté du format, ou configurez votre validateur en mode assertion et vérifiez qu’il le prend en charge.

Une mise en garde sur la validation du résultat

Si vous portez ce schéma vers Ajv, le validateur JavaScript le plus courant, attention au point d’entrée. L’export ajv par défaut ne prend en charge que draft-07. Draft 2020-12 exige ajv/dist/2020 et 2019-09 exige ajv/dist/2019.

Se tromper là-dessus fait valider un schéma 2020-12 utilisant prefixItems avec la sémantique de draft-07, où prefixItems est un mot-clé inconnu et donc ignoré. Votre validateur annonce alors « valide » sur des données qui ne le sont pas. C’est pire qu’une erreur, et cela arrive facilement par inadvertance.

How to do this in code

Générer et valider en code.

// The entry point matters. This is the 2020-12 one.
import Ajv2020 from 'ajv/dist/2020';
import addFormats from 'ajv-formats';

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);   // without this, "format" does nothing at all

const validate = ajv.compile(schema);
if (!validate(data)) console.error(validate.errors);

from jsonschema import Draft202012Validator

validator = Draft202012Validator(schema)
for error in sorted(validator.iter_errors(data), key=lambda e: e.path):
    print(list(error.path), error.message)

# Format checking is opt-in here too
from jsonschema import FormatChecker
Draft202012Validator(schema, format_checker=FormatChecker()).validate(data)

import "github.com/santhosh-tekuri/jsonschema/v6"

c := jsonschema.NewCompiler()
sch, err := c.Compile("schema.json")
if err := sch.Validate(data); err != nil {
    fmt.Println(err)
}

Questions fréquentes

Quel draft utiliser ?

Draft 2020-12 pour tout ce qui est neuf ; c’est le draft publié actuel et celui sur lequel OpenAPI 3.1 s’aligne. draft-07 reste le mieux pris en charge par l’outillage plus ancien. Notez que l’identifiant 2020-12 renvoie à la date où le draft a été figé : les documents à cette URI ont été republiés pour la dernière fois en juin 2022, ce qui est un correctif et non une nouvelle version.

Pourquoi un champ manque-t-il dans required ?

Parce qu’il était absent d’au moins un échantillon. C’est le générateur qui vous dit quelque chose d’utile. Si le champ est réellement obligatoire, donnez-lui un échantillon où chaque enregistrement le possède, ou ajoutez-le à required à la main.

Peut-il générer à partir de plusieurs échantillons ?

Oui, et vous devriez. Mettez vos échantillons dans un tableau et collez le tableau. Fusionner sur de nombreux enregistrements est exactement ce qui rend required et la nullabilité exacts.