YAML

Definicja

YAML to format zapisu danych, wygodny do pisania i czytania przez ludzi. Zamiast nawiasów i cudzysłowów używa wcięć. Nazwa to rekurencyjny skrót od „YAML Ain't Markup Language”. Format opisuje specyfikacja YAML.

Przykład z tymi samymi danymi co w haśle JSON:

imie: Anna
dzial: Sprzedaż
szkolenia:
  - WCAG
  - AI w praktyce
aktywna: true

Co to w zasadzie jest?

Dane w parach „nazwa: wartość”, każda w osobnej linii.
Listy jako linie zaczynające się od myślnika.
Wcięcia mają znaczenie: jedna spacja za dużo albo za mało zmienia sens albo psuje plik.

YAML a JSON

JSON jest wygodniejszy dla programów (API, wymiana danych).
YAML jest wygodniejszy dla ludzi (pliki konfiguracyjne, które ktoś pisze i poprawia).
Większość danych da się zapisać w obu formatach.

Gdzie go spotykasz

Konfiguracja stron i narzędzi, np. plik mkdocs.yml serwisu aiholics.pl.
Automatyczne testy i wdrożenia w GitHub Actions.
Front matter: blok YAML na górze pliku Markdown, np. title, category, tags w każdym haśle tego pojęciownika.
Definicje agentów AI i skilli, np. nagłówek pliku SKILL.md (skille).

Praktyczne zastosowania (konkretne scenariusze)

Scenariusz 1: Zmiana ustawień strony

Cel: dodać pozycję do menu serwisu.
Wejście: plik konfiguracyjny .yml.
Kroki: dopisz linię z zachowaniem wcięć sąsiednich linii → zbuduj stronę testowo.
Rezultat: nowa pozycja w menu.
Zabezpieczenie: zmiana przez PR i podgląd przed publikacją.

Scenariusz 2: Opis asystenta lub skilla

Cel: agent ma wiedzieć, kiedy użyć danej instrukcji.
Wejście: nagłówek YAML z nazwą i opisem.
Kroki: wpisz name i description jasnym językiem.
Rezultat: agent poprawnie wybiera skill.
Zabezpieczenie: test na przykładowym zadaniu.

Typowe błędy i pułapki

Tabulator zamiast spacji.
Niespójne wcięcia w tej samej liście.
Dwukropek w wartości bez cudzysłowu (np. tytuł: Plan: wersja 2).

Ryzyka i jak je ograniczać

Ryzyko 1: Cicha zmiana sensu

Ryzyko: złe wcięcie przypisuje wartość do innego elementu, a plik nadal się wczytuje.
Jak ograniczać: walidacja i test (np. zbudowanie strony) po każdej zmianie.

Ryzyko 2: Zepsuta konfiguracja

Ryzyko: narzędzie lub strona przestaje działać.
Jak ograniczać: kontrola wersji i zmiany przez PR z podglądem.

Checklista “zanim użyjesz”

Czy wcięcia są takie jak w sąsiednich liniach?
Czy w pliku nie ma tabulatorów?
Czy wartości z dwukropkiem są w cudzysłowie?
Czy po zmianie zrobiłeś test?

Diagram

flowchart LR
    A[Człowiek pisze YAML]
    B[Walidacja lub test]
    C[Narzędzie czyta konfigurację]
    D[Strona, agent lub test działa]
    A --> B --> C --> D

Diagram pokazuje, że człowiek pisze konfigurację w YAML, a przed użyciem przez narzędzie warto ją sprawdzić testem.