JSON vs YAML — Różnice wyjaśnione

Pewnie zauważyłeś, że niektóre projekty używają plików .json do konfiguracji, a inne .yaml lub .yml. Oba formaty reprezentują ustrukturyzowane dane. Oba są czytelne dla człowieka. Jaka jest więc realna różnica i kiedy powinno się sięgać po jeden, a kiedy po drugi?

Używałem obu intensywnie — JSON to mój codzienny driver do API i wymiany danych, YAML to mój go-to do manifestów Kubernetes, GitHub Actions i Docker Compose. Rozwiązują podobne problemy, ale mają zupełnie inne osobowości.

Porównanie: ta sama konfiguracja w obu formatach

Oto obiekt konfiguracji bazy danych zapisany w JSON-ie:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp",
    "ssl": true,
    "pool": {
      "min": 2,
      "max": 10
    },
    "replicas": ["replica1.db", "replica2.db"]
  }
}

A tu ta sama konfiguracja w YAML-u:

database:
  host: localhost
  port: 5432
  name: myapp
  ssl: true
  pool:
    min: 2
    max: 10
  replicas:
    - replica1.db
    - replica2.db

YAML jest wyraźnie mniej zagracony. Żadnych cudzysłowów wokół większości stringów, żadnych nawiasów klamrowych, żadnych przecinków. Dla pliku konfiguracyjnego, który ludzie regularnie edytują, ta przejrzystość ma znaczenie. Ale YAML osiąga to, będąc znacznie bardziej złożonym pod maską.

Gdzie YAML błyszczy

• Pliki konfiguracyjne edytowane przez człowieka. Pipeline'y CI/CD (GitHub Actions, GitLab CI), manifesty Kubernetes, Docker Compose, playbooki Ansible — wszystko w YAML-u. Żaden przypadek — to pliki, które ludzie piszą ręcznie.
• Komentarze. YAML obsługuje komentarze przez #. To ogromna zaleta dla plików konfiguracyjnych, gdzie chcesz wyjaśnić, dlaczego dane ustawienie jest takie, a nie inne. JSON w ogóle nie obsługuje komentarzy.
• Wieloliniowe stringi. YAML ma block scalars dla wieloliniowej treści, które czyta się naturalnie. JSON wymaga sekwencji ucieczki \n.
• Mniej szumu wizualnego. Nie trzeba cytować większości stringów, brak nawiasów zamykających, żadnych problemów z końcowymi przecinkami.
• Kotwice i aliasy. YAML pozwala zdefiniować wartość raz i odwoływać się do niej w innych miejscach za pomocą &anchor i *alias — przydatne w plikach konfiguracyjnych zgodnych z zasadą DRY.

Gdzie JSON wygrywa

• Rygorystyczność. JSON ma jedną poprawną reprezentację dla każdej struktury danych. YAML ma kilkanaście sposobów zapisania tego samego, co powoduje niespójności w zespołach.
• Żadnych pułapek z wcięciami. JSON używa nawiasów klamrowych i kwadratowych. YAML używa wcięć, co oznacza, że pojedyncze źle umieszczone spacja może po cichu zepsuć całą konfigurację.
• Wydajność parsowania. Parsery JSON są szybkie i proste. Parsery YAML są złożone — YAML 1.1 ma notoryjnie trudne reguły niejawnego rzutowania typów.
• Wsparcie bibliotek wszędzie. Każdy język ma sprawdzony, zero-zależnościowy parser JSON. Biblioteki YAML różnią się jakością i zgodnością ze specyfikacją.
• Narzędzia. Lintery, formattery, walidatory schematów — narzędzia JSON są dojrzalsze i szerzej dostępne.
• Payloady API. JSON to uniwersalny język web API. Wysyłanie YAML-a przez HTTP byłoby niekonwencjonalne i powodowałoby problemy.

Pułapki YAML-a, które cię dopadną

YAML ma kilka naprawdę zaskakujących zachowań, które doprowadziły do prawdziwych incydentów produkcyjnych. Większość z nich wynika z reguł niejawnych typów w YAML 1.1, które YAML 1.2 zaostrzył. Poznaj je, zanim zaczniesz polegać na YAML-u w czymś krytycznym:

# YAML 1.1 implicit type coercion — all of these become booleans:
enabled: yes   # → true
disabled: no   # → false
country: NO    # → false (!)  ← the Norway Problem

# Safe practice: quote strings that look like booleans
country: "NO"
enabled: "yes"

• Liczby ósemkowe. W YAML 1.1 010 parsuje się jako 8 (ósemkowo), nie 10. Ma znaczenie przy uprawnieniach do plików.
• Tabulatory vs spacje. YAML zabrania tabulatorów do wcięć. Jeden tab wtrącony przez edytor kodu i plik psuje się po cichu albo rzuca kryptyczny błąd.
• Niejawne wartości null. Pusta wartość w YAML-u staje się null. Łatwo to przeoczyć przy ręcznej edycji.
• Niejednoznaczność string vs liczba. port: 8080 daje ci liczbę całkowitą. version: 1.0 może dać float. Czasem chcesz stringa "1.0". Zawsze używaj cudzysłowów, gdy to ma znaczenie.

Praktyczny przewodnik decyzyjny

Sięgnij po YAML, gdy:

• Piszesz pliki konfiguracyjne, które ludzie edytują bezpośrednio: CI/CD, Kubernetes, Docker Compose, Ansible
• Plik będzie zawierał komentarze wyjaśniające ustawienia
• Wieloliniowe wartości stringów są częste
• Ekosystem, w którym pracujesz, już używa YAML-a (nie walcz z konwencją)

Sięgnij po JSON, gdy:

• Wysyłasz lub odbierasz dane przez API
• Dane są generowane i przetwarzane programistycznie (bez edycji przez człowieka)
• Potrzebujesz gwarantowanej spójności parsowania w różnych narzędziach i językach
• Pracujesz w ekosystemie standaryzującym na JSON-ie: npm (package.json), VS Code (settings.json), Angular, TypeScript

Konwersja między formatami

Musisz skonwertować konfigurację YAML na JSON dla narzędzia, które nie rozumie YAML-a? Użyj konwertera YAML na JSON. Chcesz w drugą stronę? Konwerter JSON na YAML sobie poradzi. YAML Formatter jest też przydatny, gdy wklejasz YAML, który się rozjechał. A jeśli twój YAML nie parsuje, YAML Validator wskaże ci dokładnie, gdzie jest problem.

Podsumowanie

JSON i YAML uzupełniają się, a nie konkurują. Używaj JSON-a do wymiany danych — API, programistyczne przechowywanie danych, serializacja. Używaj YAML-a do plików konfiguracyjnych, które ludzie czytają i edytują. Większość dojrzałych projektów używa obu: package.json do zależności, .github/workflows/*.yml do CI. Gdy zrozumiesz, do czego każdy format jest zoptymalizowany, wybór staje się oczywisty.