JSON formatter a JSON validator spolu souvisí, ale neřeší stejný problém. Formátování dělá JSON snazší ke čtení. Validace kontroluje, jestli se JSON dá parsovat. Než snippet vložíte do dokumentace, config pole, issue nebo support odpovědi, můžete potřebovat jedno nebo oboje.
Convertyho JSON / YAML / TOML převodník drží tyto úkoly pohromadě: validovat vstup, naformátovat ho pro review, minifikovat ho, když záleží na kompaktním outputu, a převést ho, když další systém očekává YAML nebo TOML.
Použijte formatter, když je JSON těžko čitelný
Formátování je o prezentaci. Přidává odsazení a nové řádky, aby šla struktura snáz zkontrolovat.
Formátování použijte, když:
- je payload minifikovaný do jednoho řádku
- se zanořené objekty špatně sledují
- API příklad se má ukázat v dokumentaci
- revieweři potřebují rychle porovnat pole
- support odpověď potřebuje čitelný snippet
Formátování nedokazuje, že je příklad sémanticky správný. Jen zviditelňuje strukturu.
Použijte validator, když JSON může být nevalidní
Validace je o parsovatelnosti. Zachytí syntaktické problémy jako chybějící čárky, neuzavřené stringy, nevalidní uvozovky nebo rozbité zanoření.
Validaci použijte před vložením JSONu do systému, který odmítne nevalidní vstup. Je užitečná i před sdílením příkladů, protože nevalidní snippety plýtvají časem reviewerů a snižují důvěryhodnost dokumentace.
Před sdílením důležitých příkladů použijte oboje
Nejbezpečnější workflow je nejdřív validace, potom formátování. Pokud se JSON neparsuje, opravte to dřív, než budete řešit prezentaci. Jakmile je validní, naformátujte ho tak, aby ho lidé mohli číst.
Tento sled je zvlášť užitečný pro API příklady. Pro zaměřený workflow sdílení API si přečtěte Jak formátovat JSON před sdílením API příkladu.
Kdy do hry vstupuje konverze
Někdy další systém potřebuje YAML nebo TOML místo JSONu. Konverze je třetí úkol, oddělený od formátování a validace. Mění syntaxi a snaží se zachovat datovou strukturu.
Ne každá struktura se mapuje čistě do každého formátu, proto záleží na compatibility upozorněních. Pokud není dostupný TOML output, přečtěte si Proč není výstup TOML dostupný pro některé vstupy JSON nebo YAML.
Otevřete JSON / YAML / TOML převodník, když potřebujete validovat, formátovat, minifikovat nebo převést strukturovaná data před vložením do dalšího workflowu.
