JSON Schema Validator

Cos'è JSON Schema e perché è importante?

JSON (JavaScript Object Notation) è la lingua franca delle API web, dei file di configurazione e dello scambio di dati. Ma il JSON grezzo non ha un sistema di tipi integrato — un campo può essere una stringa un giorno e un numero il giorno dopo, e l'unico modo per scoprire la discrepanza è un errore di runtime o un sottile bug nei dati. JSON Schema colma questa lacuna: è un vocabolario dichiarativo per descrivere la struttura attesa e i vincoli di un documento JSON, validato rispetto ai dati reali durante l'esecuzione.

I team usano JSON Schema per validare i payload delle richieste API prima di elaborarli, per imporre la struttura dei file di configurazione caricati all'avvio, per generare automaticamente documentazione e form UI da un'unica fonte di verità e per mantenere la coerenza dei contratti tra i microservizi. OpenAPI — lo standard per la documentazione delle REST API — è costruito direttamente su JSON Schema, rendendolo lo standard di validazione dei dati più diffuso sul web.

Versioni delle specifiche JSON Schema: Draft-07, Draft 2019-09 e Draft 2020-12

JSON Schema ha attraversato diverse versioni delle specifiche. Il Draft-07, rilasciato nel 2018, rimane il più ampiamente supportato in tutte le principali librerie di validatori ed è il dialetto utilizzato da OpenAPI 3.0. Ha introdotto le potenti parole chiave di validazione condizionale if/then/else, le annotazioni di proprietà readOnly/writeOnly e le parole chiave di codifica del contenuto. Se stai scrivendo schemi oggi e non hai bisogno delle funzionalità più recenti, Draft-07 è la scelta più sicura per la massima compatibilità con l'ecosistema.

Draft 2020-12 è la specifica stabile attuale e introduce diverse modifiche significative: la parola chiave items viene sostituita da prefixItems per la validazione delle tuple, i riferimenti dinamici usano $dynamicRef invece di $recursiveRef, e le nuove parole chiave unevaluatedProperties e unevaluatedItems forniscono un controllo più preciso sul contenuto aggiuntivo.

Le principali parole chiave di JSON Schema spiegate

La parola chiave type impone un tipo di dati: string, number, integer, boolean, array, object o null. required elenca le proprietà che devono essere presenti in un oggetto. properties mappa ogni nome di proprietà al proprio sotto-schema. pattern applica un'espressione regolare a un valore stringa. minimum, maximum, minLength e maxLength vincolano intervalli numerici e di stringa. enum limita un valore a un insieme fisso di valori consentiti; const lo limita a un singolo valore.

Le parole chiave di composizione permettono di costruire regole complesse da semplici blocchi fondamentali: allOf agisce come un AND logico, anyOf come OR e oneOf come XOR. La parola chiave not inverte uno schema. Le parole chiave if/then/else abilitano la validazione condizionale. Insieme consentono di esprimere quasi qualsiasi regola di validazione senza scrivere codice imperativo personalizzato.

JSON Schema in produzione: contratti API e pipeline CI

Nei sistemi di produzione, la validazione JSON Schema viene eseguita lato server o in pipeline CI usando librerie come Ajv (JavaScript/Node.js), jsonschema (Python) o Newtonsoft.Json (C#). Gli schemi vengono committati nel controllo versione insieme al codice dell'applicazione in modo che le modifiche al contratto vengano revisionate e tracciate come qualsiasi altra modifica. Le modifiche incompatibili — rimozione di un campo obbligatorio, restringimento di un tipo — vengono rilevate durante la revisione del codice prima di raggiungere la produzione.

Questo strumento basato su browser è ideale per progettare e fare debug degli schemi in modo iterativo prima di committarli. Incolla i tuoi dati, scrivi il tuo schema, clicca Valida, leggi i messaggi di errore dettagliati e perfeziona — nessun server, nessun npm install, nessun viaggio andata e ritorno. Il validatore esegue anche la stampa formattata del JSON ad ogni esecuzione, rendendolo un comodo combinato di formatter JSON e tester di schema.

Esempio pratico: Validare una risposta API

Supponiamo che la tua API restituisca un oggetto utente. Un JSON Schema che lo valida potrebbe richiedere un id intero, un nome stringa non vuoto, un email stringa corrispondente a un pattern email e un ruolo stringa opzionale da un enum di 'admin', 'editor' e 'viewer'. Impostare additionalProperties su false garantisce che la tua API non restituisca mai silenziosamente campi non documentati da cui i consumatori a valle potrebbero dipendere inavvertitamente.

La funzione if/then/else consente regole condizionali — per esempio, se il ruolo è 'admin' allora un array di permessi è richiesto, altrimenti è vietato. Queste regole composizionali permettono a un singolo schema di coprire più forme valide di un oggetto senza duplicare le definizioni delle proprietà.

Come si confronta UtiloKit con altri validatori JSON Schema

La maggior parte degli strumenti online per la validazione JSON Schema rientra in due categorie: costruttori visivi di schemi e validatori API lato server. jsonschema.net ti obbliga a passare attraverso un'interfaccia punta e clicca per costruire gli schemi — utile per i principianti che imparano la struttura degli schemi, ma lento per gli sviluppatori che sanno già quali parole chiave hanno bisogno.

jsonschemavalidator.net, costruito sulla libreria Newtonsoft.Json di Microsoft, riporta gli errori usando percorsi di proprietà .NET e codici di errore che sembrano poco familiari agli sviluppatori JavaScript. Strumenti come Stoplight e SwaggerHub validano gli schemi come parte di un documento OpenAPI completo e richiedono la configurazione del progetto e un account.

Il validatore di UtiloKit gira sullo stesso motore Ajv che alimenta la maggior parte delle applicazioni Node.js, Express e Fastify. I messaggi di errore, i percorsi dei puntatori JSON e il comportamento delle parole chiave corrispondono esattamente al tuo ambiente di produzione — e gira gratuitamente nel tuo browser senza account, senza upload, senza limite di dimensione file e senza limite di utilizzo giornaliero.