Validation JSON et bonnes pratiques de schéma

Pourquoi la validation JSON est importante

Les API sont la colonne vertébrale des applications modernes, et JSON en est la lingua franca. Mais sans validation appropriée, un JSON malformé ou malveillant peut faire planter votre service, corrompre votre base de données ou ouvrir des failles de sécurité. J'ai vu des pannes de production causées par un seul champ manquant ou un type inattendu. La validation JSON ne se limite pas à détecter les fautes de frappe : elle permet de faire respecter les contrats, d'améliorer les messages d'erreur et de protéger votre système.

Dans cet article, nous couvrons les bonnes pratiques concrètes pour concevoir des schémas JSON et valider les payloads. Que vous construisiez une API REST, un resolver GraphQL ou un microservice, ces principes vous aideront à mieux dormir la nuit.

1. Commencez par un schéma clair

Un schéma est le contrat de votre API. Il définit quels champs sont autorisés, leurs types et toutes les contraintes. Sans lui, vous avancez à l'aveugle. Utilisez JSON Schema (un vocabulaire standardisé) pour décrire vos données. Il est indépendant du langage et largement pris en charge.

Voici un exemple minimal pour un objet utilisateur :

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

Points clés : required garantit les champs obligatoires ; additionalProperties: false rejette les champs inconnus (utile pour les API strictes).

2. Validez tôt et souvent

Validez en amont, avant que votre logique métier ne s'exécute. Cela empêche les données invalides de se propager. En Node.js, vous pouvez utiliser des bibliothèques comme Ajv ; en Python, jsonschema ; en Go, gojsonschema. Validez toujours les requêtes entrantes et les réponses sortantes (pour détecter les bugs).

Exemple en Python :

from jsonschema import validate, ValidationError

try:
    validate(instance=request.json, schema=user_schema)
except ValidationError as e:
    return {"error": e.message}, 400

Retournez des messages d'erreur clairs : ils aident les clients à corriger les problèmes rapidement.

3. Concevez pour l'évolution

Les API changent. Votre schéma doit pouvoir accueillir des ajouts sans casser les clients. Suivez ces règles :

• Ne supprimez ni ne renommez jamais de champs sans incrémenter la version.
• Rendez les nouveaux champs optionnels sauf s'ils sont critiques.
• Utilisez le versioning dans votre URL (par ex. /v1/users) ou votre media type.
• Privilégiez les changements additifs : ajoutez des champs plutôt que de modifier ceux existants.

Cette approche s'aligne sur la loi de Postel : soyez conservateur dans ce que vous envoyez, libéral dans ce que vous acceptez. Mais ne soyez pas trop libéral : une validation stricte détecte les bugs tôt.

4. Gérez les types avec soin

JSON a peu de types : string, number, boolean, object, array, null. Attention à :

• Nombres : JSON ne distingue pas les entiers des flottants. Utilisez type: integer si vous avez besoin de nombres entiers.
• Dates : Utilisez des chaînes ISO 8601 (par ex. 2026-01-15T10:00:00Z) et validez avec format: date-time.
• Enums : Restreignez les valeurs à un ensemble connu pour éviter les états invalides.
• Null vs. absent : Décidez si null est autorisé. Souvent, omettre un champ vaut mieux qu'envoyer null.

5. Sécurisez votre validation

La validation est un contrôle de sécurité. Les attaquants peuvent envoyer des payloads surdimensionnés, des objets profondément imbriqués ou des types inattendus pour provoquer un déni de service. Atténuez avec :

• Limites de taille : Rejetez les payloads dépassant une certaine taille (par ex. 1 Mo).
• Limites de profondeur : Empêchez les JSON trop imbriqués (par ex. profondeur max 10).
• Schémas stricts : Interdisez les propriétés additionnelles pour éviter l'injection de champs inattendus.
• Assainissez les chaînes : Même après validation, échappez la sortie pour prévenir les XSS.

Validez également côté serveur : ne faites jamais confiance à la seule validation côté client.

6. Utilisez un tableau comparatif des bibliothèques de validation

Choisir la bonne bibliothèque dépend de votre langage et de vos besoins de performance. Voici une comparaison rapide :

Toutes ces bibliothèques implémentent JSON Schema, vos schémas sont donc portables.

7. Documentez votre schéma

Un schéma n'est utile que si les développeurs le comprennent. Générez la documentation de votre API à partir de votre schéma avec des outils comme OpenAPI (anciennement Swagger) ou le mot-clé description de JSON Schema. Incluez des exemples pour chaque champ.

Pour une inspection rapide, vous pouvez formater et valider manuellement du JSON à l'aide d'un formateur JSON. Cela aide à repérer les erreurs de syntaxe et les problèmes de structure avant de se lancer dans la validation de schéma.

8. Testez vos schémas

Les schémas sont du code : testez-les. Écrivez des tests unitaires avec des payloads valides et invalides pour vous assurer que vos règles de validation fonctionnent comme prévu. Des outils comme json-schema-test-suite peuvent vous aider. Envisagez également des tests de contrat entre services pour détecter les incompatibilités tôt.

FAQ

Qu'est-ce que JSON Schema et pourquoi l'utiliser ?

JSON Schema est un standard pour décrire la structure des données JSON. Il permet de définir des types, des champs obligatoires et des contraintes, ce qui active la validation et la documentation automatiques. Il est largement pris en charge dans tous les langages.

Comment gérer les propriétés additionnelles en validation JSON ?

Par défaut, JSON Schema autorise les propriétés additionnelles. Définissez additionalProperties: false pour rejeter les champs inconnus, ce qui améliore la sécurité et détecte les fautes de frappe. Cependant, soyez prudent avec l'évolution de l'API : des schémas stricts peuvent casser les clients qui envoient des champs supplémentaires.

Puis-je utiliser JSON Schema pour la validation des requêtes et des réponses ?

Absolument. Validez à la fois les requêtes entrantes et les réponses sortantes pour garantir l'intégrité des données. La validation des réponses détecte les bugs dans votre propre code avant qu'ils n'atteignent les clients.

Conclusion

La validation JSON et la conception de schémas sont fondamentales pour des API robustes. En définissant des schémas clairs, en validant tôt, en planifiant l'évolution et en sécurisant vos endpoints, vous construisez des systèmes fiables et maintenables. Commencez par un schéma, choisissez une bibliothèque de validation et testez minutieusement. Votre futur vous (et vos utilisateurs) vous remercieront.