Formatar e indentar XML

A formatação XML (também chamada formatação XML, indentação XML ou pretty print) consiste em reorganizar um documento XML compacto ou minificado numa estrutura indentada, legível linha a linha. Um XML bem formatado melhora a legibilidade humana, o que é indispensável quando se tem de ler uma resposta SOAP, percorrer um feed RSS ou inspecionar o conteúdo de um ficheiro de configuração.

Concretamente, formata-se XML por quatro razões principais:

• Debug: detetar rapidamente uma tag não fechada, um atributo em falta ou uma estrutura incoerente.
• Integração manual: copiar de forma limpa um fragmento para um ficheiro de configuração sem partir a indentação existente.
• Code review: comparar duas versões de um documento XML num diff do Git torna-se legível quando cada tag está na sua própria linha.
• Documentação e exemplos: um XML formatado é muito mais pedagógico numa documentação técnica ou num README.

O XML continua omnipresente no ecossistema de software. Eis os formatos em que os programadores mais frequentemente utilizam um formatador XML:

• Respostas SOAP: os envelopes <soap:Envelope> devolvidos por web services SOAP chegam geralmente minificados.
• Feeds RSS e Atom: para inspecionar ou auditar um feed de sindicação.
• Configurações Spring, Maven (pom.xml), Ant, Ivy: ficheiros de build e dependências Java.
• AndroidManifest.xml e outros recursos XML de um projeto Android.
• Ficheiros SVG: um gráfico vetorial exportado a partir de um software de design vem muitas vezes comprimido numa única linha.
• Exportações de e-commerce: feeds de produtos Google Shopping, exportações Magento, Shopify ou PrestaShop.
• Documentos OOXML: os ficheiros .docx, .xlsx e .pptx são arquivos ZIP que contêm ficheiros XML frequentemente necessários de inspecionar.
• Sitemaps XML: os sitemap.xml servidos aos motores de busca.

Um formatador XML não se limita a acrescentar espaços ao acaso. Efetua duas etapas:

1. Parsing: o documento é lido e depois transformado em árvore DOM (Document Object Model). Esta etapa valida também que o XML é bem formado (tags corretamente encadeadas, atributos entre aspas, um único elemento raiz).
2. Serialização indentada: a árvore DOM é re-emitida sob forma de texto com quebras de linha entre elementos e uma indentação proporcional à profundidade na árvore.

Esta abordagem por árvore garante que a estrutura lógica do documento se mantém estritamente idêntica: apenas os espaços não significativos entre tags são modificados. As secções CDATA, os comentários e as instruções de processamento são preservados. As transformações mais avançadas (XSLT) ou as queries (XPath) operam, aliás, sobre esta mesma árvore DOM.

O procedimento é voluntariamente simples:

1. Cole o seu documento XML na área de texto, ou carregue um ficheiro .xml.
2. Valide o formulário: o documento é analisado e indentado automaticamente.
3. O resultado formatado aparece na área de saída. Em caso de erro de parsing, uma mensagem indica a natureza e a posição aproximada do problema.
4. Copie o resultado com o botão dedicado, ou descarregue-o para o integrar diretamente no seu projeto.

Algumas convenções a respeitar para produzir um XML limpo e duradouro:

• Indentação: 2 ou 4 espaços consoante a convenção da sua equipa. Mantenha-se coerente em todo o projeto.
• Quebras de linha: um elemento por linha, o que torna os diffs do Git utilizáveis.
• Secções CDATA: um bom formatador conserva integralmente os blocos <![CDATA[ ... ]]> sem reindentar o seu conteúdo, que é tratado como texto bruto.
• Codificação: declare sempre a codificação na primeira linha com <?xml version="1.0" encoding="UTF-8"?>. UTF-8 é o padrão de facto.
• Atributos: se um elemento tem muitos atributos, algumas equipas passam-nos para linha separada para legibilidade; caso contrário ficam na mesma linha que a tag de abertura.
• Comentários: <!-- ... --> devem ser conservados tal como estão pelo formatador.

Eis um exemplo concreto de um XML compacto embelezado pelo formatador.

Antes (uma única linha, ilegível):

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

Depois (formatado com 2 espaços):

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

A estrutura lógica é estritamente idêntica: só a disposição visual muda.

Um documento XML mais volumoso depois da formatação tem este aspeto:

<?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>