Formater JSON i walidator JSON są ze sobą powiązane, ale nie rozwiązują tego samego problemu. Formatowanie sprawia, że JSON jest łatwiejszy do odczytania. Walidacja sprawdza, czy można przeanalizować kod JSON. Zanim wkleisz fragment kodu do dokumentów, pola konfiguracyjnego, problemu lub odpowiedzi pomocy technicznej, możesz potrzebować jednego lub obu.
Konwerter JSON / YAML / TOML Converty łączy te zadania w całość: sprawdza poprawność danych wejściowych, formatuje je do przeglądu, minimalizuje je, gdy liczy się kompaktowy wynik, i konwertuje je, gdy następny system będzie oczekiwał YAML lub TOML.
Użyj formatera, jeśli kod JSON jest trudny do odczytania
Formatowanie dotyczy prezentacji. Dodaje wcięcia i podziały linii, dzięki czemu łatwiej jest sprawdzić strukturę.
Użyj formatowania, gdy:
- ładunek jest zminimalizowany do jednej linii
- zagnieżdżone obiekty są trudne do śledzenia
- przykład API musi zostać pokazany w dokumentacji
- recenzenci muszą szybko porównać pola
- odpowiedź pomocy technicznej wymaga czytelnego fragmentu
Formatowanie nie dowodzi, że przykład jest poprawny semantycznie. Po prostu sprawia, że struktura jest widoczna.
Użyj walidatora, jeśli JSON może być nieprawidłowy
Walidacja dotyczy analizowalności. Wychwytuje problemy składniowe, takie jak brakujące przecinki, niezamknięte ciągi znaków, nieprawidłowe cudzysłowy lub uszkodzone zagnieżdżanie.
Użyj sprawdzania poprawności przed wklejeniem JSON do systemu, który odrzuci nieprawidłowe dane wejściowe. Jest to również przydatne przed udostępnieniem przykładów, ponieważ nieprawidłowe fragmenty marnują czas recenzenta i sprawiają, że dokumentacja jest mniej wiarygodna.
Użyj obu, zanim udostępnisz ważne przykłady
Najbezpieczniejszym przepływem pracy jest najpierw sprawdzanie poprawności, a następnie formatowanie. Jeśli JSON nie jest analizowany, napraw to, zanim zaczniesz martwić się prezentacją. Gdy będzie ważny, sformatuj go, aby ludzie mogli go przeczytać.
Ta sekwencja jest szczególnie przydatna w przypadku przykładów API. Informacje na temat przepływu pracy związanego z udostępnianiem interfejsu API można znaleźć w artykule Jak sformatować JSON przed udostępnieniem przykładu interfejsu API.
Kiedy pojawia się konwersja
Czasami następny system potrzebuje YAML lub TOML zamiast JSON. Konwersja to trzecie zadanie, niezależne od formatowania i sprawdzania poprawności. Zmienia składnię, próbując zachować strukturę danych.
Nie każda struktura jest odwzorowywana w sposób przejrzysty na każdy format, dlatego też ważne są ostrzeżenia dotyczące zgodności. Jeśli dane wyjściowe TOML są niedostępne, przeczytaj Dlaczego dane wyjściowe TOML są niedostępne dla niektórych wejść JSON lub YAML.
Otwórz konwerter JSON / YAML / TOML, jeśli chcesz sprawdzić, sformatować, zminimalizować lub przekonwertować dane strukturalne przed wklejeniem ich do następnego przepływu pracy.
