# Validation JSON Schema

JSON Schema Validate vérifie qu’une valeur runtime possède la structure JSON attendue avant que le workflow ne l’utilise. Placez-le après un Agent, un webhook, une requête HTTP, un Database Query, un Transform ou tout nœud dont la sortie peut être incomplète ou incorrecte.

Le nœud utilise un sous-ensemble JSON Schema sûr et déterministe. Il n’appelle aucun modèle IA et ne modifie pas les données valides.

## Workflow typique

```text
Database Query ou API
  ↓
JSON Schema Validate
  ├── valide → suite normale du workflow
  └── invalide → arrêt, continuation ou branche d’erreur
```

Le validateur doit être relié au nœud qui produit les données. Un nœud simplement posé sur le canvas sans arête entrante n’est pas exécuté dans ce chemin.

## Configuration

| Champ | Rôle |
| --- | --- |
| **Input field** | Chemin du contexte contenant la valeur à valider. Valeur par défaut : `last_output`. |
| **JSON Schema** | Objet JSON décrivant la valeur autorisée. L’éditeur attend un JSON valide. |
| **On invalid** | `Follow error branch`, `Stop this path` ou `Continue`. |
| **Max errors** | Nombre maximal d’erreurs retournées, de 1 à 100. Valeur par défaut : 20. |

### Constructeur visuel

Cliquez sur **Construire le schéma visuellement** pour définir un objet sans écrire de JSON :

- ajouter, renommer ou supprimer des propriétés ;
- choisir Texte, Nombre, Booléen, Enum, Objet ou Tableau ;
- rendre chaque propriété obligatoire ou optionnelle ;
- ajouter des champs imbriqués aux objets et tableaux d’objets ;
- choisir si les champs non déclarés sont acceptés ;
- passer à l’éditeur JSON avancé pour des contraintes comme `pattern`, `minimum` ou `maxItems`.

Le constructeur génère automatiquement le JSON Schema. Il est disponible dans JSON Schema Validate et dans le mode JSON Schema d’Output Parser.

### Que signifie additionalProperties ?

`"additionalProperties": false` refuse les clés absentes de `properties`. Si le schéma déclare uniquement `name` et `email`, un payload contenant `phone` est invalide. Activez **Autoriser les champs supplémentaires** dans le constructeur visuel — ou utilisez `true` — pour accepter des clés supplémentaires.

## Exemples de chemins Input field

| Chemin | Valeur sélectionnée |
| --- | --- |
| `last_output` | Sortie parsée du nœud précédent |
| `input` | Entrée initiale du workflow |
| `input.customer` | Champ imbriqué de l’entrée initiale |
| `event.body` | Corps d’un webhook ou déclencheur |
| `state.customer` | Valeur créée par Set state |
| `database_query.rows` | Lignes du dernier Database Query |
| `outputs.node-id.parsed` | Sortie structurée archivée d’un nœud nommé |

Lorsque `last_output` contient du texte JSON, le nœud le parse avant validation. Si le nœud précédent a déjà produit une donnée structurée, cette valeur est utilisée directement.

## Mots-clés supportés

Le moteur prend actuellement en charge :

| Mot-clé | S’applique à | Exemple |
| --- | --- | --- |
| `type` | Toutes les valeurs | `"object"`, `"array"`, `"string"`, `"integer"`, `"number"`, `"boolean"`, `"null"` |
| Tableau de types | Toutes les valeurs | `{"type":["string","null"]}` |
| `properties` | Objets | Décrit les champs enfants |
| `required` | Objets | Liste les champs obligatoires |
| `additionalProperties: false` | Objets | Refuse les champs non déclarés |
| `items` | Tableaux | Valide chaque élément |
| `minItems`, `maxItems` | Tableaux | Limite la taille du tableau |
| `enum` | Toutes les valeurs | Limite aux valeurs autorisées |
| `minLength`, `maxLength` | Chaînes | Limite la longueur du texte |
| `pattern` | Chaînes | Applique une expression régulière |
| `minimum`, `maximum` | Nombres | Limite la plage numérique |

Les mots-clés `$ref`, `oneOf`, `anyOf`, `allOf`, `const`, `format`, `uniqueItems` et les schémas conditionnels ne sont pas appliqués par ce nœud. Utilisez les contraintes supportées ou un Transform pour une validation avancée.

## Exemple d’objet simple

Payload :

```json
{
  "name": "Awa Ndiaye",
  "email": "awa@example.com",
  "age": 28,
  "status": "active"
}
```

Schéma :

```json
{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": {
      "type": "string",
      "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
    },
    "age": { "type": "integer", "minimum": 18 },
    "status": { "type": "string", "enum": ["active", "inactive"] }
  },
  "required": ["name", "email", "status"],
  "additionalProperties": false
}
```

`required` indique si le champ doit exister. Un champ présent dans `properties` mais absent de `required` reste optionnel.

## Exemple de tableau

Pour valider directement `database_query.rows` :

```json
{
  "type": "array",
  "minItems": 1,
  "maxItems": 100,
  "items": {
    "type": "object",
    "properties": {
      "id": { "type": "integer" },
      "name": { "type": "string", "minLength": 1 },
      "status": { "type": "string", "enum": ["active", "inactive"] }
    },
    "required": ["id", "name", "status"],
    "additionalProperties": false
  }
}
```

## Exemple complet avec Database Query

Avec **Input field** réglé sur `last_output`, Database Query fournit une enveloppe. Validez-la avec :

```json
{
  "type": "object",
  "properties": {
    "database_type": { "type": "string", "enum": ["postgres"] },
    "row_count": { "type": "integer", "minimum": 0 },
    "fields": {
      "type": "array",
      "items": { "type": "string" }
    },
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string", "minLength": 1 },
          "email": { "type": "string" },
          "status": { "type": "string" },
          "order_count": { "type": "integer", "minimum": 0 },
          "total_amount": { "type": ["string", "number"] }
        },
        "required": ["id", "name", "email", "status", "order_count", "total_amount"],
        "additionalProperties": false
      }
    },
    "truncated": { "type": "boolean" },
    "max_rows": { "type": "integer", "minimum": 1 }
  },
  "required": ["database_type", "row_count", "fields", "rows", "truncated", "max_rows"],
  "additionalProperties": false
}
```

Les valeurs décimales d’une base peuvent être sérialisées en chaînes, d’où le type `["string", "number"]` pour `total_amount`.

## Comportement lorsque les données sont invalides

### Follow error branch

Marque le nœud en échec et emprunte une arête d’erreur. Reliez cette sortie à une notification, un fallback ou une étape de correction. Sans branche d’erreur connectée, le chemin s’arrête.

### Stop this path

Arrête immédiatement le chemin courant. Les branches indépendantes peuvent continuer.

### Continue

Continue sur la sortie normale malgré l’échec de validation. L’erreur et les détails restent visibles dans la trace et la sortie structurée. Ce mode convient aux premiers tests ou lorsqu’un nœud aval traite explicitement l’erreur.

## Sortie runtime

Le résultat structuré possède cette forme :

```json
{
  "valid": true,
  "errors": [],
  "data": {},
  "input_path": "last_output"
}
```

En cas de succès :

- `last_output` reste le payload validé ;
- `last_output_parsed` contient le résultat de validation ci-dessus ;
- ce résultat est également disponible dans `schema_validation` ;
- la sortie nommée est accessible avec `{outputs.<node_id>.parsed.data}`.

En cas d’échec :

- `last_output` devient un message lisible `JSON Schema Validate Error` ;
- `last_output_parsed.valid` vaut `false` ;
- `last_output_parsed.errors` liste les chemins comme `$.rows[0].email` ;
- `last_output_parsed.data` conserve le payload refusé pour le diagnostiquer ou le corriger.

## Dépannage

| Symptôme | Cause | Correction |
| --- | --- | --- |
| Le nœud n’apparaît jamais dans la trace | Il n’est pas relié au chemin producteur | Ajoutez une arête entrante et une arête sortante |
| La racine indique « expected object, got list » | La valeur sélectionnée est un tableau | Utilisez `type: array` ou sélectionnez le bon chemin objet |
| L’entrée de validation est vide | Input field pointe vers un chemin absent | Inspectez la sortie précédente et corrigez Input field |
| Chaque ligne signale des champs supplémentaires | `additionalProperties: false` est plus strict que le payload réel | Ajoutez les champs à `properties` ou retirez cette contrainte |
| Le `format` email est ignoré | `format` n’appartient pas au sous-ensemble supporté | Utilisez une expression `pattern` |
| Un décimal valide échoue comme nombre | Le pilote de base l’a sérialisé en texte | Acceptez `["string", "number"]` ou convertissez-le avec Transform |
| Seules certaines erreurs apparaissent | Max errors a tronqué la liste | Augmentez Max errors, jusqu’à 100 |

## Exemple de workflow

Utilisez la carte ci-dessous pour créer un exemple exécutable. Set State charge un objet client, puis JSON Schema valide ses champs obligatoires.

---

*Source: https://agentbuilder.systalink.sn/docs/node-json-schema-validate — human documentation.*
*Other language: [/docs-md/en/node-json-schema-validate.md](/docs-md/en/node-json-schema-validate.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*