Blog SchemaSafe

Convalida dello schema JSON senza un LLM

La convalida dello schema appartiene a strumenti deterministici: lo stesso input produce lo stesso esito positivo o negativo, ogni volta. Un LLM può spiegare perché un documento non è stato convalidato o creare uno schema da un esempio, ma la decisione di convalida o meno dovrebbe provenire da un vero validatore. Quando il confine tra spiegazione e decisione rimane chiaro, il contratto rimane qualcosa che puoi testare e di cui puoi fidarti.

Il determinismo è il prodotto

Quando progetto un validator, mi concentro sul percorso attraverso l'albero dell'istanza. Ogni passo produce un oggetto di errore che contiene un percorso JSON Pointer, la parola chiave che non è riuscita e un messaggio breve. Poiché il percorso segue lo stesso algoritmo per gli stessi dati, l'elenco degli errori è identico ad ogni esecuzione. Quella ripetibilità consente ai team di trattare la convalida come un gate che non modifica mai il suo verdetto senza un reale cambiamento nello schema o nell'input.

I percorsi JSON Pointer sono mappati direttamente ai campi del modulo o alle chiavi della risposta API. Un front-end può prendere il puntatore /items/2/name e evidenziare il campo nome del terzo elemento senza alcun livello di traduzione aggiuntivo. Questa mappatura è deterministica, quindi lo stesso puntatore punta sempre alla stessa posizione nella stessa forma del documento.

Nel CI eseguo il validator contro la suite di test e contro eventuali fixture generate. Se il validator restituisce un array di errori vuoto, la build procede; qualsiasi array non vuoto fa fallire la build e il payload di errore viene pubblicato come artifact. Poiché l'output è leggibile dalla macchina, i passaggi downstream possono contare gli errori, raggrupparli per puntatore o pubblicare un commento sulla richiesta di pull che mostra i percorsi esatti che non sono riusciti.

Dove un LLM si guadagna il suo posto

Utilizzo un modello linguistico solo per compiti che non richiedono un verdetto vero/falso. Il modello non decide mai se passare o fallire; produce solo suggerimenti che un essere umano o uno strumento possono revisionare.

Dato un pugno di documenti JSON di esempio, sollecito il modello a emettere uno schema Draft 2020-12 che catturi i tipi osservati, i campi richiesti e i modelli di base. L'output è un punto di partenza; lo eseguo attraverso il validator per vedere se accetta gli esempi e poi stringo o allento manualmente le restrizioni.

Quando il validator restituisce una matrice di errori, alimento ogni oggetto di errore al modello con una richiesta di riscrivere il messaggio in linguaggio piano. Il modello può trasformare “failed keyword “required” at pointer /user/profile/age” in “Il profilo utente manca di un campo di età, che il tuo servizio si aspetta essere un intero.” Ciò aiuta i consumatori dell'API che non sono familiari con le parole chiave dello schema JSON.

Mostrando al modello un elenco di errori di convalida frequenti, posso chiedergli di proporre ulteriori restrizioni, come una lunghezza minima di stringa o un modello per un identificatore. Revisiono ogni suggerimento, aggiungo quelli che hanno senso e eseguo nuovamente il validator per confermare che il nuovo schema supera ancora i campioni noti buoni.

Per sicurezza, tengo il modello dietro un'API interna e registro ogni prompt e risposta. Il registro mi consente di verificare se il modello abbia mai tentato di influenzare il confine di decisione, il che non può fare perché non passo mai la sua output al validator come regola.

Esegui la convalida in CI e al limite

Lo stesso schema dovrebbe proteggere il repository di codice e il servizio live. Eseguo il validator in due luoghi:

Eseguire la convalida solo in una porta di accesso lascia il servizio interno esposto a derive; se lo schema della porta di accesso viene aggiornato ma un servizio downstream dimentica di eseguire il pull della modifica, dati errati possono passare. Incorporando il validator nel servizio, garantisco che il contratto venga applicato ovunque si trovi il codice.

Quando la convalida ha esito negativo, restituisco HTTP 400 con un corpo JSON che contiene una matrice di oggetti di errore. Ogni oggetto di errore include:

I client possono analizzare questa matrice e visualizzare errori di modulo inline, il che accelera il lavoro di integrazione rispetto a una stringa generica di "convalida non riuscita".

Poiché il validator è senza stato e deterministico, posso utilizzare lo stesso binario o libreria in entrambi i luoghi senza preoccuparmi di uno stato nascosto che potrebbe causare divergenza.

Generazione di bozza versus governance

SchemaSafe separa chiaramente le preoccupazioni:

Questa divisione mantiene il contratto auditable. Posso fare riferimento a un file di schema specifico nel repository, notare la versione del validator e mostrare che lo stesso input produce sempre lo stesso risultato. Il contributo del modello vive in registri separati o in commenti allegati alla richiesta di pull; non diventa mai parte del record di decisione immutabile.

Quando devo aggiornare lo schema, seguo questi passaggi:

In tutto questo flusso il validator è il gatekeeper; il modello non ha mai l'ultima parola.

Cosa questo non è

Questo approccio non è una promessa che ogni documento non valido verrà intercettato prima di raggiungere un utente. Se uno sviluppatore bypassa intenzionalmente il middleware o se un bug nel validator lascia passare un errore, i dati errati possono comunque apparire. Non affermo una copertura del 100 %; affermo solo che il controllo è deterministico e ripetibile.

Non è un sostituto di una progettazione API pensata. Uno schema può descrivere la forma e le constraint di base, ma non può esprimere regole aziendali che dipendono da stato esterno o logica cross-campo complessa. Queste regole hanno ancora bisogno di test unitari o guardiani in fase di runtime.

Non è una garanzia che il LLM produca sempre spiegazioni utili. Il modello può occasionalmente perdere sfumature o produrre una riscrittura fuorviante. Tratto la sua uscita come una suggerimento che un essere umano può accettare, modificare o scartare.

Infine, non è una soluzione definitiva per la sicurezza. Sebbene la convalida dell'input riduca molti rischi di iniezione, seguo ancora le linee guida di OWASP sull'iniezione dei prompt ( https://genai.owasp.org/llmrisk/llm01-prompt-injection ) e sull'igiene delle credenziali in CI/CD ( https://owasp.org/www-project-top-10-ci-cd-security-risks/CICD-SEC-06-Insufficient-Credential-Hygiene ) per mantenere la pipeline circostante sicura.

Riferimenti

https://genai.owasp.org/llmrisk/llm01-prompt-injection

https://owasp.org/www-project-top-10-ci-cd-security-risks/CICD-SEC-06-Insufficient-Credential-Hygiene

https://ajv.js.org/json-schema.html

https://cheatsheetseries.owasp.org/cheatsheets/LLM_Prompt_Injection_Prevention_Cheat_Sheet.html

Domande frequenti

La convalida deve essere riproducibile: stesso input, stesso risultato. Il giudizio di un modello può variare tra le esecuzioni, il che è inaccettabile per un contratto che controlla un deploy. Il convalidatore decide; il modello spiega.

Creare uno schema da un esempio, riscrivere un errore di convalida per un essere umano o suggerire perché un campo è stato omesso. Queste sono funzionalità aggiuntive rispetto a un convalidatore reale, non un sostituto per uno.

No. Convalida le richieste in ingresso nel servizio che controlli in modo che i messaggi di errore includano il contesto del dominio. Esegui lo stesso schema in CI contro i fixture e tratta le modifiche dello schema come potenziali modifiche di rottura.

La bozza 2020-12 è la versione stabile supportata dai convalidatori moderni come Ajv v8 e allineata con OpenAPI 3.1. Fissa l'URL dello schema in ogni file in modo che il comportamento non si modifichi.

Prova il prodotto: SchemaSafe

2026-09-16 · solo fonti primarie · nessuna metrica di traffico fabbricata