Strumenti per sviluppatori · JSON formattatore e validatore
Perché un file JSON Lines non supera la convalida alla riga 2, colonna 1
· Come funziona
json flusso di lavoro dello sviluppatore convalida
Un file .jsonl è composto da molti documenti JSON, non uno, quindi un validatore rigoroso si ferma esattamente dove inizia il secondo. Questo post spiega le convenzioni JSON Lines e NDJSON e come convalidarle un record alla volta.
Valido su ogni riga, non valido come file
Valido su ogni riga, non valido come file: l'esportazione che ogni strumento downstream legge volentieri ma un validatore rifiuta alla seconda riga. Un mittente del log può utilizzare ogni nuova riga come limite del record, tuttavia un parser JSON rigoroso vede l'intero file come un input. Il primo oggetto è completo JSON; la parentesi graffa di apertura successiva è un valore della seconda radice illegale.
ToolAcre convalida un testo JSON, non JSON righe. Una volta che lo scanner ha completato il primo valore root, qualsiasi carattere successivo diverso dagli spazi bianchi viene segnalato come imprevisto dopo la fine del valore JSON. Non offre la convalida o la conversione NDJSON per riga come fallback nascosto. Questa distinzione impedisce che un risultato verde implichi che ogni record in un flusso orientato alla riga sia stato controllato.
Un testo, un valore: cosa RFC 8259 definisce come testo JSON e perché due valori di primo livello consecutivi rappresentano un errore grammaticale
Un testo, un valore: cosa RFC 8259 definisce come testo JSON e perché due valori di primo livello consecutivi rappresentano un errore grammaticale. Un testo JSON è un valore serializzato, quindi un oggetto, un array, una stringa, un numero, un booleano o un null possono trovarsi alla radice. Lo spazio bianco può racchiudere quel valore, ma non può separare diverse radici in un documento valido più grande.
Ad esempio, `{"ok":true} {"ok":false}` contains two individually valid objects but is not one JSON text. Parsing the first object consumes a complete value; parsing the entire string must then reject the second `{`. Per rappresentare entrambi i valori nell'ordinario JSON, posizionali all'interno di un array e aggiungi la virgola richiesta tra gli elementi dell'array.
JSON Linee e NDJSON
JSON Lines e NDJSON: le convenzioni delimitate da fine riga, perché esistono per lo streaming e i log e come differiscono da un array JSON. Ogni riga fisica trasporta un valore JSON completo, normalmente un oggetto, e il ritorno a capo funge da cornice al di fuori della grammatica JSON. I produttori possono aggiungere record e i consumatori possono elaborarli in modo incrementale senza caricare una raccolta completa.
Un array invece ha una parentesi di apertura, elementi separati da virgole e una parentesi di chiusura, rendendo l'intero file un unico valore JSON. È utile per le API che restituiscono una raccolta limitata ma scomodo per un flusso di eventi in crescita indefinita. Un file JSON Lines troncato può conservare tutti i record precedenti completi; un array troncato lascia comunemente incompleto il valore che lo racchiude.
Perché l'errore è sempre alla riga 2, colonna 1
Perché l'errore è sempre alla riga 2, colonna 1: il parser termina il primo valore, prevede la fine dell'input e soddisfa il primo carattere del secondo record. Il ritorno a capo stesso è uno spazio bianco finale legale, quindi non innesca l'errore. La parentesi graffa di apertura del record successivo è il primo token che contraddice lo stato del documento completato.
Quella posizione è una prova diagnostica piuttosto che un'affermazione che il secondo oggetto sia malformato. Se il rapporto punta costantemente al primo carattere diverso da uno spazio bianco dopo una radice valida, controlla la forma del file prima di modificare la punteggiatura. L'eliminazione della parentesi graffa danneggerebbe il record; la scelta di un lettore che riconosce la linea o la conversione dei record in un array risolve l'effettiva mancata corrispondenza del framing.
Esempio realizzato: convalida di tre record di registro
Esempio funzionante: convalida di tre record di registro: controllo di ciascuna riga singolarmente anziché racchiuderli in un array con virgole. Supponiamo che le righe contengano `{"level":"info"}`, `{"level":"warn"}` e `{"level":"error"}`. Un validatore orientato alla riga analizza tre input separati e può identificare il record esatto se presenta una citazione mancante o una virgola finale.
Per un controllo rigoroso dell'intero documento, trasforma l'esempio in `[{"level":"info"},{"level":"warn"},{"level":"error"}]`. Le parentesi stabiliscono una radice e le virgole ne delimitano gli elementi. Non limitarti a sostituire i ritorni a capo con le virgole: ciò produce tre radici separate dalla punteggiatura a meno che non venga aggiunto l'array circostante e può gestire in modo errato le righe vuote che la convenzione di origine potrebbe vietare o ignorare.
Conversione tra le due forme
Conversione tra le due forme: quando un array di avvolgimento è appropriato e quando annullerebbe il punto di output delimitato da linee. Un'esportazione finita destinata a una richiesta API, un editor o un validatore rigoroso può spesso diventare un array. La conversione deve prima analizzare ogni record, poiché la concatenazione testuale non può tenere conto in modo sicuro dei caratteri di escape incorporati o delle righe non valide.
Mantieni JSON Linee quando i record arrivano continuamente, i file vengono aggiunti o i consumatori necessitano di memoria limitata e ripristino a livello di record. La conversione di un flusso di eventi da più gigabyte in un array richiede il mantenimento dello stato del contenitore e ritarda un'analisi completa fino all'arrivo della parentesi di chiusura. Nell'altra direzione, serializza ogni elemento dell'array in modo compatto su una riga e definisci se sono consentite righe vuote o ritorni a capo finali.
Ciò che questo non copre
Ciò che questo non copre: concatenato JSON senza ritorni a capo e framing di separatori di record (RFC 7464), che necessitano di parser dedicati. I valori posizionati direttamente insieme non possono essere divisi in modo sicuro con una semplice operazione su una riga, soprattutto quando le radici possono essere numeri o stringhe. RFC 7464 utilizza un carattere separatore di record ASCII per inquadrare sequenze di testo JSON anziché fare affidamento solo su ritorni a capo visibili.
Inoltre, non convalida le regole dell'applicazione condivise dai record. L'analisi di ogni riga non può dimostrare che i timestamp siano ordinati, gli identificatori siano univoci o che tutti gli oggetti utilizzino lo stesso schema. Tali controlli avvengono dopo l'inquadratura dei record e l'analisi della sintassi. Allo stesso modo, una nuova riga incorporata come sequenza di escape ` ` all'interno di una stringa ci sono dati, non un confine fisico, e un lettore di linea conforme deve preservare questa distinzione.
Da asporto: scopri quale forma stai tenendo
Conclusione: scopri quale forma stai tenendo in mano e in che modo la posizione del validatore ti dice immediatamente che un file è delimitato da righe. Un errore nel primo token della riga due dopo un valore completo della riga uno indica fortemente più record con frame e non una sintassi interrotta nel primo record. Controllare l'estensione, la documentazione del produttore e il consumatore previsto prima di modificare i dati.
Utilizza un parser JSON Lines o NDJSON per convalidare i record in modo indipendente quando il ritorno a capo è intenzionale. Utilizza un array quando la destinazione richiede una raccolta JSON completa. ToolAcre rifiuta correttamente il file multi-root perché il suo contratto è una rigorosa convalida a testo singolo; il rifiuto protegge quel contratto anziché mostrare che JSON delimitato da nuova riga è intrinsecamente difettoso. Abbina il validatore al formato di framing.