Convertire XML in YAML

XML spende all’incirca metà dei suoi caratteri per dire dove finisce un elemento. YAML lo dice con l’indentazione, quindi lo stesso documento esce molto più corto e ogni livello di annidamento è un passo visivo invece di una coppia da individuare a colpo d’occhio. Su un pom Maven o un web.config è la differenza fra scorrere e leggere.

La struttura resta invariata. Ogni elemento diventa una chiave, i suoi figli diventano la mappa sottostante e il testo diventa il valore. Niente viene riordinato e niente viene riassunto, quindi ciò che si vede è lo stesso documento con la punteggiatura tolta — esattamente quello che serve quando lo scopo è capire cosa dice il file.

Gli attributi arrivano come chiavi con il prefisso @, e un elemento che porta sia attributi sia testo memorizza quel testo sotto la chiave #text. Entrambe vengono scritte fra virgolette, perché YAML tratta @ come un indicatore riservato all’inizio di uno scalare semplice e # come l’inizio di un commento.

Sembra rumore ed è correttezza. Se modificate il file a mano, tenete quelle virgolette: toglierle produce YAML che non si analizza oppure, nel caso di #text, trasforma silenziosamente il resto della riga in un commento perdendo il valore. Vale lo stesso se riscrivete una chiave rimodellando l’output in un file di valori.

È la ragione più forte per fare questa conversione. Confrontare due XML è penoso perché un cambiamento a un livello di profondità mostra diverse righe di tag, e una riformattazione automatica riscrive l’intero file. Convertire entrambe le versioni e confrontare lo YAML mostra i valori cambiati sulla propria riga con il percorso della chiave visibile sopra.

Un avvertimento fa la differenza fra utile e inutile. Poiché un elemento ripetuto una sola volta diventa una mappa e due volte diventano una lista, una versione che aggiunge una seconda dipendenza cambia la forma di quel ramo e non solo il contenuto, quindi il diff mostra l’intero blocco come riscritto. Non è il convertitore che perde informazione — è la forma che cambia davvero — ma saperlo in anticipo evita di leggere un diff grande come un cambiamento grande.

I prefissi sono conservati come parte del nome della chiave, quindi un documento che usa soap: o xsi: produce chiavi con i due punti dentro. Il generatore le scrive senza virgolette, e vengono lette correttamente dallo stesso analizzatore. Le dichiarazioni di namespace stesse sopravvivono come attributi, quindi uno xmlns predefinito arriva come una chiave «@xmlns» fra virgolette sulla radice.

Un due punti dentro una chiave senza virgolette è il genere di cosa da sistemare a mano prima che il file viaggi. Se lo YAML sarà letto da un altro strumento, mettete voi le virgolette a quelle chiavi — non costa nulla e toglie di mezzo una categoria di problema che compare solo nel punto in cui qualcun altro analizza il file. Nulla risolve i prefissi negli URI di namespace corrispondenti, quindi due documenti che usano prefissi diversi per lo stesso namespace producono YAML che non si confronta bene fra loro.

I valori che si leggono come numeri vengono interpretati, sia nel testo degli elementi sia negli attributi. Una versione Maven come 4.13.2 resta stringa, perché ha due punti e non può essere un numero, e lo stesso vale per un indirizzo o un percorso. Un attributo di versione scritto 1.0 diventa 1, e un valore con zeri iniziali scritto 007 diventa 7.

Su una config che si legge e non si esegue il danno è limitato all’aspetto del valore, e conta comunque: una versione di schema resa come 1 invece di 1.0 in una revisione è un valore che qualcuno metterà in discussione o, peggio, copierà. Scorrete una volta i valori dall’aspetto numerico nell’output. Se lo YAML va oltre l’occhio umano, mettete voi le virgolette a quelli pensati come identificativi.

Un valore che contiene ritorni a capo viene scritto come uno scalare a blocco — una barra verticale con il testo indentato sotto — che lo mantiene leggibile invece di comprimerlo su una riga sola. Un valore lungo su una sola riga viene scritto così com’è senza andare a capo. Entrambe sono le scelte giuste per un file pensato per essere letto.

Un elemento vuoto o autochiuso diventa una stringa vuota, scritta come una coppia di virgolette. XML non distingue un elemento vuoto da uno che non contiene nulla, quindi non si perde informazione, ma una stringa vuota è visivamente facile da perdere in un file lungo — se state controllando una config alla ricerca di valori non impostati, cercate le virgolette vuote invece di fidarvi dell’occhio.

XML supporta i commenti, YAML supporta i commenti, e nessuno dei vostri sopravvive. L’analizzatore li scarta e nulla li riscrive. Su un payload è irrilevante; su un file di build è la perdita più grande, perché il commento sopra una versione di dipendenza bloccata è di solito l’unica testimonianza rimasta del perché sia bloccata.

L’assetto che evita la trappola è trattare lo YAML come una copia di lettura e tenere l’XML come sorgente. Se lo YAML deve invece diventare la sorgente — una vera migrazione verso Ansible o un chart Helm — pianificate il passaggio che copia i commenti come parte del lavoro, prima che l’XML venga cancellato e con esso il ragionamento.

Una config convertita non è ancora un file di valori o un insieme di variabili. Porta artefatti XML — le chiavi @, le chiavi #text, una dichiarazione di namespace sulla radice, e magari una chiave ?xml dalla riga di dichiarazione — che non hanno senso per qualunque cosa la stiate alimentando. Eliminarli è il primo passaggio.

Il secondo è la nomenclatura. I nomi degli elementi XML sono spesso prolissi in un modo che aveva senso con uno schema alle spalle, e una config YAML di solito li vuole più corti e piatti. Entrambi i passaggi sono manuali e sono la migrazione vera; la conversione dà solo un punto di partenza leggibile invece di un muro di tag.

Convertite quando l’obiettivo è capire, revisionare o confrontare: lo YAML è più corto, la struttura è evidente e tutto gira nel browser nel tempo che serve a trascinare il file. È una buona abitudine per qualunque config vi venga consegnata e su cui dovete ragionare prima di modificarla.

Non convertite quando il file è validato da uno schema, firmato o consumato da uno strumento che legge XML. In quel caso l’XML è l’oggetto vero, e una copia YAML sarebbe una seconda versione della verità destinata a divergere dalla prima. Leggetelo come YAML, modificatelo come XML.