Zápis XML syntaxe požadavků a odpovědí

Tato stránka určuje jednotnou notaci, kterou se v celé kapitole Protokol požadavků zapisuje struktura XML požadavků a odpovědí. Jednotlivé stránky požadavků tuto notaci používají, ale samy ji znovu nevysvětlují.

Obálka <request> a <response>

Každý požadavek se posílá zabalený v <request>...</request>, každá odpověď se vrací zabalená v <response>...</response>. Ukázky syntaxe na stránkách jednotlivých požadavků tuto obálku zobrazují jako prázdný kontext kolem konkrétního uzlu, bez vlastních atributů obálky – možnosti obálky (např. transakční zpracování, volba role, upovídanost odpovědi) jsou společné pro víc požadavků a jejich popis patří na samostatnou stránku, ne na stránku jednotlivého požadavku.

Blok syntaxe

Struktura se zapisuje jako jeden nezformátovaný blok kódu s jedním kořenovým elementem pro daný uzel. Vnořené elementy jsou odsazené o jednu úroveň. Atributy se píší každý na vlastní řádek ve tvaru jméno="{typ}".

  <element
   atribut="{typ}"
   >
   <potomek ... /> *
  </element>

Multiplicita potomků

Za ukázkou potomka (za jeho uzavřením, oddělené mezerou) je znak násobnosti:

• (bez znaku) – potomek se vyskytuje právě jednou a je povinný.
• ? – potomek se vyskytuje nula nebo jednou.
• * – potomek se vyskytuje nula a vícekrát.
• + – potomek se vyskytuje jednou a vícekrát.

Atributy

Každý atribut je popsán v seznamu pod blokem syntaxe v jednotném tvaru:

• jméno - Popisný název - Věcný popis významu a vlivu na zpracování. (typ: string/number/bool/enum/datetime; povinný/nepovinný; výchozí: hodnota, je-li definována; povolené hodnoty: a, b, c, jde-li o výčet)

Typ bool nabývá hodnot true/false (přesně tak, jak je server porovnává – u odchylek se to uvede zvlášť). Typ enum vyjmenovává všechny přípustné hodnoty; pokud server neznámou hodnotu tiše ignoruje nebo nahrazuje výchozí, uvede se to výslovně u atributu, ne jen v prozaickém textu jinde na stránce.

Atribut, jehož neuvedení server toleruje, se označuje jako nepovinný i tehdy, když ho stará dokumentace uváděla jako povinný – rozhoduje výhradně chování serveru.

Závislosti

Pokud platnost nebo povinnost jednoho atributu/potomka závisí na hodnotě jiného, uvádí se to jako krátké prozaické pravidlo v sekci „Parametry a pravidla“ dané stránky, například:

Element B je povinný, pokud A = "x".

Sekce se vynechává, pokud u požadavku žádná taková závislost není.

Význam prázdné, chybějící a mazací hodnoty

Pokud se chování serveru liší mezi chybějícím atributem/elementem, prázdnou hodnotou a explicitním příznakem mazání (např. delete="true"), uvede se to výslovně u daného atributu/elementu. Pokud se neliší (chybějící a prázdné se chovají stejně), sekce se nevytváří.

Pořadí elementů

Pokud server vyžaduje konkrétní pořadí potomků, uvede se to výslovně jednou větou u seznamu potomků. Není-li pořadí vynucováno (většina případů v tomto protokolu), sekce se nevytváří.

Odkazy na sdílené typy

Uzel, který se opakovaně používá napříč více požadavky (typicky error), se nepopisuje znovu na každé stránce. Stránka požadavku jen ukáže jeho výskyt v syntaxi a odkáže na jeho popis v Typy uzlů využívané v požadavcích.

Chybové stavy

Obecný tvar chybového uzlu (např. error s number/severity/detail) je popsán jako sdílený typ. Konkrétní chybové stavy, které daný požadavek skutečně generuje (hodnoty type="error", state, konkrétní descr texty a podmínky, za kterých nastanou), popisuje sekce „Chyby a reakce“ přímo na stránce požadavku.