Slovník pojmů

XML

XML umí zapsat hierarchická data pomocí vlastních elementů, atributů a namespaces. Je přesné a rozšiřitelné, ale jeho parser je nutné konfigurovat bezpečně a datový kontrakt validovat i nad rámec samotné syntaxe.

Stručná definice

Značkovaný datový dokument, ne HTML stránka ani automaticky bezpečný import.

XML dokument má právě jeden kořenový element. Element může obsahovat text, další elementy a atributy; například product může nést identifikátor a jeho potomci name, price a availability. XML deklarace může upřesnit verzi a kódování, ale dokument musí být především dobře formovaný: značky se správně uzavírají, vnoření dává smysl a atributy jsou korektně zapsané.

Dobře formované XML ještě nemusí odpovídat požadovanému katalogu nebo API zprávě. Schéma, například XML Schema, může popsat povolené elementy a datové typy. Aplikace pak navíc ověřuje business pravidla: platnost měny, existenci produktu, oprávnění integrace a to, zda cenu lze podle aktuálního stavu skutečně změnit.

Jaký problém řeší

Předání hierarchických dat mezi systémy s přesně definovanou strukturou.

XML má silné místo tam, kde integrační kontrakt pracuje s vnořením, namespaces nebo existujícím XML schématem.

produktové katalogy, feedy dostupnosti a ceníky dodavatelů
export objednávek, faktur a jiných dokumentů do externího systému
integrační protokoly a standardizované zprávy s XML namespaces
konfigurační či projektové soubory, pokud konkrétní nástroj XML vyžaduje
validovatelné datové výměny, kde se strany dohodly na schématu a verzování

Praktický příklad

Bezpečně zpracovaný XML katalog produktů.

Dodavatel posílá jeden kořen catalog a pro každý produkt stabilní externí identifikátor. Cena je v samostatném elementu s měnou jako atributem; aplikace ji po parsování převede na vhodnou interní hodnotu a teprve potom ověří pravidla importu.

Ukázka nepoužívá DTD ani externí entity. Příjemce musí stále v parseru výslovně zakázat externí rozlišení entit, použít limity velikosti a ověřit, že partner smí upravovat konkrétní katalog.

XML

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
  <product id="SUP-42">
    <name>Trekingový batoh</name>
    <price currency="CZK">2490.00</price>
    <availability>in_stock</availability>
  </product>
</catalog>

Jak funguje

Od XML souboru k ověřené změně v aplikaci.

Bezpečný import odděluje transport, omezené parsování, technickou validaci a business rozhodnutí.

Přijetí a omezení souboru Služba ověří zdroj, velikost, očekávaný MIME typ a případně podpis. Ani přípona .xml ani Content-Type od klienta nejsou samy o sobě důkazem bezpečnosti.
Bezpečné parsování Parser pracuje bez načítání externích entit a bez zbytečného přístupu k síti či souborům. Limity hloubky a velikosti chrání prostředky aplikace.
Kontrola struktury Aplikace ověří kořen, povolené elementy, namespaces, povinná pole a očekávané datové typy. XML Schema pomáhá jen pro pravidla, která opravdu vyjadřuje.
Převod a business validace Text ceny se převede na vhodnou reprezentaci peněz, dostupnost na povolenou hodnotu a identifikátor se spojí s konkrétním tenantem nebo dodavatelem.
Uložení a dohledatelnost Import se zpracuje idempotentně, zapíše výsledek a vrátí bezpečnou chybu. Celý citlivý dokument se neloguje bez potřeby a retenčního pravidla.

Důležité pojmy

Elementy, atributy, namespaces a úrovně platnosti.

XML nabízí víc strukturálních nástrojů než jednoduchý objektový formát, proto je důležité odlišit jejich úlohu.

Element a atribut

Element nese text či další strukturu, atribut doplňuje vlastnost elementu. Volba není jen otázka vkusu: kontrakt má určit, kde která informace patří a jak se rozšiřuje.

Kořen a vnoření

Každý XML dokument má jeden kořen. Strom potomků přirozeně vyjadřuje například katalog, produkt a jeho varianty, ale příliš hluboké stromy zhoršují čitelnost i zpracování.

Namespace

Namespace rozlišuje stejně pojmenované elementy z různých slovníků. URI v deklaraci namespace obvykle slouží jako identifikátor názvového prostoru, ne jako URL, které parser musí navštěvovat.

Dobře formovaný a validní dokument

Dobře formované XML dodržuje syntaxi. Validní XML navíc odpovídá definovanému DTD nebo schématu. Ani jedna úroveň neověřuje automaticky obchodní význam dat.

DTD a externí entity

DTD je starší mechanismus definice struktury. U nedůvěryhodných vstupů se externí entity nepovolují: mohou vést k XXE, nečekanému čtení zdrojů nebo vyčerpání prostředků.

Vztah k podobným pojmům

XML je formát dat; HTML je webový dokument a JSON či YAML jsou jiné zápisy struktury.

Formát vybírejte podle současného kontraktu, interoperabilních potřeb a nástrojů, ne podle obecného žebříčku oblíbenosti.

JSON: JSON zapisuje objekty a pole kompaktněji a je častý v HTTP API. XML naopak přirozeně pracuje s elementy, atributy a namespaces.
YAML: YAML bývá příjemný pro ruční konfiguraci. XML je často vhodnější tam, kde už existuje konkrétní XML schéma či požadavek na namespaces.
HTML: HTML je značkovací jazyk pro webový dokument s předem stanovenou sémantikou prvků. XML vytváří vlastní slovník elementů pro data.
MIME typ a API: XML se v HTTP typicky označí application/xml. API však také určuje endpoint, oprávnění, verzi a konkrétní význam elementů.

Výhody a omezení

Výrazná struktura a schémata za cenu větší složitosti.

Přínosy

hierarchické elementy a namespaces dobře vyjadřují složitější integrační slovníky
schémata mohou formalizovat část kontraktu a generovat validaci či dokumentaci
formát je široce podporovaný ve starších i současných podnikových integracích
textová podoba usnadňuje audit a transport při správném kódování

Omezení a chyby

XML je často verbálnější než JSON a ruční zápis se snáze rozbije špatným vnořením
parser s povolenými externími entitami může otevřít bezpečnostní problém
validní schéma nenahrazuje převod typů, autorizaci ani business pravidla
namespaces a prefixy komplikují dotazování i změnu kontraktu
velké dokumenty je potřeba zpracovávat s limity nebo streamovat místo načtení všeho do paměti

Praktické použití

Volit XML tam, kde je jeho struktura nebo existující ekosystém skutečným přínosem.

Dodavatelský katalog produktů může používat XML, protože jej stejným schématem posílá více odběratelům. Importní služba pro každý soubor ověří velikost, bezpečně parsuje dokument, zkontroluje rozhraní partnera a provede změny po dávkách. Pouhé načtení XML do objektu není dokončený import; ceny, měny, duplicity a skladové stavy potřebují vlastní pravidla.

Pro nově navržené menší HTTP API může být JSON jednodušší, pokud nejsou potřeba XML namespaces či závazné schéma existujícího odvětví. Rozhodnutí není souboj formátů. Záleží na klientech, validaci, operativě, vývojových nástrojích a na tom, zda formát představuje dlouhodobý veřejný kontrakt.

Na co myslet

Nedůvěryhodné XML nejdřív omezit, potom parseovat a validovat.

Bezpečnost se nesmí opírat jen o to, že dokument vypadá jako očekávaný katalog.

zakázat externí entity a DTD tam, kde je nepotřebujete; parser nemá bezdůvodně načítat síť ani lokální soubory
omezit velikost requestu, počet elementů, hloubku a dobu zpracování podle povahy importu
validovat povolený kořen, namespaces, elementy a typy hodnot před změnou databáze
převádět textová data jako cenu, datum a boolean na explicitní aplikační typy
používat UTF-8 a dokumentovat XML deklaraci, pokud ji integrační kontrakt vyžaduje
logovat identifikátor importu a chybu, ne bezdůvodně celé citlivé XML včetně osobních údajů

Časté otázky

XML v praxi

Je XML totéž co HTML?

Ne. HTML má pro web předem definovaný význam elementů. XML je obecný formát, ve kterém si kontrakt definuje vlastní elementy, atributy a případně namespaces.

Je dobře formované XML automaticky validní?

Ne. Dobře formované XML dodržuje syntaxi. Validní XML navíc odpovídá určenému schématu; i potom je nutné ověřit business pravidla.

Proč se u XML mluví o externích entitách?

Některé XML mechanismy mohou odkazovat na externí zdroje. U nedůvěryhodných dokumentů je parser nemá načítat, aby se předešlo XXE a nečekané spotřebě zdrojů.

Mám pro nové API použít XML nebo JSON?

Záleží na klientech a kontraktu. JSON bývá pro menší HTTP API jednodušší, XML může být nutné kvůli existujícímu odvětvovému standardu, namespaces nebo schématu.

Jak pracuji s integračními daty

Externí datový formát propojuji s bezpečným importem, validací a dohledatelností.

U e-commerce a marketplace integrací řeším vedle formátu také identitu partnera, idempotenci, monitoring a bezpečné zpracování chyb.

Jak pracuji s API a integracemi Nezávazně probrat projekt