Teisenda JSON-i ja YAML-i vahel

Töölaud
Dokumentatsioon
API

teisendab JSON-i YAML-iks (ja vastupidi) struktuuri säilitades, konfigureeritava taandega. Praktiline konfiguratsiooni migratsiooniks .json ja .yaml failide vahel

Mille jaoks see JSON/YAML-muundur on ette nähtud?

See tööriist muudab YAML-dokumendi JSON-iks ja vastupidi, säilitades andmestruktuuri (objektid, tabelid, skalaartüübid). JSON-i YAML-iks teisendamine või YAML-i teisendamine JSON-iks on arenduses tavaline toiming: genereerime JSON-i spetsifikatsioonist OpenAPI YAML-faili, teisendame REST API-i väljundi YAML-i, et siduda see konfiguratsioonihoidlasse, tõlgime Kubernetes YAML-i manifesti JSON-i, et edastada see koodile kubectl --dry-o>. GitHubi töövoo toimingud JSON-skeemiga. Laiemas plaanis on see sild andmevahetuse (JSON) ja käsitsi redigeeritava konfiguratsiooni (YAML) maailma vahel.



    YAML vs JSON: peadevaheline võrdlus
    
    
        JSON ja YAML vastavad sarnastele vajadustele, kuid erinevatele kasutusjuhtudele. Järgmises tabelis on kokku võetud peamised tehnilised erinevused, mis on kasulikud nende kahe vahel valimiseks sõltuvalt kontekstist.
    
    
         kaudu
                
            
                
                    Kriteerium
                    JSON
                    YAML
                
            
            
                
                    Inimloetavus
                    Keskmine (sulud, jutumärgid läbivalt)
                    Tugev (taande, vähe kirjavahemärke)
                
                
                    Paljusõnalisus
                    Sõnasõnalisem
                    Kokkuvõtlikum
                
                
                    Kommentaarid
                    Ei toetata
                    Toetatud (# kommentaar)
                
                
                    Mitu dokumenti ühes failis
                    Ei
                    Jah, eraldaja ---
                
                    Ankrud ja varjunimed (taaskasutus)
                    Ei
                    Jah (&ankur ja *ankur)
                
                
                    Tübisüsteem
                    Ranged (string, arv, tõend, null, massiiv, objekt)
                    Kaudne sund (jah, ei, null, kuupäevad, tõlgendatud skalaarid)
                
                
                    Parsimise jõudlus
                    Väga kiired algparserid kõikjal
                    Aeglasem, palju laiem grammatika
                
                
                    REST API-de kasutuselevõtt
                    Tegelik standard
                    Haruldane
                
                
                    Konfigureerimise vastuvõtmine
                    Harva (v.a package.json, tsconfig.json)
                    Tegelik standard (Kubernetes, CI/CD, Ansible)
                
            
        
    


    Millal JSON-i kasutada?
    
    
        JSON-i nõutakse alati, kui programm suhtleb teise programmiga. Selle tüüpilised kasutusjuhud:
    
    
        REST ja GraphQL API-d: päringu- ja vastusekoormus.
        Andmevahetus mikroteenuste ja sõnumijärjekordade vahel.
        JavaScripti algkood: JSON.parse ja JSON.stringify ilma sõltuvusteta.
        Brauseripoolne salvestusruum: localStorage, sessionStorage, IndexedDB.
        AJAX-i ja toomise taotlused.
        Binaarsed või voopõhised variandid: BSON (MongoDB), JSON-liinid (logid, ML-andmed), MessagePack.
        JS-i/TS-tööriistade konfiguratsioon: package.json, tsconfig.json, composer.json.
    


    Millal YAMLi kasutada?
    
    
        YAML on nõutav kohe, kui inimene faili regulaarselt redigeerib. Selle tüüpilised kasutusjuhud:
    
    
        Docker Compose (docker-compose.yml) ja virna profiilid.
        Kubernetese manifestid (juurutus-, teenindus-, sisenemis-, roolidiagrammid).
        Võimalikud mänguraamatud ja varud.
        CI/CD torujuhtmed: GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines.
        OpenAPI / Swaggeri ja AsyncAPI spetsifikatsioonid.
        Annoteeritud rakenduse konfiguratsioon (Symfony, Spring Boot, Rails), kus kommentaarid on kasulikud.
        Sageli käsitsi redigeeritavad failid, kus ülevaatlikkus ja loetavus on sõelumiskiirusest ülimuslikud.
    


    YAML-i tavalised lõksud

Kriteerium	JSON	YAML
Inimloetavus	Keskmine (sulud, jutumärgid läbivalt)	Tugev (taande, vähe kirjavahemärke)
Paljusõnalisus	Sõnasõnalisem	Kokkuvõtlikum
Kommentaarid	Ei toetata	Toetatud (`# kommentaar`)
Mitu dokumenti ühes failis	Ei	Jah, eraldaja `---`
Ankrud ja varjunimed (taaskasutus)	Ei	Jah (`&ankur` ja `*ankur`)
Tübisüsteem	Ranged (string, arv, tõend, null, massiiv, objekt)	Kaudne sund (`jah`, `ei`, `null`, kuupäevad, tõlgendatud skalaarid)
Parsimise jõudlus	Väga kiired algparserid kõikjal	Aeglasem, palju laiem grammatika
REST API-de kasutuselevõtt	Tegelik standard	Haruldane
Konfigureerimise vastuvõtmine	Harva (v.a `package.json`, `tsconfig.json`)	Tegelik standard (Kubernetes, CI/CD, Ansible)


    
        YAML on lubavam kui JSON, muutes selle võimsaks, kuid reetlikuks vorminguks. Kõige tavalisemad lõksud:


        Tande: tabeldusmärgid on spetsifikatsiooniga keelatud, kehtivad ainult tühikud. Nende kahe segamine või tühikute arvu muutmine samas plokis katkestab sõelumise.

Automaatne skalaarsund: jah, ei, sees, väljas, tõene, vale, null, puudub, null, null, parsitakse kui ~. Näidislõks: jutumärgita sihtnumber 01234 muutub täisarvuks 1234 ja riigi nimi EI (Norra) muutub false. Lisage mitmetähenduslikud stringid alati jutumärkidesse.
Mitmerealised stringid: | (plokiliteraal) jätab reavahetused samaks, samas kui > (volditud) asendab reavahetused tühikutega. Märgistuslipud - ja + reguleerivad käitumist viimasel hüppel.
YAML 1.1 vs 1.2: 1.1 (ikkagi väga levinud, näiteks vaikimisi PyYAML-i kaudu) käsitleb jah/ei/sees/väljas tõeväärtustena, mille 1.2 eemaldas. Käitumine erineb ka 8. põhinumbri puhul.
Kaudsed kuupäevad: 2024-01-15 ilma jutumärkideta tõlgendatakse mõne analüüsija poolt kuupäevaobjektina, mitte stringina.

Kõrvuti näited

Sama dokument, väljendatuna JSON-is ja seejärel YAML-is. Rakenduse lihtne konfigureerimine koos selle sõltuvuste ja keskkonnaga:

JSON-versioon

kood>{
    "nimi": "cdrn-app",
    "version": "1.14.2",
    "keskkond": "tootmine",
    "sõltuvused": {
        "php": "^8.3",
        "symfony/framework-bundle": "^7.0",
        "doktriin/orm": "^3.0"
    },
    "funktsioonid": ["vahemälu", "mailer", "queue"],
    "silumine": vale
}

Samaväärne YAML-versioon

# Rakenduse konfiguratsioon
nimi: cdrn-app
versioon: 1.14.2
keskkond: tootmine
sõltuvused:
    php: '^8.3'
    symfony/framework-bundle: '^7.0'
    doktriin/orm: '^3.0'
omadused:
    - vahemälu
    - postitaja
    - saba
silumine: false

YAML-i versioon on umbes 25% lühem tähemärkide poolest, aktsepteerib juhtivat kommentaari ja loeb nagu atribuutide loend ilma süntaktilise mürata.

Kuidas konverterit kasutada

Toimingud andmete teisendamiseks:

Kleepige oma lähtedokument (JSON või YAML) sisestusväljale.
Valige soovitud konversioonisuund (JSON-st YAML-iks või YAML-ist JSON-iks).
Klõpsake teisendamisnupul: vormindatud tulemus kuvatakse väljundalal.
Kontrollige renderdust ja seejärel kasutage kopeerimisnuppu, et tulemus lõikelauale tuua.

Konverteerimine toimub lokaalselt teie brauseris või spetsiaalse serveri kaudu, olenevalt tööriistadest: tundlikke andmeid ei säilitata.

Korduma kippuvad küsimused

JSON või YAML minu konfiguratsioonifailide jaoks?

Kui ökosüsteem kehtestab vormingu (YAML-is Kubernetes, JSON-is package.json), järgige tava. Vastasel juhul eelistage YAML-i pikkade, märkustega konfiguratsioonide jaoks, mida muudate käsitsi, ja JSON-i konfiguratsioonide jaoks, mis on loodud programmi või koodiga. Kasulike kommentaaride olemasolu on sageli otsustav argument YAMLi kasuks.

Kuidas säilitada kommentaare YAMLi-JSON-YAML-i edasi-tagasi reisi ajal?

Sa ei saa. JSON ei toeta kommentaare: niipea, kui teisendate YAML-i JSON-iks, lähevad kommentaarid jäädavalt kaotsi. Kommentaaride säilitamiseks programmilise redigeerimise ajal kasutage parserit, mis säilitab vormingu, nagu ruamel.yaml Pythonis edasi-tagasi režiimis, või vältige JSON-i kasutamist üldse.

Miks mu YAML-fail parsib kohapeal õigesti, kuid ebaõnnestub tootmises?

Levinud põhjused: erinevad parseri versioonid (YAML 1.1 vs 1.2), redaktori sisestatud vahelehed, jutumärkideta väärtused, mis näevad välja nagu tõeväärtused (EI, off) või numbrid (01234), failikodeering (UTF-8 BOM halvasti käsitletud). Tsiteerige süstemaatiliselt mitmetähenduslikke stringe ja määrake oma projektis parseri versioon.

Kas JSON on YAML-i alamhulk?

Alates YAML 1.2-st praktikas jah: iga kehtiv JSON-dokument on kehtiv YAML 1.2-dokument. Vastupidine on vale: YAML-i dokumenti, mis kasutab failis kommentaare, ankruid, kaudseid kuupäevi või mitut dokumenti, ei saa otse JSON-is ilma teabe kadumiseta väljendada.

Milliseid JSON-i ja YAML-i alternatiive peaksite teadma?

TOML: populaarne konfiguratsiooni (Cargo, pyproject.toml) jaoks, hea kompromiss loetavuse ja selgesõnalise tippimise vahel. INI: väga lihtne, kuid puudub standardne pesastatud struktuur. XML: üksikasjalik, kuid siiski asjakohane SOAP-i ja mõne Java pärandkonfiguratsiooni jaoks. HCL: kasutab Terraform. JSON5 ja JSONC: JSON-laiendid, mis võimaldavad kommentaare ja komasid.

Mis on YAML-i ja JSON-i kaal?

Samaväärse struktuuri puhul on YAML baitides üldiselt 15–30% lühem tänu klahvide ja enamiku stringide ümber olevate jutumärkide puudumisele ning sulgude puudumisele. Traadil (HTTP transport) jääb minimeeritud JSON võrreldavaks, kuid YAML jääb loetavas versioonis kompaktsemaks. Parsimise poolel puhta jõudluse tagamiseks on JSON mitu korda kiirem, mis õigustab selle kasutamist suure liiklusega API-de puhul.

Päringunäide

curl -X POST https://cdrn.fr/api/v1/tools/json-yaml-converter/execute \
  -H "Content-Type: application/json" \
  -d '{"json":"...","space_tabulation":1}'

Sisendskeem

Väli	Tüüp	Kohustuslik	Vaikimisi
`json`	text	✓	–
`space_tabulation`	integer	✓	–

Lõpp-punktid

GET https://cdrn.fr/api/v1/tools - loetleb kõik saadaolevad tööriistad
GET https://cdrn.fr/api/v1/tools/json-yaml-converter - toob selle tööriista skeemi
POST https://cdrn.fr/api/v1/tools/json-yaml-converter/execute - täidab selle tööriista JSON-payloadiga