Salta al contenuto
Ufficio Lo.Gi.Co.Ufficio Lo.Gi.Co. Assistenza
← Tutte le risorse

Testo e formati · 9 MIN DI LETTURA

Come formattare e verificare un JSON prima di usarlo

Un JSON può essere ben allineato e non essere utilizzabile dall’applicazione. La prima verifica riguarda la sintassi; la seconda riguarda campi, tipi e valori attesi dal sistema che lo riceverà. Separare questi…

A cura di Ufficio Lo.Gi.Co.

Preparare una verifica2 fonti consultabili ↓
Illustrazione tecnica: Sintassi, contratto, comportamento. Sintassi; Ambiguità; Contratto; Collaudo.
SCHEMA CONCETTUALE / UFFICIO LO.GI.CO.

Un JSON ben allineato può essere sintatticamente valido e ancora inadatto all’applicazione che lo riceve. Formattazione, schema, significato e autorizzazione sono controlli distinti. Il percorso utile conserva l’originale, corregge errori nel loro contesto e prova un campione senza modificare la produzione. Il formatter rende leggibile la struttura; non approva una configurazione né esegue ciò che il testo descrive.

Definire origine, destinazione e scopo del contenuto

Chiarisci se il JSON rappresenta una risposta API, una configurazione, un’esportazione o un esempio. Il formato può essere lo stesso, ma il significato dei campi dipende dal sistema. Recupera la versione dello schema o la documentazione della destinazione, quando disponibile, prima di modificare valori e nomi.

Conserva una copia esatta dell’originale. Se stai diagnosticando un errore, una trasformazione preliminare può nascondere il problema che devi capire. Prepara poi un campione senza credenziali, token o dati personali non necessari. Il fatto che il tool lavori localmente non autorizza a usare materiale che non sei abilitato a trattare.

Indica il risultato desiderato: sola lettura, formattazione, confronto o preparazione di un invio di prova. Non lasciare che una validazione sintattica diventi implicitamente una decisione di applicare il documento a un sistema. L’operazione successiva deve avere un perimetro separato.

La RFC 8259 definisce JSON e fornisce indicazioni di interoperabilità. [1] Serve come base del formato, mentre la specifica dell’applicazione decide quali campi e valori siano accettabili. Questa distinzione evita di correggere il testo in un modo che piace al parser ma cambia il contratto del servizio.

Riconoscere i tipi senza confonderli con il contenuto visivo

Stringhe, numeri, booleani, null, oggetti e array hanno ruoli differenti. Un codice composto da cifre può essere una stringa; una quantità può essere un numero. Non cambiare il tipo soltanto perché il valore «sembra numerico». La scelta deve seguire il significato e lo schema previsto.

Un esempio sintetico mostra un identificativo testuale e valori di tipo diverso:

{
  "codice": "00125",
  "attivo": true,
  "pagine": 12,
  "nota": null,
  "categorie": ["ufficio", "prova"]
}

Il campione non è una configurazione pronta per un prodotto. Illustra che gli zeri iniziali fanno parte del codice e che null è diverso da una stringa vuota. Il destinatario deve definire come trattare ciascuno di questi casi.

Non aggiungere commenti, apici singoli o virgole finali assumendo che siano accettati. Alcuni formati derivati li consentono, ma non diventano JSON standard perché un editor li evidenzia bene. Se il sistema usa un formato diverso, dichiaralo e scegli lo strumento appropriato anziché forzarlo attraverso sostituzioni automatiche.

Correggere la sintassi risalendo al contesto dell’errore

Il punto segnalato dal validatore può essere quello in cui il parser non riesce più a continuare, non necessariamente il punto dove è nato il problema. Una virgola o una parentesi mancante può produrre un errore più avanti. Esamina quindi l’oggetto o l’array circostante e confrontalo con la struttura attesa.

Procedi con una correzione alla volta e ripeti la verifica. Evita sostituzioni globali di apostrofi, virgolette o barre: dentro una stringa possono essere dati legittimi. Un cambiamento indiscriminato può rendere il documento valido alterando però nomi, percorsi o messaggi.

Il validatore JSON locale controlla sintassi e duplicati, con limiti dichiarati nell’interfaccia. Nella configurazione descritta accetta fino a un MiB di testo o file, centoventotto livelli e duecentomila token. Questi limiti proteggono la praticità dell’elaborazione e non descrivono la capacità di ogni sistema destinatario.

Non usare esecuzione di codice per capire se il contenuto sia valido. Il testo deve essere analizzato come dati. Un frammento che assomiglia a JavaScript non deve essere valutato in una console operativa soltanto perché condivide una parte della sintassi con JSON.

Trattare le chiavi duplicate come ambiguità da risolvere

Due occorrenze dello stesso nome in un oggetto possono essere gestite diversamente dai parser. Alcuni mantengono un valore, altri segnalano un problema o espongono comportamenti differenti. La RFC raccomanda nomi univoci per favorire l’interoperabilità. [1] Una configurazione ambigua non deve essere approvata perché un programma riesce comunque a leggerla.

Il formatter segnala le chiavi duplicate e le conserva, senza scegliere automaticamente quale valore tenere. Questa scelta permette di vedere l’input originale, ma richiede una decisione da parte di chi conosce il sistema. Non assumere che l’ultima occorrenza sia quella corretta.

Confronta il contenuto con la sorgente e con il contratto dell’applicazione. Il duplicato può derivare da una fusione, da un’esportazione o da un errore di generazione. La correzione deve spiegare quale valore è stato mantenuto e perché, evitando di nascondere l’ambiguità con una semplice formattazione.

Se il documento è prodotto automaticamente, correggi anche il processo che genera il duplicato. Una modifica manuale al singolo file può essere utile per un test, ma il problema si ripresenterà alla successiva esportazione. Il collaudo deve quindi includere il nuovo output del produttore, non soltanto una copia corretta a mano.

Schema di verifica: Sintassi, contratto, comportamento. Sintassi; Ambiguità; Contratto; Collaudo.

Ogni livello risponde a una domanda diversa prima che il documento venga usato dall'applicazione.

Leggi lo schema
  1. SintassiStruttura leggibile senza eseguire contenuti
  2. AmbiguitàDuplicati, tipi e precisione esaminati
  3. ContrattoSchema e regole della destinazione verificati
  4. CollaudoValori e comportamento osservati in prova

La verifica: Il sistema registra i valori previsti senza conversioni o effetti inattesi?

Un JSON valido può essere ancora una configurazione sbagliata per il destinatario.

Preservare numeri lunghi e rappresentazioni significative

La sintassi JSON non garantisce che tutti i parser rappresentino ogni numero con la stessa precisione. Il normale percorso numerico JavaScript ha limiti che possono influire sugli interi molto grandi; la documentazione di JSON.parse richiama questo aspetto. [2] La verifica deve considerare il sistema che consumerà il valore.

Il formatter UFFLOG preserva la rappresentazione scritta di numeri e stringhe durante la formattazione, invece di trasformare automaticamente tutti i valori numerici in una rappresentazione che potrebbe arrotondarli. Questo protegge il testo nel passaggio specifico, ma non cambia il comportamento di un’applicazione successiva.

Per identificativi e importi usa il tipo previsto dal contratto. Non convertire ogni numero in stringa per evitare un rischio generico: potresti rendere il documento incompatibile. Se il requisito di precisione non è chiaro, chiedi la specifica e prepara un campione con valori limite pertinenti.

Controlla anche rappresentazioni che sembrano equivalenti ma hanno un ruolo diverso nel processo. Una formattazione deve modificare lo spazio leggibile, non decidere una politica di normalizzazione dei dati. Quando serve un confronto semantico, usa un percorso esplicito e conserva la differenza rispetto al testo originale.

Verificare schema e regole del dominio dopo la sintassi

Confronta campi obbligatori, tipi, valori ammessi e gestione dei campi sconosciuti. Un JSON valido può omettere un identificativo necessario o contenere una data nel formato sbagliato. Il parser non conosce automaticamente queste regole. La validazione dello schema, quando disponibile, è un passaggio ulteriore.

Anche uno schema superato non dimostra sempre correttezza aziendale. Due date possono avere il formato richiesto e un ordine impossibile; un codice può rispettare la lunghezza ma non esistere nel sistema. Definisci quali verifiche appartengono al formato e quali richiedono dati o autorizzazioni della destinazione.

La guida al CSV per importazioni mostra lo stesso principio in un formato diverso. Cambiare contenitore non elimina mapping, chiavi e significato. Le regole devono essere esplicite, soprattutto quando un documento prepara ordini, configurazioni o attività con effetti esterni.

Non usare l’AI per inventare campi mancanti senza una fonte autorizzata. Un assistente può spiegare un errore o proporre domande, ma il valore finale deve provenire dal sistema o dalla persona competente. Il documento resta un insieme di dati da validare, anche quando è stato generato con un linguaggio convincente.

Formattare e confrontare senza confondere testo e comportamento

Una versione leggibile aiuta la revisione; una versione minificata riduce spazi non necessari al formato. Nessuna delle due modifica intenzionalmente il significato dei campi nel percorso del formatter. Conserva però l’originale, perché altre applicazioni possono avere comportamenti o vincoli propri.

Per capire cosa sia cambiato fra due configurazioni puoi usare Config Diff. Il confronto strutturale aiuta a individuare aggiunte, rimozioni e differenze di tipo, ma non applica le configurazioni e non decide se una modifica sia sicura. Un campo cambiato può richiedere una verifica del servizio che lo usa.

Se il JSON contiene valori codificati, la guida a Base64 e URL distingue rappresentazione e protezione. Una stringa Base64 resta un dato sensibile se rappresenta un segreto. La formattazione non la rende innocua né ne verifica la provenienza.

Mantieni separati confronto testuale e confronto semantico. Spazi e ordine delle proprietà possono cambiare l’aspetto senza rappresentare necessariamente una modifica applicativa, mentre un tipo diverso può avere conseguenze importanti. La revisione deve spiegare quale livello sta osservando.

Provare in un ambiente autorizzato senza effetti sulla produzione

Usa un campione sintetico nella destinazione di test prevista. Verifica risposta, messaggi d’errore e valore effettivamente registrato. Un codice di successo non dimostra che ogni campo sia stato accettato senza trasformazioni: alcuni sistemi ignorano proprietà o applicano valori predefiniti.

Includi casi mancanti, null, valori limite e ripetizione della stessa operazione quando pertinente. Il comportamento deve corrispondere al contratto: creare, aggiornare e rifiutare un duplicato sono esiti differenti. Non provare questi casi su dati operativi senza una procedura autorizzata.

Il formatter non verifica endpoint, permessi o regole commerciali. Non esegue configurazioni e non invia richieste al servizio. Questa separazione deve restare chiara nell’interfaccia e nel processo: il risultato di sintassi è una base per il collaudo, non un comando da applicare automaticamente.

Se il test produce effetti esterni, il responsabile deve definire contenimento e ritorno prima dell’esecuzione. Una guida generica non può sostituire la procedura del prodotto. Conserva i risultati del campione e ciò che non è stato verificato, senza promuovere l’input a configurazione approvata per sola leggibilità.

Consegnare il documento con versione e decisioni ricostruibili

La consegna dovrebbe identificare origine, schema, trasformazioni effettuate e prove superate. Non includere segreti nel rapporto. Il riferimento deve permettere a una persona autorizzata di capire quale copia sia stata esaminata e quale uso sia stato approvato.

Se il documento viene generato da un’applicazione, conserva un campione che permetta di ripetere la verifica dopo aggiornamenti. Nuovi campi o tipi possono cambiare il comportamento anche quando la sintassi resta valida. Il controllo deve seguire il contratto del sistema, non soltanto il risultato del parser.

Definisci cosa accade alle eccezioni: duplicati, campi sconosciuti o precisione non garantita devono avere un responsabile. Non risolverli silenziosamente durante un passaggio automatico senza una regola documentata. La tracciabilità riduce errori difficili da ricostruire in seguito.

Un JSON pronto all’uso è quindi più di un testo ben formattato. Deve rispettare sintassi e contratto, conservare i valori necessari ed essere stato provato nel perimetro previsto. Il tool rende visibili struttura e anomalie; la decisione tecnica completa collega quei risultati al comportamento reale dell’applicazione.

Dalla guida a una verifica concreta.

Confronta due esempi sintetici: JSON valido con un campo mancante e JSON sintatticamente errato. Distingui parsing, formattazione e schema; soltanto l’ultimo può descrivere i campi richiesti dal tuo flusso.

Risorse utili e progetti ufficiali
  • JSON Schema — First schema

    Documentazione pubblica. Un vocabolario per dichiarare tipi, campi e vincoli: diverso dalla semplice formattazione JSON.

  • Pydantic

    Progetto open source. Validazione strutturale dei dati; un campo formalmente valido può comunque contenere un valore errato.

I link ai repository identificano il progetto di origine, non una garanzia di sicurezza. Verifica licenza, manutenzione e compatibilità prima di adottare software. I siti esterni applicano le proprie regole sui dati.

RIFERIMENTI / TRASPARENZA

Le fonti. I limiti. Il contesto.

Questa guida collega indicazioni pratiche alla documentazione dei produttori e degli organismi citati. Versione del prodotto, licenze e configurazione possono cambiare il comportamento descritto.

  1. IETF — RFC 8259, formato JSON e interoperabilità ↗rfc-editor.org
  2. MDN — Parsing JSON e precisione numerica ↗developer.mozilla.org

Le indicazioni vanno applicate da persone autorizzate dopo aver verificato l’ambiente. Le immagini sono rappresentazioni concettuali.

Uso consapevole · limiti e responsabilità

Le guide e gli esempi hanno finalità informative. Non offriamo una garanzia di assenza di errori, continuità o idoneità a uno scopo specifico. Verifica il risultato prima di utilizzarlo e conserva copie degli originali.

L’uso avviene a tuo rischio e sotto la tua responsabilità, nei limiti consentiti dalla legge. Restano salvi i diritti e le responsabilità inderogabili. Queste indicazioni non sostituiscono un incarico professionale, un collaudo o una valutazione del tuo ambiente.

Esegui esempi soltanto su dati sintetici o copie autorizzate, dopo averne compreso gli effetti. La cancellazione dalla sessione rimuove i risultati dalla pagina: non revoca copie, download o appunti e non certifica la cancellazione sicura della memoria.

Porta il ragionamento nel tuo contesto.

Prepara i dati del tuo ambiente e le priorità. Il confronto parte già dalle domande utili.

CONTINUA IL PERCORSO

UFFLOG BOT / IL TUO PROSSIMO PASSO

Partiamo da ciò che ti serve.

Dove vuoi arrivare?

Per un progetto già definito, parliamone direttamente ↗