Formattare e indentare XML

La formattazione XML (chiamata anche messa in forma XML, indentazione XML o pretty print) consiste nel riorganizzare un documento XML compatto o minificato in una struttura indentata, leggibile riga per riga. Un XML ben formattato migliora la leggibilità umana, cosa indispensabile quando si deve leggere una risposta SOAP, scorrere un flusso RSS o ispezionare il contenuto di un file di configurazione.

Concretamente, si formatta il proprio XML per quattro ragioni principali:

• Debug: individuare rapidamente un tag non chiuso, un attributo mancante o una struttura incoerente.
• Integrazione manuale: copiare in modo pulito un frammento in un file di configurazione senza rompere l'indentazione esistente.
• Code review: confrontare due versioni di un documento XML in un diff Git diventa leggibile quando ogni tag è sulla propria riga.
• Documentazione ed esempi: un XML formattato è molto più pedagogico in una documentazione tecnica o un README.

L'XML resta onnipresente nell'ecosistema software. Ecco i formati su cui gli sviluppatori usano più spesso un formattatore XML:

• Risposte SOAP: le buste <soap:Envelope> restituite dai web service SOAP arrivano generalmente minificate.
• Flussi RSS e Atom: per ispezionare o auditare un flusso di sindacazione.
• Configurazioni Spring, Maven (pom.xml), Ant, Ivy: file di build e dipendenze Java.
• AndroidManifest.xml e altre risorse XML di un progetto Android.
• File SVG: un grafico vettoriale esportato da un software di design è spesso compresso su una sola riga.
• Export e-commerce: flussi prodotto Google Shopping, export Magento, Shopify o PrestaShop.
• Documenti OOXML: i file .docx, .xlsx e .pptx sono archivi ZIP che contengono file XML che spesso bisogna ispezionare.
• Sitemap XML: i sitemap.xml serviti ai motori di ricerca.

Un formattatore XML non si limita ad aggiungere spazi a caso. Effettua due passaggi:

1. Parsing: il documento viene letto poi trasformato in albero DOM (Document Object Model). Questa fase valida anche che l'XML sia ben formato (tag correttamente nidificati, attributi tra virgolette, un solo elemento radice).
2. Serializzazione indentata: l'albero DOM viene riemesso come testo con a capo tra gli elementi e un'indentazione proporzionale alla profondità nell'albero.

Questo approccio ad albero garantisce che la struttura logica del documento resti strettamente identica: solo gli spazi non significativi tra i tag vengono modificati. Le sezioni CDATA, i commenti e le istruzioni di elaborazione sono preservati. Le trasformazioni più avanzate (XSLT) o le query (XPath) operano d'altronde sullo stesso albero DOM.

La procedura è volutamente semplice:

1. Incollate il vostro documento XML nella zona di testo, o caricate un file .xml.
2. Validate il form: il documento viene analizzato e indentato automaticamente.
3. Il risultato formattato appare nella zona di output. In caso di errore di parsing, un messaggio indica la natura e la posizione approssimativa del problema.
4. Copiate il risultato con il pulsante dedicato, o scaricatelo per integrarlo direttamente nel vostro progetto.

Alcune convenzioni da rispettare per produrre un XML pulito e durevole:

• Indentazione: 2 o 4 spazi a seconda della convenzione del vostro team. Restate coerenti in tutto il progetto.
• A capo: un elemento per riga, il che rende sfruttabili i diff Git.
• Sezioni CDATA: un buon formattatore conserva integralmente i blocchi <![CDATA[ ... ]]> senza reindentare il loro contenuto, che viene trattato come testo grezzo.
• Encoding: dichiarate sempre l'encoding nella prima riga con <?xml version="1.0" encoding="UTF-8"?>. UTF-8 è lo standard di fatto.
• Attributi: se un elemento ha molti attributi, alcuni team li mandano a capo per la leggibilità; altrimenti restano sulla stessa riga del tag di apertura.
• Commenti: <!-- ... --> devono essere conservati così come sono dal formattatore.

Ecco un esempio concreto di un XML compatto abbellito dal formattatore.

Prima (una sola riga, illeggibile):

<root><item id="1">val</item><item id="2">val2</item></root>

Dopo (formattato con 2 spazi):

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <item id="1">val</item>
  <item id="2">val2</item>
</root>

La struttura logica è strettamente identica: cambia solo la disposizione visiva.

Un documento XML più voluminoso dopo la formattazione assomiglia a questo:

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <user id="12345">
    <name>John Doe</name>
    <email>johndoe@example.com</email>
    <address>
      <street>123 Main St</street>
      <city>Springfield</city>
      <state>IL</state>
      <postalCode>62704</postalCode>
      <country>USA</country>
    </address>
    <phoneNumbers>
      <phoneNumber type="home">555-1234</phoneNumber>
      <phoneNumber type="work">555-5678</phoneNumber>
    </phoneNumbers>
    <preferences>
      <newsletter>true</newsletter>
      <theme>dark</theme>
    </preferences>
    <lastLogin>2024-06-14T09:30:00Z</lastLogin>
  </user>
</root>