Preparare JSON, tabelle Markdown e testo HTML

Decidere che cosa serve alla destinazione

Una stessa esportazione può avere diverse rappresentazioni utili. Un programma può richiedere oggetti JSON con chiavi note. Il README di un progetto può richiedere una breve tabella Markdown. Un esempio HTML può dover mostrare una e commerciale o delle parentesi angolari senza che il browser le legga come markup. Scegli prima la destinazione. Una tabella che appare corretta in un browser non è per forza una fonte affidabile per reimportare i record in un programma.

Conserva un originale con un delimitatore noto o una struttura documentata. Per esempio, un piccolo team può avere un CSV con ticket_id, summary e status. Crea separatamente da quel CSV il JSON leggibile dalle macchine e la tabella per la lettura. Non prendere la tabella già visualizzata per ricopiarla negli appunti e usarla come nuova fonte di verità. In questo andata e ritorno si perdono facilmente valori vuoti, zeri iniziali e a capo.

Decidi che cosa deve restare esatto. Se un identificatore ha cinque cifre compresi gli zeri iniziali, annota che è testo anche se sembra un numero. Se una nota può contenere un a capo, conservalo nell'originale e scegli a parte come mostrarlo. Prova con qualche record rappresentativo prima di convertire l'intera fonte.

Controllare la sintassi JSON prima di leggere i dati

Un JSON valido usa le virgolette doppie per i nomi delle proprietà e per i valori di tipo stringa. Non ammette commenti, virgole finali né un segnaposto come undefined. Un elenco inizia con una parentesi quadra; un oggetto inizia con una graffa. Incolla solo i dati, non il blocco di codice Markdown che racchiude un esempio né un'assegnazione come const config =. La notazione degli oggetti JavaScript e il JSON si assomigliano, ma molte cose valide in un file JavaScript non lo sono in JSON.

{ "ticket_id": "00123", "open": true, "note": null }

Parti da un piccolo esempio valido per capire se l'errore è nella tua fonte o nel modo in cui è stata copiata. Se il formattatore segnala un errore di lettura, guarda la zona indicata e il valore che la precede. Una virgoletta di chiusura mancante può far rilevare l'errore più avanti rispetto al carattere che devi davvero correggere. Le virgolette tipografiche incollate da un documento sono caratteri di testo, non delimitatori di stringa JSON.

Ripara un errore alla volta e ripeti il controllo. Evita di sostituire le virgolette ovunque: una virgoletta dentro una stringa correttamente protetta fa parte del valore e non va cambiata.

Apri il formattatore JSON e controlla la sintassi

Scegliere tra formattazione leggibile e risultato compatto

I rientri aiutano una persona a vedere dove inizia e dove finisce ogni record o valore annidato. Usa la formattazione leggibile quando rivedi un campione, confronti due versioni o metti un piccolo oggetto in una documentazione. Scegli due o quattro spazi in base alle convenzioni del progetto che riceve il testo. Usa la compressione quando ti serve una rappresentazione compatta e chi la riceve la interpreterà comunque. Ridurre gli spazi non equivale a comprimere un file, a cifrarlo né a nascondere i dati.

Il formattatore verifica il testo e poi cambia gli spazi fuori dai token JSON. Non ricostruisce il risultato convertendo ogni numero in un numero JavaScript e riscrivendolo. Per esempio, i caratteri di 9007199254740993, 1e-7 e -0 possono restare come sono scritti. Una sequenza di escape dentro una stringa resta una sequenza di escape nel risultato. È utile quando formatti un'esportazione senza cambiare in silenzio il modo in cui un valore era stato scritto.

Questa conservazione non rende un sistema ricevente capace di memorizzare ogni numero con esattezza. Se un identificatore può superare l'intervallo di interi sicuri di un sistema, concorda prima di esportare di rappresentarlo come stringa. Controlla il valore realmente importato, soprattutto se un'altra applicazione potrebbe forzarlo a diventare un numero.

Formatta una copia leggibile o comprimi il tuo JSON

Distinguere i controlli di sintassi da quelli di schema

Un controllo di sintassi conferma che un parser JSON riesce a leggere il testo. Non conferma che un'API o un programma di importazione lo accetterà. Per esempio, sia {"ticket_id":"00123"} sia {"ticket_id":123} sono JSON validi. Solo la stringa conserva esattamente quel codice. Allo stesso modo, un oggetto e un elenco di oggetti possono essere entrambi validi anche se un programma di importazione ne accetta soltanto una delle due forme.

Controlla i nomi dei campi, i tipi e i campi obbligatori che l'applicazione ricevente si aspetta. Fai attenzione a null, a una stringa vuota e a una proprietà mancante: possono voler dire tre cose diverse. Se l'app ha un esempio di importazione, parti da quella forma. Poi aggiungi un valore rappresentativo dei tuoi dati e provalo. Quando puoi, usa un ambiente di prova o l'anteprima di importazione dell'app prima di modificare i record reali.

Cerca le chiavi ripetute dentro un oggetto. Un formattatore che conserva i token della fonte non le deduplica, e i sistemi possono non essere d'accordo su quale valore usare. Se la stessa proprietà compare due volte, correggi la fonte in modo che esprima il valore voluto una volta sola. Un risultato ben indentato senza errori di sintassi non è comunque la prova che regole di business o vincoli di unicità siano stati superati.

Controlla il JSON dopo aver corretto la fonte

Convertire un piccolo campione CSV prima dell'esportazione completa

Apri il convertitore CSV e JSON con un'intestazione e due o tre righe. Controlla se la prima riga deve fornire le chiavi degli oggetti. Senza intestazione, un array di campi può essere una rappresentazione migliore. Se due intestazioni si ripetono, rinominale di proposito invece di aspettarti che due proprietà di un oggetto con lo stesso nome identifichino due colonne distinte. Conserva una tabella di corrispondenza se l'importazione richiede nomi di campo standardizzati.

ticket_id,summary,status
00123,"Cavo, staffa & supporto",aperto
00124,"L'etichetta dice <pronto>",chiuso

Le virgolette proteggono la virgola nel primo riepilogo. La e commerciale e le parentesi angolari sono contenuto CSV letterale. Non servono entità HTML nella versione CSV o JSON solo perché qualcuno potrebbe vederle in seguito su una pagina web. Applica la protezione HTML solo quando produci una versione per quel contesto. Controlla che il JSON contenga esattamente gli stessi riepiloghi e che gli ID dei ticket siano stringhe con gli zeri iniziali.

Per una tabella con campi su più righe o delimitata da punto e virgola, segui la guida su elenchi e tabelle per controllare l'interpretazione. Un campo non deve spostarsi di colonna solo perché contiene punteggiatura o un a capo.

Preparare una tabella separata per la documentazione

Quando le persone devono vedere solo pochi record, genera una tabella Markdown direttamente dal CSV. Scegli il delimitatore giusto, conferma l'impostazione sull'intestazione e controlla l'anteprima nella destinazione reale. Se il riepilogo contiene una barra verticale, il convertitore la protegge in modo che resti dentro la cella invece di fare da confine di colonna. Se il testo contiene parentesi angolari letterali, la tabella generata le rappresenta come testo invece di incorporare come markup il valore originale che sembra un tag.

Limita un esempio di documentazione alle colonne che contano. Se stai mostrando una convenzione per i nomi, possono servirti l'identificatore del ticket e il riepilogo, ma non una lunga nota interna. Usa esempi inventati quando la fonte contiene informazioni personali o riservate. Lo strumento lavora in locale, ma copiare un risultato in un ticket o in un repository pubblico è un'azione diversa, con un pubblico diverso.

Il rendering delle tabelle Markdown non è identico ovunque. Controlla in anteprima una riga con una barra verticale protetta, una cella con un a capo e un valore molto lungo. Alcuni renderer non supportano le tabelle o possono eliminare gli a capo incorporati. In quel caso usa un breve elenco o un file separato invece di presumere che il sorgente grezzo della tabella appaia sempre bene.

Genera una tabella Markdown dal tuo campione

Proteggere il testo per l'HTML nel contesto giusto

L'HTML usa le parentesi angolari per segnare i tag e la e commerciale per iniziare i riferimenti ai caratteri. Se stai scrivendo codice HTML e vuoi mostrare il testo letterale Borsa & scatola <pronta>, proteggi quei caratteri per un nodo di testo. Così il browser mostra il testo invece di trattare <pronta> come markup. Una e commerciale già usata come parte di un'entità non deve essere codificata una seconda volta per sbaglio, a meno che tu non voglia mostrare il riferimento stesso.

Input:  Borsa & scatola <pronta>
Output: Borsa &amp; scatola &lt;pronta&gt;

Usa lo strumento sul valore letterale, non su una pagina intera che vuoi mantenere funzionante. Proteggere un'intera pagina trasforma i tag in testo visibile. Per un template o un'applicazione, preferisci la sua protezione basata sul contesto oppure un collegamento solo testo. Un valore inserito in un nodo di testo HTML, in un URL, in un attributo o in uno script non usa per forza le stesse regole.

Il codificatore non è un sanificatore HTML. Non rende sicuro un template, un link o uno script qualsiasi. Se vuoi solo mostrare testo semplice in un editor, di solito non hai bisogno di codificarlo affatto. Usa la codifica perché la destinazione lo richiede, non perché l'originale contiene punteggiatura.

Codifica un campione di testo letterale per l'HTML

Decodificare un solo livello e controllare che cosa è cambiato

A volte una nota arriva come Borsa & scatola anche se ti serve mostrarla come testo normale. Scegli la decodifica e controlla il risultato prima di applicarlo al testo di partenza. Un passaggio trasforma un riferimento riconosciuto in un carattere; non decodifica ripetutamente finché il risultato smette di cambiare. Questo comportamento conta quando un riferimento compare in un esempio didattico e deve restare visibile invece di essere interpretato.

Per esempio, una stringa che contiene < diventa il riferimento letterale < dopo una decodifica, e un segno di minore dopo un'altra. Decidi quale rappresentazione si aspetta il programma successivo prima di fare un secondo passaggio. Se la fonte è HTML, chiediti se ti serve il testo visibile della pagina o solo il sorgente decodificato. Decodificare i riferimenti non elimina i tag né estrae il testo da un layout.

I riferimenti HTML e la codifica degli URL servono a scopi diversi. I caratteri %26 codificano una e commerciale in un componente di URL; & la rappresenta nel sorgente HTML. Se stai risolvendo un problema con il parametro di un URL copiato, usa il decodificatore di componenti URL sul valore, invece di applicare la decodifica HTML a ogni segno di percentuale.

Decodifica un livello di riferimenti HTML

Seguire un passaggio di consegne realistico con due righe

Prendi i due ticket qui sopra e salva il CSV senza modifiche. Per un'importazione automatica, converti l'intestazione e le righe in oggetti JSON. Formatta il risultato in modo leggibile per poter controllare le chiavi e i due identificatori. Confronta il riepilogo del primo ticket con il CSV: la virgola e la e commerciale devono esserci ancora. Rivedi il secondo riepilogo e conferma che le parentesi angolari restino parte della stringa e non un tag di un template. Usa l'anteprima di importazione per confermare che cosa vede il sistema che riceve i dati.

Per il ticket di revisione, crea una tabella Markdown direttamente dallo stesso CSV e visualizzala nella destinazione. Il risultato è pensato per essere letto da qualcuno, quindi togli le colonne superflue solo in quella copia di presentazione. Se ti serve anche un esempio di codice HTML che mostri un riepilogo, codifica per l'HTML solo il valore di esempio. Non sostituire il riepilogo memorizzato con la versione codificata.

Quando un collega ti chiede quale versione riutilizzare, indica la fonte invariata o l'esportazione concordata leggibile dalle macchine. Etichetta a parte la copia di presentazione. Questa piccola distinzione evita che la tabella copiata da una pagina di documentazione diventi la prossima importazione di dati senza che nessuno si accorga che ha perso dei campi.

Crea una tabella separata per il ticket di revisione

Verificare ogni risultato nell'applicazione che lo riceve

Prima di condividere, controlla il primo e l'ultimo record e un valore difficile a metà. Per il JSON, verifica la sintassi, poi controlla nel programma di importazione i campi attesi e i tipi dei valori. Per il Markdown, guarda l'anteprima della pagina vera e controlla l'intestazione, l'allineamento e ogni punteggiatura che somigli alla sintassi. Per l'HTML, controlla sia il sorgente sia ciò che appare nel browser. Sono controlli diversi: un esito positivo in un formato dice poco sugli altri.

Se una versione non funziona, torna alla fonte salvata e isola il record più piccolo che riproduce il problema. Poi decidi se la fonte è malformata, se l'impostazione di conversione è sbagliata o se la destinazione interpreta il risultato in modo diverso da come ti aspettavi. Evita di convertire ripetutamente l'intero file cambiando più impostazioni insieme: diventa difficile capire quale modifica ha risolto il problema e si può nascondere un'altra perdita di dati.

Conserva un input in miniatura e il risultato atteso come riferimento per la prossima esportazione. Includi un identificatore con zeri iniziali, un campo vuoto e un po' di punteggiatura. Un buon esempio di tre righe rende più facile aggiornare una pipeline in futuro senza dover indovinare che cosa doveva succedere alle righe insolite.

Fai l'ultimo controllo di sintassi JSON prima dell'esportazione