Slovník pojmů

YAML

YAML je formát pro ručně psanou konfiguraci a strukturovaná data. Je přehledný, ale význam odsazení, rozdíly parserů a práce s tajemstvími vyžadují disciplínu: syntakticky platný soubor nemusí být platnou ani bezpečnou konfigurací.

Stručná definice

Čitelná konfigurace, jejíž strukturu určují klíče, seznamy a mezery.

YAML zapisuje mapování klíč–hodnota, sekvence položek a skalární hodnoty jako řetězce, čísla, boolean nebo null. Vnoření se vyjadřuje odsazením mezerami, proto může jediná změna odsazení přesunout hodnotu do jiné části konfigurace. Komentář začíná znakem # a dokument může být oddělen značkou ---, i když většina konfiguračních souborů používá jeden dokument.

YAML není programovací jazyk a jeho úkolem není rozhodovat o chování aplikace. Parser převede text na datovou strukturu, ale cílový nástroj teprve posuzuje, zda jsou klíče známé, hodnoty správného typu a konfigurace bezpečná. To je podstatné například pro CI workflow, Docker Compose nebo OpenAPI dokument.

Jaký problém řeší

Zapsat ručně upravitelnou konfiguraci bez vlastního konfiguračního jazyka.

YAML se používá tam, kde lidé potřebují číst a měnit strukturované nastavení společně s kódem nebo provozní dokumentací.

Docker Compose popisující služby, sítě, volumes a proměnné prostředí
CI/CD workflow s kroky sestavení, testování a nasazování
OpenAPI specifikace cest, schémat, parametrů a odpovědí HTTP API
konfigurace frameworku, monitoringu nebo infrastruktury
přenositelný konfigurační soubor, který nástroj validuje podle vlastní specifikace

Praktický příklad

Konfigurace služby bez produkčního hesla.

Příklad obsahuje název prostředí, odkaz na databázi přes proměnnou prostředí a seznam povolených funkcí. Hodnota DATABASE_URL je pouze název proměnné; skutečné připojovací údaje patří do bezpečně spravovaného prostředí nebo secrets mechanismu, ne do repozitáře.

Cílová aplikace musí ověřit, že databaseUrl existuje, že seznam obsahuje podporované funkce a že prostředí odpovídá pravidlům nasazení. Platný YAML s chybně napsaným klíčem tak není důkazem správné konfigurace.

YAML

service: catalog-import
environment: production
databaseUrl: ${DATABASE_URL}
enabledFeatures:
  - stock-sync
  - price-validation

Jak funguje

Od odsazeného textu k ověřené konfiguraci nástroje.

YAML parser řeší syntaxi; cílový nástroj řeší význam, oprávnění a bezpečný způsob použití hodnot.

Autor zapíše strukturu Klíče mají hodnoty a sekvence začínají pomlčkou. Vnořené bloky používají konzistentní mezery, ne tabulátory pro odsazení.
Parser vytvoří data Parser rozhodne, zda hodnota představuje řetězec, číslo, boolean nebo null podle své verze a pravidel. Nejednoznačné hodnoty je bezpečnější zapisovat explicitně jako řetězce.
Nástroj ověří vlastní schéma Docker Compose, CI systém nebo OpenAPI validátor kontroluje podporované klíče, povinná pole a další pravidla. Správný YAML s překlepem v klíči nemusí udělat to, co autor čekal.
Hodnoty se předají bezpečně Konfigurace odkazuje na proměnnou prostředí nebo správce secrets; do repozitáře nepatří skutečné produkční heslo, token ani soukromý klíč.
Změna se testuje Validace, lint a bezpečné spuštění v odpovídajícím prostředí odhalí chybu odsazení i provozní dopad dříve než produkční nasazení.

Důležité pojmy

Mapování, sekvence, skalár a význam odsazení.

Čitelnost YAML stojí na jednoduché struktuře. Složitá magie s kotvami či automatickou interpretací hodnot ji rychle ztrácí.

Mapování

Mapování přiřazuje klíči hodnotu, například environment: production. Klíč může mít vnořenou mapu, jejíž rozsah určují mezery na začátku řádku.

Sekvence

Seznam položek začíná pomlčkou. Hodí se například pro povolené funkce, kroky pipeline nebo pojmenované služby. Pořadí může mít význam, pokud jej tak chápe cílový nástroj.

Skalární hodnota

Řetězec, číslo, boolean nebo null. Aby parser neměnil očekávaný řetězec na jiný typ, je u nejednoznačné hodnoty vhodné použít uvozovky a ověřit pravidla konkrétního parseru.

Komentáře a více řádků

Komentář pomáhá vysvětlit záměr, ale nemá nahrazovat dokumentaci. YAML umí víceřádkový text, který je vhodný jen tehdy, pokud cílový nástroj jeho přesný tvar očekává.

Kotvy a aliasy

Kotvy mohou zopakovat část struktury, ale rozsáhlé použití zhoršuje dohledatelnost výsledné konfigurace. U nedůvěryhodného vstupu mohou být navíc relevantní limity parseru.

Vztah k podobným pojmům

YAML je zápis dat; JSON, XML a nástroje nad ním řeší jiné potřeby.

Volba formátu nepřenáší automaticky jeho bezpečnost ani sémantiku do cílové aplikace.

JSON: JSON má přísnější a menší syntaxi a je běžný v API. YAML je obvykle pohodlnější pro ruční konfiguraci, ale více závisí na odsazení a parseru.
XML: XML používá elementy, atributy a namespaces, často v integračních kontraktech. YAML je typicky konfigurační formát, nikoli náhrada každého XML schématu.
OpenAPI: OpenAPI dokument lze zapsat v YAML nebo JSON. Formát zápisu není sám specifikací ani nedokazuje správný návrh API.
Docker a CI/CD: Tyto nástroje YAML často používají jako vstup. Každý má ale vlastní verzi konfigurace, vlastní validátor a odlišná pravidla pro proměnné či secrets.

Výhody a omezení

Dobře čitelný formát, který vyžaduje zdrženlivou konfiguraci.

Přínosy

mapování a seznamy jsou snadno čitelné při code review
komentáře umožní vysvětlit provozní záměr u konfigurace
jeden formát používají běžné nástroje pro infrastrukturu, CI/CD i API dokumentaci
konfigurace může zůstat verzovaná vedle zdrojového kódu a testů

Omezení a chyby

odsazení je součástí syntaxe a jeden špatný řádek může změnit strom dat
hodnoty mohou různé parsery či verze interpretovat jinak, zejména u nejednoznačných skalárů
syntaktická platnost neověřuje podporu konkrétního klíče ani bezpečnost nasazení
nechráněné secrets v YAML snadno skončí v repozitáři, CI logu nebo historii commitu
složité kotvy, aliasy a rozsáhlé vnoření zhoršují čitelnost a diagnostiku

Praktické použití

Konfiguraci držet malou, validovanou a oddělenou od tajných hodnot.

V projektu může YAML pojmenovat službu, prostředí, závislosti a seznam povolených funkcí. Připojovací heslo do něj ale nepatří jako prostý text. Bezpečnější je odkaz na proměnnou prostředí nebo podporovaný secrets mechanismus nasazovací platformy; tým pak odděleně spravuje přístup a rotaci tajných hodnot.

Nedůvěryhodný YAML se nemá deserializovat do libovolných objektů. Výběr parseru a jeho bezpečného režimu záleží na jazyce, ale platí obecné pravidlo: přijímat jen očekávané datové typy, nastavit limity a nepovolovat chování, které z textu vytváří proveditelný objekt nebo volá externí zdroje. Po parsování následuje validace schématu konkrétního nástroje.

Na co myslet

Zápis zjednodušit, validovat nástrojem a bezpečně pracovat se secrets.

Dobrá YAML konfigurace je krátká, jednoznačná a ověřitelná při lokálním vývoji i v CI.

používat konzistentní odsazení mezerami a kontrolovat soubor formatterem nebo validátorem cílového nástroje
nejednoznačné hodnoty zapisovat jako řetězec a ověřit typovou interpretaci konkrétní implementace
neukládat produkční hesla, tokeny ani privátní klíče přímo do verzovaného YAML
u vstupu od jiného systému použít bezpečný parser bez automatického vytváření objektů a s limity zdrojů
testovat konfiguraci v podobném prostředí, protože syntaktická chyba a neplatná konfigurace jsou odlišné problémy
složité kotvy a aliasy nahrazovat raději jasně pojmenovanou společnou konfigurací, pokud tím neztratíte význam

Časté otázky

YAML v praxi

Je YAML programovací jazyk?

Ne. YAML zapisuje strukturovaná data. To, co s nimi nástroj udělá, určuje jeho vlastní konfigurace a implementace.

Je YAML lepší než JSON?

Ne obecně. YAML bývá pohodlnější pro ruční konfiguraci a komentáře, JSON má přísnější jednodušší syntaxi a je obvyklý v API. Volba závisí na konkrétním kontraktu a nástroji.

Mohu dát secret přímo do YAML?

Produkční tajný údaj do verzovaného souboru nepatří. Použijte proměnnou prostředí nebo podporovaný secrets mechanismus a omezte přístup i logování hodnot.

Stačí, že YAML projde parserem?

Nestačí. Parser ověřuje syntaxi. Cílový nástroj a aplikace musí ověřit podporované klíče, typy, požadované hodnoty i bezpečné provozní nastavení.

Jak udržuji konfiguraci v provozu

Konfigurační soubory verzujeme, validujeme a oddělujeme od tajných hodnot.

Při vývoji a nasazování propojuji konfiguraci aplikace s testy, CI kontrolami a bezpečným předáním hodnot mezi prostředími.

Jak pracuji s testováním a kvalitou Nezávazně probrat projekt