Validation JSON : JSON Schema, erreurs de validation

1. Pourquoi valider le JSON

Imaginons que vous avez écrit une classe User et que vous vous attendez à recevoir en entrée un JSON de ce type :

{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com"
}

Mais soudain, vous recevez ceci :

{
  "id": "quarante-deux",
  "name": 123,
  "email": null,
  "admin": true
}

Ou même :

{
  "username": "Alice"
}

Dans le meilleur des cas, Jackson ou Gson lèveront une exception lors de la tentative de désérialisation. Dans le pire — ils attribueront silencieusement des valeurs par défaut aux champs, et votre code métier commencera à se comporter de manière incorrecte. Et si c’est une configuration pour votre service — vous risquez des bugs amusants que toute l’équipe traquera ensuite.

La validation JSON est le processus qui consiste à vérifier que la structure, les types et les valeurs des données JSON respectent des règles définies (un schéma). C’est comme un contrôle de passeport pour les données : qui ne passe pas — ne monte pas à bord !

2. JSON Schema : qu’est-ce que c’est et à quoi ça ressemble

Dans l’écosystème JSON, il existe une norme officielle pour décrire la structure des données — JSON Schema. C’est une « check-list » permettant de vérifier que le JSON correspond aux exigences de votre programme.

JSON Schema est lui-même un JSON, mais avec des clés spéciales : type, properties, required, etc.

Exemple du schéma le plus simple

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "name"]
}

Ce qui se passe ici :

• On attend un objet (type : "object").
• L’objet peut avoir les champs "id", "name", "email" (décrits dans properties).
• "id" — doit être un entier (type : "integer").
• "name" — doit être une chaîne (type : "string").
• "email" — une chaîne ayant la forme d’un email (clé format avec la valeur "email").
• required indique la liste des champs obligatoires : "id" et "name".

Si le JSON ne contient pas "id" ou "name", ou si leur type n’est pas correct — la validation échouera.

Aperçu des possibilités de JSON Schema

• Spécification du type (type : "string", "integer", "array", "object", "boolean", "null").
• Description des objets et tableaux imbriqués (properties, items).
• Champs obligatoires et facultatifs (required).
• Vérification de la longueur des chaînes, de la plage de nombres (minLength, maximum, etc.).
• Vérification du format (format : "email", "date", "uri", etc.).
• Énumérations (enum : liste des valeurs autorisées).
• Expressions régulières pour les chaînes (pattern).
• Conditions complexes : anyOf, oneOf, allOf (pour les cas avancés).

3. Validation JSON en Java : panorama des bibliothèques

La validation JSON par schéma ne fait pas partie de la bibliothèque standard Java. Mais il existe des bibliothèques tierces populaires. Voici les plus connues :

• everit-org/json-schema — simple, gratuite et populaire.
• networknt/json-schema-validator — rapide, prend en charge les dernières normes.
• Jackson-module-jsonSchema — une extension pour Jackson (mais ne prend pas en charge une validation complète).
• Justify, Java JSON Tools — il en existe d’autres, mais elles sont moins répandues.

Dans ce cours, nous allons voir everit-org/json-schema — elle est simple pour les débutants, bien documentée et ne nécessite pas de configurations complexes.

Installation de everit-org/json-schema

Ajoutez la dépendance à votre pom.xml (Maven) :

<dependency>
  <groupId>org.everit.json</groupId>
  <artifactId>org.everit.json.schema</artifactId>
  <version>1.14.2</version>
</dependency>

Ou via Gradle :

implementation 'org.everit.json:org.everit.json.schema:1.14.2'

4. Exemple : validation JSON selon un schéma (pas à pas)

Essayons de valider un JSON en pratique. Pour cela, il nous faut le schéma, le JSON et un peu de code.

Exemple de schéma (user-schema.json) :

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string", "minLength": 2, "maxLength": 30 },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "name"]
}

Exemple de JSON valide (user.json) :

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

Exemple de JSON non valide :

{
  "id": "un",
  "name": "",
  "email": "not-an-email"
}

Code de validation

import org.everit.json.schema.Schema;
import org.everit.json.schema.loader.SchemaLoader;
import org.json.JSONObject;
import org.json.JSONException;
import org.json.JSONTokener;
import org.everit.json.schema.ValidationException;

import java.nio.file.Files;
import java.nio.file.Paths;

public class JsonValidationExample {
    public static void main(String[] args) throws Exception {
        // Chargement du schéma depuis un fichier
        String schemaString = new String(Files.readAllBytes(Paths.get("user-schema.json")));
        JSONObject rawSchema = new JSONObject(new JSONTokener(schemaString));
        Schema schema = SchemaLoader.load(rawSchema);

        // Chargement du JSON à valider
        String jsonString = new String(Files.readAllBytes(Paths.get("user.json")));
        JSONObject json = new JSONObject(new JSONTokener(jsonString));

        // Validation
        try {
            schema.validate(json); // Si tout est OK — rien ne se passera
            System.out.println("JSON est valide !");
        } catch (ValidationException e) {
            System.out.println("JSON N'EST PAS valide !");
            for (String msg : e.getAllMessages()) {
                System.out.println("Erreur : " + msg);
            }
        }
    }
}

Commentaires sur le code :

• On utilise la classe Schema et le chargeur SchemaLoader.load(...).
• La méthode schema.validate(json) lève une exception si le JSON ne correspond pas au schéma.
• Dans le bloc catch, on peut obtenir toutes les erreurs via getAllMessages().

Comment l’intégrer dans une application ?

En général, le schéma est stocké dans les ressources (par exemple, dans le dossier resources). Vous validez le JSON avant la désérialisation en objet Java. Si tout va bien — vous désérialisez et continuez.

5. Gestion des erreurs de validation

Lorsque le JSON échoue à la vérification, la bibliothèque lève l’exception ValidationException. Le message contient une liste d’erreurs : ce qui ne correspond pas au schéma.

Exemple de sortie d’erreurs

Pour le JSON non valide ci-dessus, la sortie ressemblera à ceci :

JSON N'EST PAS valide !
Erreur: #: required key [id] not found
Erreur: #/name: expected minLength: 2, actual: 0
Erreur: #/email: String [not-an-email] is invalid against requested format [email]
Erreur: #/id: expected type: Integer, found: String

Comment interpréter les erreurs :

• required key [id] not found — champ obligatoire manquant.
• expected minLength: 2, actual: 0 — chaîne trop courte.
• String [...] is invalid against requested format [email] — email non valide.
• expected type: Integer, found: String — type non conforme.

Important ! Les messages peuvent être en anglais, mais ils sont très explicites.

Comment afficher les erreurs à l’utilisateur ?

Vous pouvez rassembler les erreurs dans une liste et la renvoyer à l’utilisateur, par exemple via un REST API ou un GUI. Cela permettra de comprendre rapidement ce qui ne va pas avec les données d’entrée.

6. Pratique : validation d’un tableau d’objets

Il arrive souvent qu’il faille valider non pas un seul objet, mais un tableau :

[
  { "id": 1, "name": "Alice", "email": "alice@example.com" },
  { "id": 2, "name": "Bob" },
  { "id": "c'est quoi ?", "name": 123, "email": "not-an-email" }
]

Schéma :

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id":    { "type": "integer" },
      "name":  { "type": "string", "minLength": 2, "maxLength": 30 },
      "email": { "type": "string", "format": "email" }
    },
    "required": ["id", "name"]
  }
}

La validation fonctionne de la même manière, sauf qu’on passe un tableau en tant que JSON. Les erreurs indiqueront les index des éléments où quelque chose ne va pas (par exemple, [#/2/id]).

7. Erreurs courantes lors de la validation JSON

Erreur n° 1 : Inadéquation des types de données. Très souvent, une chaîne arrive à la place d’un nombre ("id": "123"), alors que le schéma attend un integer. La validation échouera. Si vous ne maîtrisez pas la source des données — soit adaptez le schéma, soit convertissez les données en amont.

Erreur n° 2 : Champs obligatoires manquants. Si le schéma indique qu’un champ est obligatoire ("required" : ["id","name"]) et qu’il manque dans le JSON — vous obtiendrez une erreur. Cela peut parfois surprendre : le frontend a oublié d’envoyer le champ ou l’API a changé.

Erreur n° 3 : Champs superflus dans le JSON. Par défaut, JSON Schema autorise les champs supplémentaires. Si vous voulez un schéma strict, n’oubliez pas d’ajouter "additionalProperties" : false. Sans cela, le JSON peut contenir n’importe quels champs « hors-sujet ».

Erreur n° 4 : Mauvaise version de schéma ou syntaxe. Si vous utilisez des clés absentes de votre version du schéma ou faites des fautes de frappe, le validateur ne pourra pas charger le schéma. Vérifiez le schéma sur https://www.jsonschemavalidator.net/ ou des services similaires.

Erreur n° 5 : Mauvaise gestion des erreurs. Si vous vous contentez d’attraper la première exception sans détailler pour l’utilisateur, il sera difficile de comprendre ce qui ne va pas avec le JSON. Utilisez getAllMessages() pour afficher toutes les erreurs.

Erreur n° 6 : Formats trop stricts. La vérification "format" : "email" ou "date" peut être assez « superficielle ». Si vous avez besoin d’une validation stricte, utilisez des contrôles supplémentaires dans le code.