XML opmaken en inspringen

XML-opmaak (ook wel XML-formatting, XML-inspringing of pretty print genoemd) bestaat uit het reorganiseren van een compact of geminificeerd XML-document in een ingesprongen structuur, regel voor regel leesbaar. Goed opgemaakte XML verbetert de menselijke leesbaarheid, wat onmisbaar is wanneer men een SOAP-antwoord moet lezen, een RSS-feed moet doorlopen of de inhoud van een configuratiebestand moet inspecteren.

Concreet maakt men zijn XML op om vier hoofdredenen:

• Debug: snel een niet-gesloten tag, een ontbrekend attribuut of een inconsistente structuur opsporen.
• Handmatige integratie: een fragment netjes kopiëren in een configuratiebestand zonder de bestaande inspringing te breken.
• Code review: twee versies van een XML-document vergelijken in een Git-diff wordt leesbaar wanneer elke tag op zijn eigen regel staat.
• Documentatie en voorbeelden: een opgemaakte XML is veel pedagogischer in technische documentatie of een README.

XML blijft alomtegenwoordig in het software-ecosysteem. Dit zijn de formaten waarop ontwikkelaars het vaakst een XML-opmaker gebruiken:

• SOAP-antwoorden: de <soap:Envelope>-enveloppen die door SOAP-webservices worden geretourneerd, komen meestal geminificeerd aan.
• RSS- en Atom-feeds: om een syndicatiefeed te inspecteren of te auditeren.
• Configuraties Spring, Maven (pom.xml), Ant, Ivy: build- en afhankelijkheidsbestanden Java.
• AndroidManifest.xml en andere XML-bronnen van een Android-project.
• SVG-bestanden: een vectorafbeelding geëxporteerd uit ontwerpsoftware is vaak gecomprimeerd op één regel.
• E-commerce-exports: Google Shopping-productfeeds, Magento-, Shopify- of PrestaShop-exports.
• OOXML-documenten: de bestanden .docx, .xlsx en .pptx zijn ZIP-archieven met XML-bestanden die vaak moeten worden geïnspecteerd.
• XML-sitemaps: de sitemap.xml die aan zoekmachines wordt geserveerd.

Een XML-opmaker beperkt zich niet tot het willekeurig toevoegen van spaties. Hij voert twee stappen uit:

1. Parsing: het document wordt gelezen en omgezet in een DOM-boom (Document Object Model). Deze stap valideert ook dat de XML wel gevormd is (correct geneste tags, attributen tussen aanhalingstekens, één enkel root-element).
2. Ingesprongen serialisatie: de DOM-boom wordt opnieuw uitgezonden als tekst met regeleinden tussen de elementen en een inspringing die evenredig is aan de diepte in de boom.

Deze boombenadering garandeert dat de logische structuur van het document strikt identiek blijft: alleen de niet-significante spaties tussen tags worden gewijzigd. De CDATA-secties, de commentaren en de verwerkingsinstructies worden bewaard. De meer geavanceerde transformaties (XSLT) of de queries (XPath) opereren overigens op diezelfde DOM-boom.

De procedure is bewust eenvoudig:

1. Plak uw XML-document in het tekstgebied, of upload een .xml-bestand.
2. Valideer het formulier: het document wordt automatisch geanalyseerd en ingesprongen.
3. Het opgemaakte resultaat verschijnt in het uitvoergebied. In geval van een parse-fout geeft een bericht de aard en de geschatte positie van het probleem aan.
4. Kopieer het resultaat met de daarvoor bestemde knop, of download het om het direct in uw project te integreren.

Enkele conventies om te respecteren om schone en duurzame XML te produceren:

• Inspringing: 2 of 4 spaties afhankelijk van de conventie van uw team. Blijf consistent in het hele project.
• Regeleinden: één element per regel, wat de Git-diffs bruikbaar maakt.
• CDATA-secties: een goede opmaker bewaart volledig de blokken <![CDATA[ ... ]]> zonder de inhoud te herinprongen, die als ruwe tekst wordt behandeld.
• Codering: declareer altijd de codering op de eerste regel met <?xml version="1.0" encoding="UTF-8"?>. UTF-8 is de feitelijke standaard.
• Attributen: als een element veel attributen heeft, plaatsen sommige teams ze op een nieuwe regel voor de leesbaarheid; anders blijven ze op dezelfde regel als de openingstag.
• Commentaren: <!-- ... --> moeten als zodanig door de opmaker worden bewaard.

Hier is een concreet voorbeeld van compacte XML verfraaid door de opmaker.

Voor (één enkele regel, onleesbaar):

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

Na (opgemaakt met 2 spaties):

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

De logische structuur is strikt identiek: alleen de visuele rangschikking verandert.

Een groter XML-document na opmaak ziet er zo uit:

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