YAML

YAML to czytelny dla człowieka format zapisu danych ustrukturyzowanych, wykorzystywany w konfiguracjach.

YAML jako format opisu danych i konfiguracji

YAML, od angielskiego „YAML Ain’t Markup Language”, jest tekstowym formatem serializacji danych. Służy do zapisywania informacji ustrukturyzowanych w postaci łatwej do odczytania i edycji przez człowieka. W pliku YAML można przechowywać między innymi wartości konfiguracyjne, listy elementów, parametry uruchomieniowe oraz dane przekazywane między programami. Format nie jest językiem programowania: sam opisuje dane, natomiast sposób ich wykorzystania zależy od aplikacji, która plik odczytuje.

Struktura YAML wynika przede wszystkim z wcięć, znaków specjalnych i położenia tekstu w kolejnych wierszach. Para klucz-wartość ma postać klucz: wartość, a element listy rozpoczyna się od myślnika. Przykładowy zapis może wyglądać następująco: tryb: test oraz port: 8080. Wcięcia pokazują zagnieżdżenie danych, dlatego ich zmiana może zmienić znaczenie całego dokumentu. Do wcięć należy używać spacji; tabulatory nie są dozwolone jako znaki wcięcia strukturalnego.

Mapy, listy, wartości i komentarze w pliku YAML

Najczęściej spotykanymi typami danych w YAML są mapowania, sekwencje i skalary. Mapowanie przypomina słownik lub obiekt z nazwami pól, na przykład użytkownik: z dalszymi właściwościami zapisanymi pod spodem. Sekwencję można zapisać jako kolejne wiersze rozpoczynające się od -, na przykład listę urządzeń albo nazw modułów. Skalary obejmują tekst, liczby, wartości logiczne i wartości puste. Tekst można ująć w apostrofy lub cudzysłowy, gdy zawiera znaki, które parser mógłby potraktować jako składnię.

W YAML komentarz rozpoczyna znak # znajdujący się poza wartością tekstową. Komentarze są ignorowane podczas odczytu danych i mogą wyjaśniać przeznaczenie konkretnej opcji. Dłuższy tekst da się zapisać za pomocą bloku literalnego oznaczonego pionową kreską |, który zachowuje znaki końca wiersza, albo bloku składanego oznaczonego znakiem >, w którym kolejne wiersze są zwykle łączone w jeden akapit. Pojedynczy dokument może rozpoczynać się od dyrektywy %YAML, a znacznik --- oddziela początek dokumentu; separator ... może oznaczać jego koniec.

YAML 1.2 został opublikowany przez organizację YAML jako specyfikacja formatu i wprowadził zgodność modelu danych z JSON-em w zakresie podstawowych struktur. Oznacza to, że poprawny dokument JSON może być jednocześnie interpretowany jako YAML 1.2, ale nie każdy plik YAML jest poprawnym JSON-em. W praktyce konkretna aplikacja może obsługiwać tylko wybrany podzbiór składni albo stosować własne reguły interpretacji typów. Z tego powodu sam fakt, że plik wygląda poprawnie, nie gwarantuje zgodności z każdym parserem YAML.

Walidacja składni oraz typowe błędy interpretacji

Najczęstszą przyczyną problemów z YAML jest niespójne wcięcie. Element należący do mapowania musi znajdować się na właściwym poziomie względem klucza nadrzędnego. Błąd może powstać również wtedy, gdy w jednym miejscu użyto tabulatora, pomylono dwukropek z częścią tekstu albo umieszczono znak komentarza bez cudzysłowu w wartości, która miała zawierać znak #. Parser zazwyczaj zgłasza wtedy błąd składni wraz z numerem wiersza, lecz rzeczywista przyczyna może znajdować się kilka znaków wcześniej, na przykład w niezamkniętym cudzysłowie.

Ostrożności wymagają także wartości, które parser może automatycznie zaklasyfikować jako liczby, wartości logiczne lub daty. Wpis 8080 może zostać odczytany jako liczba, a nie jako tekst. Podobnie zapis przeznaczony do wyświetlenia dosłownie może zostać zmieniony znaczeniowo, jeśli nie zostanie ujęty w cudzysłowy. Wersja specyfikacji i biblioteka użyta przez program mają znaczenie, ponieważ różne implementacje mogą odmiennie rozpoznawać niektóre nieujęte wartości. Przy konfiguracjach wymagających dokładnych typów warto jawnie stosować cudzysłowy oraz sprawdzać dokumentację używanej aplikacji.

YAML obsługuje kotwice i aliasy. Kotwica, zapisywana przy użyciu &, pozwala nadać nazwę fragmentowi danych, a alias z prefiksem * może odwołać się do tego fragmentu w innym miejscu. Mechanizm ten ogranicza powielanie konfiguracji, ale utrudnia ręczne śledzenie zależności. Parsery mogą również obsługiwać tagi określające sposób interpretacji wartości. Dokument pochodzący z nieznanego źródła powinien być analizowany przez bibliotekę skonfigurowaną do bezpiecznego odczytu danych, bez uruchamiania konstrukcji przeznaczonych dla rozszerzeń konkretnego języka programowania. Walidacja składni nie zastępuje walidacji znaczenia: plik może być poprawnym YAML-em, a mimo to zawierać nieprawidłowy port, nieistniejącą ścieżkę lub literówkę w nazwie opcji.

YAML w konfiguracji laptopów i komputerów PC

Na komputerach domowych i biurowych pliki YAML mogą występować w narzędziach programistycznych, systemach automatyzacji, konfiguracjach edytorów oraz aplikacjach korzystających z tekstowych ustawień. Sam plik jest zwykłym plikiem tekstowym, więc można go otworzyć w edytorze kodu lub innym edytorze obsługującym kodowanie UTF-8. Do sprawdzenia poprawności potrzebny jest parser lub narzędzie właściwe dla programu, który ma ten plik wykorzystać. Zwykłe otwarcie dokumentu w edytorze nie wykryje błędów logicznych, takich jak niewłaściwa nazwa klucza.

Podczas diagnostyki komputera warto ustalić, który program odczytuje dany plik, jaka wersja jego parsera jest używana i w jakim katalogu znajduje się konfiguracja. Należy też sprawdzić, czy aplikacja wymaga dokładnie jednego dokumentu, czy dopuszcza wiele dokumentów rozdzielonych przez ---. Zmiana wcięcia, nazwy klucza albo typu wartości może spowodować, że program odmówi uruchomienia lub zastosuje wartość domyślną. Bezpieczna modyfikacja polega na zachowaniu kopii pierwotnego pliku, wykonaniu kontroli składni oraz uruchomieniu aplikacji z obserwacją komunikatów błędu. Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i ich podzespołów, a w ramach diagnozy może również sprawdzić pliki konfiguracyjne YAML związane z działaniem używanego oprogramowania.