Valider les données JSON avant de générer un document

Le PDF ne doit pas découvrir les erreurs métier

Sans validation, un payload incomplet peut produire un document techniquement valide mais inutilisable : facture sans numéro, contrat sans signataire ou tableau sans devise. Le moteur PDF n’est pas le bon endroit pour décider si ces données ont un sens.

La validation doit intervenir avant le rendu, avec un contrat lisible par l’application qui envoie les données et par le service qui génère le document.

Décrire la forme attendue

JSON Schema permet de décrire les objets, types, champs obligatoires, formats et contraintes simples.

{
  "type": "object",
  "required": ["invoice", "customer", "items"],
  "properties": {
    "invoice": {
      "type": "object",
      "required": ["number", "date"],
      "properties": {
        "number": { "type": "string", "minLength": 1 },
        "date": { "type": "string", "format": "date" }
      }
    },
    "items": { "type": "array", "minItems": 1 }
  }
}

Le schéma ne remplace pas les règles métier profondes. Il peut vérifier qu’un total est un nombre, mais votre service de facturation reste responsable de son calcul.

Retourner des erreurs actionnables

Une erreur utile identifie le chemin, la règle et une explication stable :

{
  "code": "DOCUMENT_PAYLOAD_INVALID",
  "errors": [
    { "path": "invoice.number", "rule": "required", "message": "Invoice number is required" }
  ]
}

N’insérez pas tout le payload dans les logs. Conservez l’identifiant de requête, la version du schéma et les chemins en erreur. Les données personnelles ou contractuelles doivent rester protégées.

Faire évoluer le schéma

Tous les changements ne se valent pas. Ajouter un champ facultatif est généralement compatible. Ajouter un champ obligatoire, supprimer une propriété utilisée ou modifier un type peut casser les intégrations existantes.

Une comparaison automatique entre deux versions peut classer le changement : compatible, additif ou breaking. En attendant cette automatisation, documentez chaque changement de schéma dans la revue de version.

Aligner schéma et template

Un champ déclaré mais jamais utilisé ajoute du bruit. Un binding utilisé dans le template mais absent du schéma crée une zone aveugle. Vérifiez les deux directions : tous les bindings doivent être déclarés et chaque champ obligatoire doit être justifié.

Les données d’exemple doivent valider le schéma. Elles servent à l’aperçu, aux tests et à la compréhension de l’intégration.

Checklist de validation

• La validation précède la création du job coûteux.
• Les erreurs exposent un chemin stable.
• Les logs évitent le payload complet.
• Le schéma est lié à une version du template.
• Les exemples sont eux-mêmes valides.
• Les changements incompatibles sont identifiés.
• Les règles métier restent dans le service qui les possède.

Questions fréquentes

Valider côté client ou côté API ?

Les deux peuvent être utiles. La validation côté client améliore l’expérience développeur ; l’API doit toujours valider à nouveau car elle ne peut pas faire confiance à l’appelant.

Faut-il rejeter les champs inconnus ?

Pour un contrat strict, oui. Pour une transition progressive, les tolérer peut faciliter l’évolution. La décision doit être explicite et testée.