Konwerter JSON na YAML

Konwerter JSON na YAML

JSON i YAML opisują te same struktury danych, ale YAML jest bardziej czytelny dla człowieka. Wklejasz JSON, klikasz Konwertuj (albo Ctrl+Enter) i dostajesz YAML gotowy do skopiowania lub pobrania jako plik dane.yaml. Konwersja JSON na YAML przydaje się przy plikach konfiguracyjnych, manifestach Kubernetes, Docker Compose i workflow CI.

Czym się różnią?

Przykład

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

Zamienia się na (przy domyślnych ustawieniach):

---
app: webp
servers:
  - web1
  - web2

Pierwsza linia --- to znacznik początku dokumentu YAML. Jest opcjonalny i można go wyłączyć w opcjach.

Opcje konwersji

• Wcięcie: 2 albo 4 spacje na poziom zagnieżdżenia. Dwie spacje to najczęstsza konwencja w Kubernetes i GitHub Actions.
• Cudzysłowy: styl czytelny cytuje tylko te teksty, które parser mógłby źle odczytać. Styl bezpieczny bierze w cudzysłów każdy tekst i każdy klucz, a liczby, true, false i null zostawia bez nich.
• Sortowanie kluczy A–Z porządkuje klucze w każdym obiekcie, bez rozróżniania wielkości liter i z naturalną kolejnością liczb (item2 przed item10). Kolejność elementów tablic się nie zmienia.
• Znacznik --- jest domyślnie włączony. Wyłącz go, jeśli wklejasz wynik w środek istniejącego pliku.

Zmiana opcji od razu przelicza wynik. Nad wynikiem widać liczbę węzłów JSON, głębokość zagnieżdżenia, liczbę linii YAML oraz rozmiar obu wersji w bajtach. Przyciski z przykładami (podstawowy, zagnieżdżony, tablica obiektów, konfiguracja w stylu workflow CI) wczytują gotowe dane do testu.

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. Jeśli składnia jest błędna, konwerter podaje linię i kolumnę oraz opis problemu, np. zbędny przecinek przed „}”, apostrof zamiast cudzysłowu albo klucz bez cudzysłowu. Dopiero potem serializer przechodzi 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, wyrównane do pierwszego klucza.

Ostatni etap to decyzja o cudzysłowach. W stylu czytelnym tekst zostaje bez nich tylko wtedy, gdy zaczyna się od litery lub podkreślnika i zawiera wyłącznie litery (także polskie), cyfry, spacje oraz znaki _ . / -. Cudzysłów dostają teksty zaczynające się od cyfry (liczby, daty, kody pocztowe), puste, zakończone spacją, zawierające dwukropek, # lub @ oraz słowa true, false, null, yes, no, on, off, y i n. 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, więc kafelek „Węzły JSON” pokaże 10, a „Głębokość” 2.
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 (lub czterech, jeśli tak ustawisz).
5. Obiekt limits jest zagnieżdżony, więc jego klucze cpu i ram również dostają wcięcie i nie są otoczone nawiasami klamrowymi.
6. Wynik ma 9 linii danych: app: webp, port: 8080, debug: false, tags:, dwie pozycje z myślnikiem, limits:, cpu: 2 oraz ram: 256. Z włączonym znacznikiem --- licznik „Linie YAML” pokaże 10. 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 we wcięciu. Jeśli poprawiasz wynik ręcznie, ustaw w edytorze zamianę tabulatora na spacje, inaczej plik przestanie się parsować.
• Ł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 ze znakiem # dopisz dopiero po konwersji.
• Wynik traktuj jako punkt wyjścia: po konwersji możesz dodać kotwice, aliasy i komentarze, których JSON nie przenosi.
• Dane są przetwarzane na serwerze, a ich treść nie trafia do historii użycia. Mimo to nie wklejaj haseł ani kluczy API.

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. Zostaje ostatnia wartość, a konwerter nie sygnalizuje konfliktu.
• Duże liczby: liczby całkowite spoza zakresu 64 bitów (np. długie identyfikatory) konwerter zapisuje jako tekst w cudzysłowie, żeby nie zgubić cyfr. W YAML są wtedy łańcuchem, nie liczbą. Ułamki z bardzo wieloma cyframi po przecinku są ograniczone precyzją liczb zmiennoprzecinkowych.
• Limity: JSON do 1 MB, najwyżej 100 000 węzłów i 40 poziomów zagnieżdżenia. Większe pliki lepiej konwertować lokalnie skryptem.
• Różnice między YAML 1.1 i 1.2: zapisy takie jak yes, no czy on parser YAML 1.1 czyta jako wartości logiczne. Konwerter cytuje te słowa, więc w obu wersjach pozostają tekstem, ale ręcznie dopisane wartości trzeba pilnować samemu.