Validatore JSON Schema

Cos'è un Validatore JSON Schema?

// A 5-line schema that catches three real bugs
const schema = {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
};

// Three bugs the schema catches:
const bad = { "id": "42", "age": 200 };
//   /id   → type: expected integer, got string
//   /email → required: missing
//   /age   → maximum: 200 > 150

// In Node:        new Ajv().compile(schema)(bad)  // false; ajv.errors has the paths
// In Python:      jsonschema.validate(bad, schema)
// In the browser: this tool — same errors, same paths, no install

Funzionalità principali

Esempi

{
  "id": 42,
  "email": "alice@example.com",
  "age": 30
}

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

{
  "id": "42",
  "age": 200
}

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "maximum": 150 }
  },
  "required": ["id", "email"]
}

{
  "type": "order.created",
  "data": { "orderId": "ORD-001234", "totalUsd": 49.99 }
}

{
  "oneOf": [
    {
      "properties": {
        "type": { "const": "order.created" },
        "data": {
          "type": "object",
          "properties": {
            "orderId": { "type": "string", "pattern": "^ORD-[0-9]{6}$" },
            "totalUsd": { "type": "number", "minimum": 0 }
          },
          "required": ["orderId", "totalUsd"]
        }
      },
      "required": ["type", "data"]
    },
    {
      "properties": {
        "type": { "const": "order.refunded" },
        "data": { "type": "object", "required": ["refundId"] }
      },
      "required": ["type", "data"]
    }
  ]
}

[
  { "sku": "A1", "qty": 3 },
  { "sku": "B2", "qty": 5 },
  { "sku": "A1", "qty": 3 }
]

{
  "type": "array",
  "minItems": 1,
  "uniqueItems": true,
  "items": {
    "type": "object",
    "properties": {
      "sku": { "type": "string", "pattern": "^[A-Z][0-9]+$" },
      "qty": { "type": "integer", "minimum": 1 }
    },
    "required": ["sku", "qty"]
  }
}

Come si usa

1. 1

   Incolla il tuo JSON Schema

   Inserisci il tuo schema nel pannello destro. Il validatore rileva automaticamente il draft dall'URI $schema se presente; altrimenti scegli Draft 2020-12, 2019-09 o Draft-07 dalla toolbar.

2. 2

   Incolla i tuoi dati JSON

   Inserisci il documento JSON che vuoi controllare nel pannello sinistro. La validazione si esegue mentre scrivi; gli input grandi (>200 KB) passano a un pulsante Validate manuale per mantenere la digitazione reattiva.

3. 3

   Leggi l'elenco degli errori

   Ogni errore ha un percorso JSON Pointer, una keyword e un messaggio di una riga. Clicca su un errore per saltare alla posizione nei tuoi dati, correggilo e guarda il contatore scendere in tempo reale.

Trappole comuni di JSON Schema

{ "qty": 1.0 }   schema: { "type": "integer" }   → error: not an integer

{ "qty": 1 }     schema: { "type": "integer" }   → valid

{ "properties": { "name": { "type": "string", "required": true } } }

{ "properties": { "name": { "type": "string" } }, "required": ["name"] }

{ "properties": { "id": { "type": "integer" } } }   accepts: { "id": 1, "foo": "bar", "x": null }

{ "properties": { "id": { "type": "integer" } }, "additionalProperties": false }

{ "type": "string", "nullable": true }   in 2020-12: nullable is just an unknown keyword

{ "type": ["string", "null"] }   in 2020-12: explicitly allows null

pattern: "[A-Z]+"   accepts: "helloX"   (because X matches)

pattern: "^[A-Z]+$"   accepts only: "HELLO"

oneOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → error: matches both

anyOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → valid

Casi d'uso comuni

Validazione richiesta API

Incolla un corpo di richiesta e lo schema del tuo endpoint prima del deploy. Intercetta le risposte 400 che i tuoi test non hanno coperto — campi required mancanti, tipi sbagliati, numeri fuori range.

Verifica payload webhook

Il vendor ha inviato un payload che il tuo handler rifiuta? Valida il payload reale contro il tuo schema, poi contro lo schema pubblicato del vendor. La differenza tra i due è il tuo bug.

Linting di file di configurazione

package.json, tsconfig.json, helm values.yaml — ogni file di configurazione ha uno schema pubblico. Incolla lo schema, incolla la configurazione, trova il typo. Salta il tentativi-ed-errori.

Test componenti OpenAPI

Estrai un componente di schema da un documento OpenAPI 3.1, incollalo qui, valida payload di esempio. Più veloce che tirare su un mock server, deterministico, nessun SDK richiesto.

Pre-flight invio form

Incolla un payload form di esempio prima di cablare la validazione frontend. Conferma che lo schema rifiuta ciò che ti aspetti, accetta ciò che ti aspetti, poi invia lo stesso schema a client e server.

Verifica contratto pipeline dati

L'output ETL è andato in deriva? Incolla una riga di esempio e lo schema a valle. Individua quale producer è cambiato e quali key si sono rotte prima che la pipeline ritenti 10.000 record.

Dettagli tecnici

Conforme a Draft 2020-12

Implementa la specifica Draft 2020-12 pubblicata — keyword, sistema di tipi, vocabolario format. Verificato contro l'output di Ajv 8.x e ajv-formats.

Percorsi errore JSON Pointer

Gli errori usano JSON Pointer RFC 6901 (/user/email/0). Ogni fallimento di keyword punta a una singola posizione risolvibile nei dati — nessuna ambiguità, nessuna ricerca per stringa.

Risoluzione interna $ref

Risolve i puntatori $ref all'interno di un singolo documento (#/$defs/foo, #/properties/bar). Cicli rilevati e segnalati. $ref HTTP esterni disabilitati per privacy.

Best Practice

Imposta sempre additionalProperties: false

Sui contratti di input (corpi di richiesta, file di configurazione, messaggi di coda) le key sconosciute sono di solito bug — typo, campi accidentali o sondaggi di un attaccante. Rifiutale per default.

Usa $defs per sotto-schemi riutilizzabili

Inlinare due volte la stessa forma porta a divergenza. Sposta le definizioni condivise in $defs e referenziale con $ref — un'unica fonte di verità, ogni modifica si applica ovunque.

Valida prima della logica di business

Esegui la validazione dello schema subito dopo JSON.parse, prima di toccare la struttura analizzata. Restringimento di tipo, default e persistenza presuppongono tutti che il contratto regga — assicurati che regga.

Domande frequenti