Konwerter JSON na YAML

Konwerter JSON na YAML

JSON i YAML opisują te same struktury danych, ale YAML jest bardziej czytelny dla człowieka. Konwersja przydaje się przy plikach konfiguracyjnych i manifestach.

Czym się różnią?

Przykład

{
  "app": "webp",
  "servers": ["web1", "web2"]
}

Zamienia się na:

app: webp
servers:
  - web1
  - web2

Na co uważać?

• Wartości tekstowe mogą wymagać cudzysłowów (np. „true”, „123”).
• Wcięcia w YAML muszą używać spacji, nie tabulatorów.
• Konwerter zachowuje typy: liczby, booleany i null nie są cytowane.

Jak konwerter zamienia JSON na YAML

Konwersja przebiega w dwóch etapach. Najpierw parser JSON zamienia tekst wejściowy na drzewo wartości: obiekty, tablice, łańcuchy znaków, liczby, booleany i null. Dopiero potem serializer przechodzi to drzewo od korzenia w dół i zapisuje każdy poziom jako kolejne linie YAML, a głębokość zagnieżdżenia oddaje wcięciem.

Reguła mapowania jest stała: obiekt staje się mapowaniem, czyli parą klucz: wartość w jednej linii, a tablica sekwencją, w której każdy element poprzedza myślnik i spacja. Gdy elementem tablicy jest obiekt, myślnik występuje w linii pierwszego klucza, a pozostałe klucze tego obiektu trafiają do linii poniżej, z wcięciem o jeden poziom głębszym.

Ostatni etap to decyzja o cudzysłowach. Skalar zapisujemy bez nich tylko wtedy, gdy jego treść jest jednoznaczna dla parsera YAML. Wartości wyglądające jak liczba, boolean albo null, a także te zawierające znaki specjalne, trafiają w cudzysłów, żeby nie zmieniły typu. Liczby, booleany i null pochodzące z JSON-a pozostają bez cudzysłowów, bo ich typ jest znany z drzewa.

Konwersja krok po kroku

1. Wklejasz tekst: {"app":"webp","port":8080,"debug":false,"tags":["json","yaml"],"limits":{"cpu":2,"ram":256}}. Parser sprawdza składnię i buduje drzewo wartości.
2. W obiekcie głównym jest 5 kluczy: app, port, debug, tags i limits. Tablica tags ma 2 elementy, a zagnieżdżony obiekt limits 2 klucze. Razem daje to 7 wartości skalarnych i 3 kontenery.
3. Każdy klucz obiektu głównego trafia do osobnej linii w postaci klucz: wartość, więc powstają linie app: webp, port: 8080 oraz debug: false.
4. Klucz tags zapisuje się w osobnej linii, a jego dwa elementy wchodzą poziom niżej jako pozycje sekwencji z myślnikiem, z wcięciem dwóch spacji.
5. Obiekt limits jest zagnieżdżony, więc jego klucze cpu i ram również dostają wcięcie dwóch spacji i nie są otoczone nawiasami klamrowymi.
6. Wynik ma 9 linii: app: webp, port: 8080, debug: false, tags:, dwie pozycje z myślnikiem, limits:, cpu: 2 oraz ram: 256. Wartości 8080, 2, 256 i false nie mają cudzysłowów, bo ich typ jest jednoznaczny.

Mapowanie elementów JSON na zapis YAML

Praktyczne wskazówki

• Trzymaj spacje, nie tabulatory — YAML nie dopuszcza znaku tabulacji w wcięciu. Jeśli poprawiasz wynik ręcznie, ustaw w edytorze zamianę tabulatora na spacje, inaczej plik przestanie się parsować.
• Sprawdź wartości podobne do typów — łańcuchy typu "true", "no", "123" albo "1.0" mogą zostać odczytane jako boolean lub liczba. Konwerter otacza je cudzysłowem, ale przy ręcznej edycji łatwo ten cudzysłów zgubić.
• Usuń komentarze przed wklejeniem — JSON ich nie przewiduje, więc zapisy // i /* */ wywołają błąd parsowania. Komentarze YAML z znakiem # dopisz dopiero po konwersji.
• Traktuj wynik jako punkt wyjścia — po konwersji możesz dodać kotwice, aliasy i komentarze, których JSON nie przenosi.
• Przy dużych plikach zostań lokalnie — konwersja w przeglądarce jest wygodna, ale dla bardzo dużych zbiorów szybszy i pewniejszy bywa skrypt uruchomiony na dysku.

Czego narzędzie nie uwzględnia

• Komentarze i kotwice YAML — jeśli konwertujesz w obie strony, komentarze oraz kotwice i aliasy znikną, bo JSON nie ma dla nich odpowiednika.
• Duplikaty kluczy — JSON z powtórzonym kluczem w tym samym obiekcie jest niejednoznaczny. Parsery zwykle zostawiają ostatnią wartość, a konwerter nie sygnalizuje konfliktu.
• Precyzja dużych liczb — identyfikatory i bardzo długie liczby całkowite mogą zostać wczytane jako liczby zmiennoprzecinkowe i stracić końcowe cyfry. Takie wartości bezpieczniej trzymać w JSON-ie jako łańcuchy.
• Różnice między YAML 1.1 i 1.2 — interpretacja zapisów takich jak yes, no czy on zależy od wersji i parsera docelowego. Wynik jest poprawny składniowo, ale nie w każdym narzędziu odczytany tak samo.

Najczęstsze pytania