JSON Schema

JSON Schema è un modo standard per descrivere come deve essere un documento JSON valido: quali proprietà esistono, i loro tipi, quali sono obbligatorie, i valori e i formati ammessi. Un validatore controlla poi i dati reali rispetto allo schema e segnala ogni violazione. Per chi testa le API, trasforma “la risposta sembra giusta” in un unico controllo ripetibile sull’intera forma della risposta. La versione attuale della specifica è la draft 2020-12; la draft-07 è ancora molto diffusa.

Esempio

Uno schema per un utente restituito da GET /users/{id}:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email", "role", "createdAt"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "role": { "enum": ["admin", "member", "viewer"] },
    "createdAt": { "type": "string", "format": "date-time" },
    "nickname": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}

Validazione in Node con Ajv (ajv/dist/2020 supporta la draft 2020-12, e ajv-formats aggiunge email e date-time):

import Ajv2020 from 'ajv/dist/2020';
import addFormats from 'ajv-formats';

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(userSchema);

if (!validate(responseBody)) {
  console.log(validate.errors);
}

In Java, il modulo json-schema-validator di REST Assured fornisce matchesJsonSchemaInClasspath("schemas/user.json") da usare dentro .body(...). Controlla quale draft supporta il tuo validatore prima di usare le parole chiave più recenti.

Perché è importante

• Un’unica asserzione copre l’intera forma. Campi mancanti, tipi errati e null inattesi vengono intercettati senza scrivere un controllo per ogni campo.
• Intercetta le fughe di dati. "additionalProperties": false fallisce se la risposta all’improvviso include qualcosa come passwordHash.
• Documenta il contratto. Le specifiche OpenAPI usano JSON Schema per descrivere i body di richieste e risposte.

Errori comuni

• Schemi che accettano qualsiasi cosa. Uno schema senza required passa anche con {}. Elenca sempre i campi obbligatori.
• Dare per scontato che format venga applicato. Molti validatori trattano format come una semplice annotazione, a meno che la validazione dei formati non sia attivata.
• Validare solo lo schema. Una risposta può rispettare lo schema e contenere comunque l’utente sbagliato. Mantieni le asserzioni sui valori per i dati che contano.