YAML — co to jest i jak pisać pliki .yml bez błędów

Do czego służy YAML

YAML to format zapisu danych, czytelny dla człowieka. Spotyka się go w plikach konfiguracyjnych: Docker Compose, GitHub Actions, Kubernetes, Ansible czy ustawieniach generatorów stron. Ten sam zestaw danych można zapisać jako JSON, który opisuje poradnik co to jest JSON. YAML jest jednak krótszy, bo nie wymaga nawiasów ani cudzysłowów przy większości tekstów.

Podstawy składni

nazwa: AMKBIT
wersja: 2
aktywny: true
tagi:
  - kalkulatory
  - narzędzia
ustawienia:
  motyw: ciemny

• Para klucz–wartość to klucz, dwukropek i spacja.
• Lista to wiersze zaczynające się od myślnika i spacji.
• Zagnieżdżenie wyznacza wcięcie. Używa się spacji, nigdy tabulatora.
• Komentarz zaczyna się od #.

Gotowy JSON zamienisz na taki zapis w konwerterze JSON na YAML.

Najczęstsze pułapki

Wcięcia. Jedna spacja za dużo zmienia strukturę albo daje błąd. Edytor z widocznymi spacjami bardzo pomaga.

Tekst rozumiany jako inny typ. W starszej wersji YAML słowa yes, no, on, off oznaczały wartości logiczne. Słynny przykład to kod kraju Norwegii NO zamieniony na false. Numery z zerem na początku, jak 08, wersje 1.10 czy daty mogą zostać odczytane jako liczby lub daty. Bezpieczniej ująć je w cudzysłów.

Dwukropek w tekście. Wartość „godzina: 12:30” wymaga cudzysłowu, bo dwukropek ze spacją ma specjalne znaczenie.

Znaki specjalne na początku. Teksty zaczynające się od @, *, &, ! lub % trzeba cytować.

YAML a JSON

Każdy poprawny JSON jest też poprawnym YAML w wersji 1.2, ale nie odwrotnie. JSON lepiej sprawdza się w wymianie danych między programami, bo jest prostszy i szybciej przetwarzany. YAML wygrywa w plikach edytowanych ręcznie dzięki komentarzom i czytelności. Przed konwersją warto sprawdzić JSON w formaterze JSON. Gdy dane przychodzą w XML, uporządkuje je formater XML.

Teksty wielowierszowe

Znak | zachowuje podziały linii, a > skleja wiersze w jeden akapit. Przydaje się to przy dłuższych opisach lub skryptach w konfiguracji CI.

Gdzie spotkasz YAML na co dzień

Harmonogramy zadań w CI zapisuje się w YAML wyrażeniami cron, opisanymi w poradniku cron — harmonogram zadań. Nagłówki wpisów w generatorach stron, tak zwany front matter, to YAML umieszczony na początku pliku Markdown, o którym pisze poradnik Markdown — podstawy.