JSON Scheman ymmärtäminen: Validoi datasi kuin ammattilainen

Oletko koskaan kohdannut bugia, jossa API palautti "42" (merkkijonon) eikä 42 (numeron) ja kaikki myöhempi käsittely meni rikki? Tai joku lähetti pyynnön ilman pakollista kenttää ja sovelluksesi kaatui avuliaan virheilmoituksen sijaan? JSON Schema on olemassa juuri tällaisten ongelmien estämiseksi.

Ajattele sitä JSON-datasi pohjapiirustuksena — se kuvaa, minkä muotoista datan pitäisi olla, ja nappaa kiinni kaiken, mikä ei täsmää.

Miltä JSON Schema näyttää

JSON Schema on itsessään kirjoitettu JSON:ina (aika metaa, eikö?). Tässä on yksinkertainen skeema käyttäjäobjektille:

Tämä sanoo: "Odotan objektin, jolla on pakollinen name (ei-tyhjä merkkijono) ja email (kelvollinen sähköpostimuoto), sekä valinnainen age (kokonaisluku 0–150)." Jos joku lähettää {"name": "", "email": "not-an-email"}, validaattori havaitsee molemmat ongelmat.

Skeemojen rakentaminen vaihe vaiheelta

Aloita tyypistä. Jokainen skeema alkaa "type":llä: object, array, string, number, integer, boolean tai null.

Lisää rajoituksia. Merkkijonoille: minLength, maxLength, pattern (regex). Numeroille: minimum, maximum, multipleOf. Taulukoille: minItems, maxItems, uniqueItems. Virallinen JSON Schema -opas sisältää täydellisen listan.

Merkitse pakolliset kentät. Käytä "required"-taulukkoa objektitasolla. Listaa vain kentät, joiden täytyy olla mukana — älä tee kaikkea pakolliseksi, ellet todella tarkoita sitä.

Määrittele sisäkkäiset objektit. Sijoita skeemamäärittelyt "properties":n sisään. Tässä on käyttäjä osoitteella:

Tuo pattern postinumerossa? Se varmistaa, että vain 5-numeroiset yhdysvaltalaiset postinumerot hyväksytään. Tällainen käytännön validointi estää roskadataa pääsemästä tietokantaasi.

Miksi sinun todella pitäisi käyttää tätä

API-validointi: Validoi saapuvat pyyntöjen rungot API:si reunalla. Huono data hylätään selkeillä virheilmoituksilla ennen kuin se koskee liiketoimintalogiikkaasi. Useimmat kehykset tukevat tätä — Ajv JavaScriptille on salamannopea.

Konfiguraation validointi: Validoi asetustiedostot sovelluksen käynnistyessä. Epäonnistu nopeasti selkeällä viestillä "asetuksistasi puuttuu database.host-kenttä" kryptisen null pointer -poikkeuksen sijaan 5 minuuttia myöhemmin.

Dokumentaatio: JSON Schema toimii elävänä dokumentaationa. Työkalut kuten Swagger UI generoivat API-dokumentaation suoraan skeemoista.

Koodin generointi: Generoi TypeScript-rajapintoja, Go-rakenteita tai Python-dataluokkia skeemastasi. Kirjoita kerran, käytä kaikkialla.

Testaus: Validoi API-vastaukset testisarjassasi regressioiden automaattiseksi havaitsemiseksi.

Aloita 30 sekunnissa

Nopein tapa aloittaa? Generoi skeema olemassa olevasta JSON-datasta. Liitä JSON-esimerkkivastaus JSON Schema -generaattoriimme — se analysoi datan ja tuottaa skeeman, jota voit jalostaa. Testaa se sitten JSON Schema -validaattorillamme oikeaa dataa vasten.

Voit myös validoida ohjelmallisesti. Tässä nopea Node.js-esimerkki Ajv:llä:

Pythonille tutustu jsonschema-kirjastoon. Javalle on everit-json-schema. Lähes jokaisella kielellä on vankka tuki — katso täydellinen lista toteutuksista.

Edistyneet skeemaominaisuudet, jotka sinun pitäisi tuntea

Kun perusteet ovat hallussa, JSON Schemassa on tehokkaita ominaisuuksia, jotka mahdollistavat monimutkaisen validoinnin.

oneOf, anyOf, allOf — Skeemojen yhdistäminen:

Joskus kenttä voi olla yksi useista tyypeistä. Esimerkiksi API voi hyväksyä joko merkkijono-ID:n tai numeerisen ID:n:

Tämä skeema hyväksyy sekä {"id": "PRD-1234"} että {"id": 42}, mutta hylkää {"id": -1} tai {"id": "invalid"}.

$ref — Uudelleenkäytettävät skeemamäärittelyt:

Skeemojesi kasvaessa haluat välttää samojen määrittelyjen toistamista. $ref-avainsana mahdollistaa jaettuihin määrittelyihin viittaamisen:

Nyt sekä billing_address että shipping_address käyttävät täsmälleen samoja validointisääntöjä. Muuta address-määrittely kerran, ja molemmat kentät päivittyvät. Tämä on välttämätöntä suurten skeemojen ylläpidettävyyden kannalta.

additionalProperties — Lukitse objektisi:

Oletusarvoisesti JSON Schema sallii lisäominaisuudet, joita ei ole listattu properties:ssa. Tämä ei usein ole sitä, mitä haluat — odottamattomat kentät voivat viitata asiakkaan bugiin tai versioiden epäyhteensopivuuteen. Aseta "additionalProperties": false tuntemattomien kenttien hylkäämiseksi:

Tällä skeemalla {"name": "Alice", "email": "[email protected]", "admin": true} hylättäisiin, koska admin ei ole määritelty ominaisuus.

Yleiset JSON Schema -virheet

Kokeneetkin kehittäjät tekevät näitä virheitä skeemoja kirjoittaessaan:

1. Unohtaminen, että required on objektitasolla, ei ominaisuustasolla. Tämä on väärin:

Oikea tapa on:

2. "type": "number" käyttäminen, kun tarkoitat "type": "integer". number-tyyppi hyväksyy desimaaliluvut kuten 3.14, kun taas integer hyväksyy vain kokonaisluvut. Jos kenttäsi on laskuri tai tunniste, käytä integer.

3. format:n määrittämättä jättäminen yleisille kaavoille. JSON Schemassa on sisäänrakennetut formaattivalidaattorit email, uri, date-time, ipv4, ipv6, uuid ja muille. Käytä niitä monimutkaisten regex-kaavojen kirjoittamisen sijaan.

4. Kaiken tekeminen pakolliseksi. Merkitse kentät pakollisiksi vain, jos niiden todella pitää olla mukana. Skeeman liiallinen rajoittaminen tekee API:n kehittämisestä vaikeampaa — uuden valinnaisen kentän lisääminen on yhteensopiva muutos, mutta menetät tämän joustavuuden, jos kaikki on pakollista.

Käytännön esimerkki: Verkkokaupan tuoteskeema

Katsotaan käytännöllistä skeemaa, jota voisit käyttää tuote-API:lle:

Tämä skeema varmistaa, että jokaisella tuotteella on nimi (1-200 merkkiä), positiivinen hinta ja kategoria kiinteästä listasta. Tagit ovat valinnaisia, mutta niiden on oltava uniikkeja merkkijonoja enintään 10 kappaletta. enum-avainsana on uskomattoman hyödyllinen kentille, joiden pitäisi hyväksyä vain tiettyjä arvoja.

JSON Schema -versiot: Mikä luonnos kannattaa valita

JSON Schema on käynyt läpi useita luonnoksia — kukin julkaistu IETF Internet-Draftina — ja tämä voi olla hämmentävää tulokkaalle. Tässä nopea katsaus:

Uusille projekteille käytä 2020-12 (uusin). Jos työskentelet olemassa olevan koodipohjan kanssa, tarkista mitä luonnosta validaattorisi tukee. Useimmat modernit validaattorit kuten Ajv tukevat Draft 7:ää ja uudempia.

JSON Scheman integrointi työnkulkuusi

Tässä käytännöllinen lähestymistapa JSON Schema -validoinnin lisäämiseen Express.js-API:in:

Tämä malli antaa sinulle automaattisen pyyntövalidoinnin selkeillä virheilmoituksilla. allErrors: true -vaihtoehto varmistaa, että kaikki validointivirheet raportoidaan kerralla, ei vain ensimmäinen.

Kokeile itse

Valmis lisäämään skeemavalidoinnin projektiisi? Aloita näillä työkaluilla:

• JSON Schema Generator — Liitä mitä tahansa JSON-dataa ja saat automaattisesti generoidun skeeman. Täydellinen skeemojen luomiseen API-esimerkkivastauksista.
• JSON Schema Validator — Testaa skeemasi oikeaa dataa vasten varmistaaksesi, että se havaitsee sen minkä pitää ja sallii sen minkä pitää.
• JSON Validator — Tarkista nopeasti, että JSON:si on syntaktisesti kelvollinen ennen kuin huolehdit skeemavalidoinnista.

JSON Schema saattaa tuntua ylimääräiseltä työltä aluksi, mutta se maksaa itsensä takaisin moninkertaisesti havaitsemalla bugit järjestelmäsi rajalla eikä syvällä liiketoimintalogiikassasi.