Un schéma généré à partir d’un document exemple décrit ce qui était dans l’exemple. C’est un point de départ, pas une spécification imposée d’ailleurs, et cet outil est construit pour le traiter de cette façon plutôt que de suggérer plus de certitude que les données ne soutiennent réellement.
Utiliser le générateur de JSON Schema
Collez un document, ou un tableau de plusieurs enregistrements, choisissez un brouillon (2020-12 ou Draft 07), si détecter les formats de chaîne, et si marquer les clés requises, puis appuyez sur Générer schéma.
Étant donné
[
{"id": 1, "name": "a", "score": 1},
{"id": 2, "name": "b", "score": 1.5}
]les deux enregistrements portent id, name et score, donc les trois
apparaissent dans required. id est un nombre entier dans chaque
enregistrement et devient "integer". score a une fraction dans le
deuxième enregistrement, 1.5, donc son type est le plus large "number"
plutôt que "integer", car il contient réellement des valeurs non
entières.
Pourquoi une clé peut silencieusement sortir de required
Ajoutez un troisième enregistrement, {"id": 3, "name": "c"}, sans champ
score, et régénérez : score n’est plus requis, tandis que id et
name restent requis. Une clé n’est marquée requise que lorsque chaque
seul enregistrement du tableau la portait. Un enregistrement manquant un
champ ne prouve pas que le champ est optionnel dans toute votre API, mais
il prouve que le schéma ne peut pas honnêtement promettre qu’il sera
toujours là, donc il devient optionnel. C’est la seule règle que la FAQ
sur la page déclare directement, car c’est le détail le plus susceptible
de surprendre quelqu’un lisant le résultat.
Détection de format
Un format de chaîne comme une date ou une adresse e-mail n’est affirmé que lorsque chaque chaîne dans cette position dans chaque enregistrement correspond au même motif. C’est ce qui empêche une valeur chanceuse de transformer un champ de texte libre en quelque chose qui ressemble à un format de date strict, qui rejetterait ensuite des données réelles et valides dès qu’il verrait une valeur qui n’est pas réellement une date.
Ce que cela ne peut pas savoir
Le générateur n’a que les enregistrements que vous avez collés. Il ne
peut pas voir les enregistrements que vous n’avez pas collés, donc un
champ qui était toujours un nombre positif dans votre exemple n’aura pas
de minimum sauf si vous en ajoutez un vous-même, et un champ comme enum
ne deviendra pas un mot-clé enum sauf si vous l’ajoutez. Traitez la
sortie comme la forme que votre exemple prouve, et élargissez-la à la
main là où vous savez que les données réelles sont plus lâches.
Vérifier le résultat
Collez le schéma généré et un document dans le validateur JSON Schema pour voir s’il accepte réellement le type de documents que vous attendez.