YAML vs JSON: różnice, pułapki oraz .yaml vs .yml | We.Inc
YAML i JSON obok siebie: składnia, komentarze, typy, tekst wielowierszowy i pułapka yes/no. Sprawdź, jak odczytywana jest wartość bez cudzysłowów, i raz na zawsze rozstrzygnij .yaml vs .yml.
JSON to ścisły format danych dla programów: nawiasy klamrowe, kwadratowe, teksty w podwójnych cudzysłowach i brak komentarzy. YAML wyraża te same dane wcięciami, pozwala na komentarze i tekst wielowierszowy, a wersja 1.2 została zaprojektowana jako nadzbiór JSON. Wybierz JSON dla API i danych generowanych maszynowo, YAML dla plików edytowanych ręcznie.
Porównanie YAML i JSON cecha po cesze
Cecha
JSON
YAML 1.2
Struktura
Nawiasy klamrowe i kwadratowe
Wcięcia (tylko spacje) lub styl flow jak w JSON
Komentarze
Niedozwolone
Teksty
Zawsze w podwójnych cudzysłowach
Bez cudzysłowów, w pojedynczych lub podwójnych
Tekst wielowierszowy
Escapowane \n w jednym tekście
Skalary blokowe z | lub >
Ponowne użycie wartości
Nie
Kotwice (&) i aliasy (*)
Kilka dokumentów w jednym pliku
Nie
Tak, oddzielone przez ---
Typ mediów
application/json
application/yaml
Oba formaty opisują te same rzeczy: mapy, listy, teksty, liczby, wartości logiczne i null. Prawdziwe różnice dotyczą tego, kto czyta plik i jak wyrozumiały jest parser. Wypróbuj poniżej sprawdzarkę wartości, aby zobaczyć, jaki typ dostaje wartość bez cudzysłowów, a potem przeczytaj przykłady obok siebie i pułapki, na które trafiają osoby przechodzące między formatami.
Wpisz do sprawdzarki jedną wartość bez cudzysłowów, na przykład yes, 0x1F, 1e3 lub ~.
Przeczytaj, jaki typ nadaje jej parser YAML 1.2, co starszy parser YAML 1.1 może zrobić inaczej i czy JSON akceptuje ją w takiej postaci.
Porównaj ten sam rekord zapisany na oba sposoby w przykładach niżej.
Ujmij w cudzysłów każdą wartość, której typ Cię zaskoczył, i zachowaj ten nawyk w plikach konfiguracyjnych.
Robiąc wcięcia w YAML, używaj spacji. Specyfikacja zabrania znaków tabulacji we wcięciach, a większość błędów parsowania w ręcznie edytowanych plikach bierze się z zabłąkanego tabulatora.
Ujmuj w cudzysłów kody krajów, numery wersji i wszystko w rodzaju yes, no, on lub off. Niektóre parsery nadal stosują reguły YAML 1.1 i zamieniają je w wartości logiczne.
Jeśli narzędzie akceptuje oba formaty, generuj JSON z kodu, a YAML zostaw dla plików utrzymywanych przez ludzi.
Waliduj oba: przepuść JSON przez formatter, a YAML wczytaj tą samą biblioteką, której używa Twoja aplikacja, bo parsery różnią się w przypadkach brzegowych.
Najczęściej zadawane pytania
Czy każdy plik JSON jest poprawnym YAML?
YAML 1.2 napisano tak, aby był ścisłym nadzbiorem JSON, więc w praktyce dokument JSON wczytuje się w parserze YAML 1.2. Istnieją przypadki brzegowe, takie jak zduplikowane klucze, które parsery JSON często tolerują, a YAML zabrania.
Używać .yaml czy .yml?
Używaj .yaml. RFC 9512, który rejestruje typ mediów application/yaml, nazywa .yaml preferowanym rozszerzeniem i zauważa, że .yml jest nadal używane. Oba działają w narzędziach takich jak GitHub Actions, więc chodzi o spójność w obrębie jednego projektu.
Dlaczego moja wartość w YAML stała się true lub false?
YAML 1.1 traktował słowa takie jak yes, no, on, off, y i n jako wartości logiczne. Schemat core YAML 1.2 akceptuje tylko true i false w trzech wariantach wielkości liter, ale starsze parsery są nadal powszechne. Ujęcie wartości w cudzysłów usuwa wątpliwości.
Czy JSON może mieć komentarze?
Nie. RFC 8259 wymienia tokeny, które może zawierać JSON, i komentarzy wśród nich nie ma. Niektóre narzędzia akceptują luźniejszy JSON z komentarzami, ale ścisły parser odrzuci taki plik.
Który parsuje się szybciej?
Gramatyka JSON jest znacznie mniejsza, a przeglądarki mają dla niego wbudowany parser, więc zwykle jest to szybszy i bezpieczniejszy wybór dla danych przesyłanych przez sieć. Parsery YAML muszą stosować znacznie więcej reguł, od wcięć po niejawne typowanie.
Kiedy lepszy jest JSON
API, pamięć przeglądarki, logi i wszystko, co jeden program zapisuje, aby odczytał to inny program. Gramatyka jest niewielka, każdy język ma ścisły parser, a każdą wartość można zapisać tylko na jeden sposób, więc diffy pozostają przewidywalne.
JSON nie ma też niejawnego typowania. Tekst jest tekstem, bo ma cudzysłowy, co eliminuje całą klasę niespodzianek.
Kiedy lepszy jest YAML
Konfiguracja, którą ludzie czytają i edytują: workflowy CI, konfiguracje kontenerów, front matter stron i manifesty wdrożeń. Komentarze pozwalają wyjaśnić, dlaczego dane ustawienie istnieje, a skalary blokowe zachowują czytelność skryptów powłoki i długich komunikatów.
Ceną jest to, że białe znaki mają znaczenie, a typ wartości bez cudzysłowów jest zgadywany. Utrzymuj pliki krótkie, ujmuj w cudzysłów wszystko, co niejednoznaczne, i uruchamiaj linter w CI.
Jeden rekord zapisany na dwa sposoby
Te same ustawienia strony w obu formatach. YAML pomija cudzysłowy i nawiasy klamrowe oraz dodaje komentarz; JSON wypisuje każdy tekst i każdy poziom zagnieżdżenia.
Wcięcie dwiema spacjami, komentarz, lista i numer wersji w cudzysłowie, aby pozostał tekstem.
Komentarz nie jest możliwy, a każdy klucz i tekst ma podwójne cudzysłowy.
Wartości, które zmieniają typ, gdy zapomnisz o cudzysłowach
Jaki typ dostaje wartość YAML bez cudzysłowów i bezpieczna wersja
Zapisałeś
Schemat core YAML 1.2 odczytuje
Bezpieczniej
version: 2.10
float 2.1 (końcowe zero ginie)
version: "2.10"
country: NO
tekst w 1.2, wartość logiczna false w 1.1
country: "NO"
port: 0x1F90
liczba całkowita 8080
port: 8080
mode: 0o755
liczba całkowita 493
mode: "0o755"
value: ~
value: null
ratio: .inf
float nieskończoność (brak zapisu w JSON)
ratio: "inf"
Jak zostanie odczytana ta wartość bez cudzysłowów?
Wpisz wartość tak, jak wyglądałaby po dwukropku w pliku YAML, bez cudzysłowów. Sprawdzarka stosuje reguły schematu core YAML 1.2, listę wartości logicznych YAML 1.1 i gramatykę JSON.
Wartość bez cudzysłowów
Schemat core YAML 1.2
Parsery YAML 1.1
JSON, zapisany bez zmian
Ta sama wartość w JSON
wartość logiczna {v} (YAML 1.1 odczytuje to słowo jako wartość logiczną)
Brak pułapki z wartością logiczną w stylu yes/no dla tej wartości