Validatore JSON Schema

Cos'è la validazione di JSON Schema?

La validazione di JSON Schema è il processo di verifica che un documento JSON sia conforme a un insieme di vincoli strutturali e di valore definiti in un JSON Schema. Lo schema stesso è un documento JSON che descrive la forma attesa dei tuoi dati: quali proprietà sono obbligatorie, quali tipi devono avere, gli intervalli consentiti per i numeri, i pattern delle stringhe, le lunghezze degli array e altro ancora. La specifica JSON Schema è mantenuta su json-schema.org e pubblicata come serie di draft IETF; Draft 7 e Draft 2020-12 sono i più ampiamente adottati.

Mentre la semplice validazione JSON controlla solo la sintassi (le parentesi sono bilanciate? le stringhe sono tra virgolette?), la validazione di schema va oltre. Risponde a domande come: la risposta di questa API contiene un campo "id" che è sempre un intero? Il campo "status" è uno dei tre valori consentiti? Gli oggetti annidati hanno la forma corretta? Questo tipo di verifica strutturale individua bug che i controlli sintattici non rileverebbero mai, perché un JSON sintatticamente valido può essere semanticamente errato per la tua applicazione.

JSON Schema è usato nelle definizioni OpenAPI/Swagger, nella validazione di file di configurazione, nella validazione di form, nei vincoli sui documenti di database e nei test automatizzati. Strumenti come Ajv (JavaScript), jsonschema (Python) e check-jsonschema (CLI) implementano la specifica per validare i dati in modo programmatico. Questo validatore online ti permette di incollare sia uno schema che un documento dati per verificarne la conformità istantaneamente, senza installare alcuna libreria.

Perché usare un validatore JSON Schema online?

Scrivere schemi e fare il debug degli errori di validazione a mano è lento. Un validatore JSON Schema online ti dà un feedback immediato su se i tuoi dati corrispondono allo schema, con messaggi di errore chiari che indicano la proprietà esatta che ha fallito.

Casi d'uso della validazione JSON Schema

Riferimento alle parole chiave JSON Schema

Un JSON Schema è costruito da parole chiave che ciascuna impone un vincolo sui dati validati. La tabella seguente elenca le parole chiave più comunemente usate in Draft 7 e versioni successive. Ogni parola chiave può essere combinata con altre nello stesso oggetto schema.

Confronto dei draft JSON Schema: Draft 7 vs 2019-09 vs 2020-12

JSON Schema ha attraversato diverse versioni di draft. Draft 7 (pubblicato nel 2018) è il più ampiamente supportato dagli strumenti. Draft 2019-09 ha introdotto $defs (in sostituzione di definitions), unevaluatedProperties e $recursiveRef. Draft 2020-12 (l'ultimo rilascio stabile) ha sostituito $recursiveRef con $dynamicRef e introdotto prefixItems per la validazione delle tuple. Quando scegli un draft, verifica che la tua libreria di validazione lo supporti. Ajv supporta tutti e tre i draft. La libreria jsonschema di Python supporta fino a 2020-12 dalla versione 4.0.

Esempi di codice

Questi esempi mostrano come validare JSON rispetto a uno schema in modo programmatico. Ciascuno utilizza una libreria ben mantenuta per il proprio ecosistema linguistico.

import Ajv from 'ajv';

const ajv = new Ajv();

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1 },
    age: { type: 'integer', minimum: 0 },
    email: { type: 'string', format: 'email' }
  },
  required: ['name', 'email'],
  additionalProperties: false
};

const data = { name: 'Alice', age: 30, email: 'alice@example.com' };

const validate = ajv.compile(schema);
const valid = validate(data);
console.log(valid);          // → true
console.log(validate.errors); // → null

// Invalid data — missing required "email"
validate({ name: 'Bob', age: 25 });
console.log(validate.errors);
// → [{ instancePath: '', keyword: 'required', params: { missingProperty: 'email' } }]

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "age": {"type": "integer", "minimum": 0},
        "tags": {
            "type": "array",
            "items": {"type": "string"},
            "uniqueItems": True
        }
    },
    "required": ["name"]
}

# Valid data
validate(instance={"name": "Alice", "age": 30, "tags": ["admin"]}, schema=schema)
# → No exception raised

# Invalid data — wrong type for "age"
try:
    validate(instance={"name": "Alice", "age": "thirty"}, schema=schema)
except ValidationError as e:
    print(e.message)
    # → 'thirty' is not of type 'integer'
    print(e.json_path)
    # → $.age

package main

import (
    "fmt"
    "strings"
    "github.com/santhosh-tekuri/jsonschema/v5"
)

func main() {
    schemaJSON := `{
        "type": "object",
        "properties": {
            "id": { "type": "integer" },
            "status": { "enum": ["active", "inactive"] }
        },
        "required": ["id", "status"]
    }`

    compiler := jsonschema.NewCompiler()
    compiler.AddResource("schema.json", strings.NewReader(schemaJSON))
    schema, _ := compiler.Compile("schema.json")

    // Valid data
    data := map[string]interface{}{"id": 1, "status": "active"}
    err := schema.Validate(data)
    fmt.Println(err) // → <nil>

    // Invalid — missing "status"
    bad := map[string]interface{}{"id": 2}
    err = schema.Validate(bad)
    fmt.Println(err) // → validation failed: missing properties: 'status'
}

# Install via pip
pip install check-jsonschema

# Validate a file against a schema
check-jsonschema --schemafile schema.json data.json
# → ok -- validation done

# Validate against a remote schema (e.g., GitHub Actions workflow)
check-jsonschema --builtin-schema vendor.github-workflows my-workflow.yml

# Validate multiple files at once
check-jsonschema --schemafile schema.json file1.json file2.json file3.json

Domande frequenti