Forstå JSON Schema: Valider dataene dine som en proff

Har du noen gang hatt en bug der API-et ditt returnerte "42" (en streng) i stedet for 42 (et tall) og alt nedstrøms gikk i stykker? Eller noen sendte en forespørsel uten et påkrevd felt og appen din krasjet i stedet for å returnere en nyttig feilmelding? JSON Schema eksisterer nettopp for å forhindre slike problemer.

Tenk på det som en plantegning for JSON-dataene dine — det beskriver hvilken form dataene skal ha, og fanger opp alt som ikke stemmer.

Hvordan JSON Schema ser ut

JSON Schema er selv skrevet i JSON (meta, ikke sant?). Her er et enkelt skjema for et brukerobjekt:

Dette sier: "Jeg forventer et objekt med et påkrevd name (ikke-tom streng) og email (gyldig e-postformat), pluss en valgfri age (heltall mellom 0 og 150)." Hvis noen sender {"name": "", "email": "not-an-email"}, vil validatoren fange begge problemene.

Bygge skjemaer steg for steg

Start med typen. Hvert skjema begynner med "type": object, array, string, number, integer, boolean eller null.

Legg til begrensninger. For strenger: minLength, maxLength, pattern (regex). For tall: minimum, maximum, multipleOf. For arrays: minItems, maxItems, uniqueItems. Den offisielle JSON Schema-guiden har den komplette listen.

Merk påkrevde felt. Bruk "required"-arrayen på objektnivå. List bare opp felt som virkelig må være til stede — ikke gjør alt påkrevd med mindre du mener det.

Definer nestede objekter. Bare plasser skjemadefinisjoner inne i "properties". Her er en bruker med en adresse:

Det pattern på postnummeret? Det sikrer at bare 5-sifrede amerikanske postnumre aksepteres. Slik virkelighetsnær validering forhindrer søppeldata fra å snike seg inn i databasen din.

Hvorfor du virkelig bør bruke dette

API-validering: Valider innkommende forespørselskropper i kanten av API-et ditt. Dårlige data avvises med klare feilmeldinger før de berører forretningslogikken din. De fleste rammeverk støtter dette — Ajv for JavaScript er lynrask.

Konfigurasjonsvalidering: Valider konfigurasjonsfiler når appen starter. Feil raskt med en klar melding "konfigurasjonen din mangler database.host-feltet" i stedet for et kryptisk null pointer-unntak 5 minutter senere.

Dokumentasjon: JSON Schema fungerer som levende dokumentasjon. Verktøy som Swagger UI genererer API-dokumentasjon direkte fra skjemaer.

Kodegenerering: Generer TypeScript-grensesnitt, Go-strukturer eller Python-dataklasser fra skjemaet ditt. Skriv det en gang, bruk det overalt.

Testing: Valider API-svar i testsuiten din for å fange regresjoner automatisk.

Kom i gang på 30 sekunder

Den raskeste måten å starte? Generer et skjema fra eksisterende JSON-data. Lim inn et eksempel JSON-svar i vår JSON Schema Generator — den analyserer dataene og produserer et skjema du kan forfine. Test det deretter med vår JSON Schema Validator mot ekte data.

Du kan også validere programmatisk. Her er et raskt Node.js-eksempel med Ajv:

For Python, sjekk ut jsonschema-biblioteket. For Java finnes everit-json-schema. Praktisk talt alle språk har solid støtte — sjekk den fullstendige listen over implementasjoner.

Avanserte skjemafunksjoner du bør kjenne til

Når du har grunnleggende ting på plass, har JSON Schema noen kraftige funksjoner som gjør kompleks validering mulig.

oneOf, anyOf, allOf — Kombinere skjemaer:

Noen ganger kan et felt være en av flere typer. For eksempel kan et API akseptere enten en streng-ID eller en numerisk ID:

Dette skjemaet aksepterer både {"id": "PRD-1234"} og {"id": 42}, men avviser {"id": -1} eller {"id": "invalid"}.

$ref — Gjenbrukbare skjemadefinisjoner:

Etter hvert som skjemaene dine vokser, vil du unngå å gjenta de samme definisjonene. Nøkkelordet $ref lar deg referere til delte definisjoner:

Nå bruker både billing_address og shipping_address nøyaktig de samme valideringsreglene. Endre address-definisjonen en gang, og begge feltene oppdateres. Dette er essensielt for å holde store skjemaer vedlikeholdbare.

additionalProperties — Lås ned objektene dine:

Som standard tillater JSON Schema ekstra egenskaper som ikke er listet i properties. Dette er ofte IKKE det du vil — uventede felt kan indikere en klientfeil eller versjonsavvik. Sett "additionalProperties": false for å avvise ukjente felt:

Med dette skjemaet ville {"name": "Alice", "email": "[email protected]", "admin": true} bli avvist fordi admin ikke er en definert egenskap.

Vanlige JSON Schema-feil

Selv erfarne utviklere gjør disse feilene når de skriver skjemaer:

1. Glemme at required er på objektnivå, ikke egenskapsnivå. Dette er feil:

Den riktige måten er:

2. Bruke "type": "number" når du mener "type": "integer". Typen number aksepterer desimaltall som 3.14, mens integer bare aksepterer hele tall. Hvis feltet ditt er en teller eller en ID, bruk integer.

3. Ikke spesifisere format for vanlige mønstre. JSON Schema har innebygde formatvalidatorer for email, uri, date-time, ipv4, ipv6, uuid og mer. Bruk dem i stedet for å skrive komplekse regex-mønstre.

4. Gjøre alt påkrevd. Merk bare felt som påkrevd hvis de virkelig må være til stede. Å overbegrense skjemaet ditt gjør API-evolusjon vanskeligere — å legge til et nytt valgfritt felt er en ikke-ødeleggende endring, men du mister den fleksibiliteten hvis alt er påkrevd.

Eksempel fra virkeligheten: E-handelsproduktskjema

La oss se på et praktisk skjema du kanskje bruker for et produkt-API:

Dette skjemaet håndhever at hvert produkt har et navn (1-200 tegn), en positiv pris og en kategori fra en fast liste. Tagger er valgfrie, men må være unike strenger med maks 10. Nøkkelordet enum er utrolig nyttig for felt som bare skal akseptere bestemte verdier.

JSON Schema-versjoner: Hvilket utkast bør du bruke

JSON Schema har gått gjennom flere utkast — hvert publisert som et IETF Internet-Draft — og dette kan være forvirrende for nybegynnere. Her er en rask oversikt:

For nye prosjekter, bruk 2020-12 (den nyeste). Hvis du jobber med en eksisterende kodebase, sjekk hvilket utkast validatoren din støtter. De fleste moderne validatorer som Ajv støtter Draft 7 og nyere.

Integrere JSON Schema i arbeidsflyten din

Her er en praktisk tilnærming for å legge til JSON Schema-validering i et Express.js-API:

Dette mønsteret gir deg automatisk forespørselsvalidering med klare feilmeldinger. Alternativet allErrors: true sikrer at alle valideringsfeil rapporteres på en gang, ikke bare den første.

Prøv det selv

Klar til å legge til skjemavalidering i prosjektet ditt? Start med disse verktøyene:

• JSON Schema Generator — Lim inn hvilke som helst JSON-data og få et automatisk generert skjema. Perfekt for å bootstrappe skjemaer fra eksempel-API-svar.
• JSON Schema Validator — Test skjemaet ditt mot ekte data for å sikre at det fanger det det skal og tillater det det skal.
• JSON Validator — Verifiser raskt at JSON-en din er syntaktisk gyldig før du bekymrer deg om skjemavalidering.

JSON Schema kan virke som ekstra arbeid i starten, men det betaler seg mange ganger over ved å fange feil ved grensen av systemet ditt i stedet for dypt inne i forretningslogikken.