JSON Schema begrijpen: Valideer je data als een pro

Heb je ooit een bug gehad waarbij je API "42" (een string) retourneerde in plaats van 42 (een nummer) en alles downstream kapotging? Of iemand stuurde een verzoek zonder een verplicht veld en je app crashte in plaats van een nuttige foutmelding te geven? JSON Schema bestaat precies om dit soort problemen te voorkomen.

Zie het als een blauwdruk voor je JSON-data — het beschrijft welke vorm de data moet hebben en vangt alles op wat niet overeenkomt.

Hoe JSON Schema eruitziet

JSON Schema is zelf geschreven in JSON (meta, toch?). Hier is een eenvoudig schema voor een gebruikersobject:

Dit zegt: "Ik verwacht een object met een verplichte name (niet-lege string) en email (geldig e-mailformaat), plus een optionele age (geheel getal tussen 0 en 150)." Als iemand {"name": "", "email": "not-an-email"} stuurt, detecteert de validator beide problemen.

Schema's stap voor stap bouwen

Begin met het type. Elk schema begint met "type": object, array, string, number, integer, boolean of null.

Voeg beperkingen toe. Voor strings: minLength, maxLength, pattern (regex). Voor nummers: minimum, maximum, multipleOf. Voor arrays: minItems, maxItems, uniqueItems. De officiële JSON Schema-gids heeft de volledige lijst.

Markeer verplichte velden. Gebruik de "required" array op objectniveau. Vermeld alleen velden die echt aanwezig moeten zijn — maak niet alles verplicht tenzij je dat echt bedoelt.

Definieer geneste objecten. Nest gewoon schemadefinities binnen "properties". Hier is een gebruiker met een adres:

Dat pattern op de postcode? Het zorgt ervoor dat alleen 5-cijferige Amerikaanse postcodes worden geaccepteerd. Dit soort praktische validatie voorkomt dat rommeldata in je database terechtkomt.

Waarom je dit echt zou moeten gebruiken

API-validatie: Valideer inkomende request bodies aan de rand van je API. Slechte data wordt afgewezen met duidelijke foutmeldingen voordat het je bedrijfslogica raakt. De meeste frameworks ondersteunen dit — Ajv voor JavaScript is razend snel.

Configuratievalidatie: Valideer configbestanden bij het opstarten van je app. Faal snel met een duidelijk bericht zoals "je config mist het database.host veld" in plaats van een cryptische null pointer exception 5 minuten later.

Documentatie: JSON Schema dient als levende documentatie. Tools zoals Swagger UI genereren API-docs direct uit schema's.

Codegeneratie: Genereer TypeScript-interfaces, Go-structs of Python-dataclasses vanuit je schema. Schrijf het één keer, gebruik het overal.

Testen: Valideer API-responses in je testsuite om regressies automatisch te detecteren.

In 30 seconden beginnen

De snelste manier om te beginnen? Genereer een schema uit bestaande JSON-data. Plak een voorbeeld JSON-response in onze JSON Schema Generator — hij analyseert de data en produceert een schema dat je kunt verfijnen. Test het vervolgens met onze JSON Schema Validator tegen echte data.

Je kunt ook programmatisch valideren. Hier is een snel Node.js-voorbeeld met Ajv:

Voor Python, bekijk de jsonschema-bibliotheek. Voor Java is er everit-json-schema. Vrijwel elke taal heeft goede ondersteuning — bekijk de volledige lijst van implementaties.

Geavanceerde Schema-functies die je moet kennen

Als je de basis onder de knie hebt, biedt JSON Schema krachtige functies die complexe validatie mogelijk maken.

oneOf, anyOf, allOf — Schema's combineren:

Soms kan een veld een van meerdere typen zijn. Een API kan bijvoorbeeld zowel een string-ID als een numeriek ID accepteren:

Dit schema accepteert zowel {"id": "PRD-1234"} als {"id": 42} maar wijst {"id": -1} of {"id": "invalid"} af.

$ref — Herbruikbare schemadefinities:

Naarmate je schema's groeien, wil je dezelfde definities niet herhalen. Het $ref-sleutelwoord laat je verwijzen naar gedeelde definities:

Nu gebruiken zowel billing_address als shipping_address exact dezelfde validatieregels. Wijzig de address-definitie één keer, en beide velden worden bijgewerkt. Dit is essentieel om grote schema's onderhoudbaar te houden.

additionalProperties — Vergrendel je objecten:

Standaard staat JSON Schema extra eigenschappen toe die niet in properties staan vermeld. Dit is vaak NIET wat je wilt — onverwachte velden kunnen duiden op een clientbug of een versie-mismatch. Stel "additionalProperties": false in om onbekende velden af te wijzen:

Met dit schema zou {"name": "Alice", "email": "[email protected]", "admin": true} worden afgewezen omdat admin geen gedefinieerde eigenschap is.

Veelgemaakte JSON Schema-fouten

Zelfs ervaren ontwikkelaars maken deze fouten bij het schrijven van schema's:

1. Vergeten dat required op objectniveau staat, niet op eigenschapsniveau. Dit is fout:

De juiste manier is:

2. "type": "number" gebruiken terwijl je "type": "integer" bedoelt. Het type number accepteert decimalen zoals 3.14, terwijl integer alleen gehele getallen accepteert. Als je veld een teller of een ID is, gebruik dan integer.

3. Geen format opgeven voor veelvoorkomende patronen. JSON Schema heeft ingebouwde formaatvalidators voor email, uri, date-time, ipv4, ipv6, uuid en meer. Gebruik ze in plaats van complexe regex-patronen te schrijven.

4. Alles verplicht maken. Markeer velden alleen als verplicht als ze echt aanwezig moeten zijn. Je schema te veel beperken maakt API-evolutie moeilijker — een nieuw optioneel veld toevoegen is een niet-brekende wijziging, maar je verliest die flexibiliteit als alles verplicht is.

Praktijkvoorbeeld: E-Commerce productschema

Laten we een praktisch schema bekijken dat je zou kunnen gebruiken voor een product-API:

Dit schema dwingt af dat elk product een naam heeft (1-200 tekens), een positieve prijs en een categorie uit een vaste lijst. Tags zijn optioneel maar moeten unieke strings zijn met maximaal 10. Het enum-sleutelwoord is ongelooflijk handig voor velden die alleen specifieke waarden mogen accepteren.

JSON Schema-versies: Welke Draft te gebruiken

JSON Schema heeft meerdere drafts doorlopen — elk gepubliceerd als een IETF Internet-Draft — en dat kan verwarrend zijn voor nieuwkomers. Hier is een snel overzicht:

Voor nieuwe projecten, gebruik 2020-12 (de nieuwste). Als je met een bestaande codebase werkt, controleer dan welke draft je validator ondersteunt. De meeste moderne validators zoals Ajv ondersteunen Draft 7 en later.

JSON Schema integreren in je workflow

Hier is een praktische aanpak om JSON Schema-validatie toe te voegen aan een Express.js API:

Dit patroon geeft je automatische requestvalidatie met duidelijke foutmeldingen. De allErrors: true optie zorgt ervoor dat alle validatiefouten in één keer worden gerapporteerd, niet alleen de eerste.

Probeer het zelf

Klaar om schemavalidatie aan je project toe te voegen? Begin met deze tools:

• JSON Schema Generator — Plak willekeurige JSON-data en krijg automatisch een schema gegenereerd. Perfect om schema's te bootstrappen uit voorbeeld-API-responses.
• JSON Schema Validator — Test je schema tegen echte data om te controleren of het detecteert wat het moet en toelaat wat het moet.
• JSON Validator — Controleer snel of je JSON syntactisch geldig is voordat je je zorgen maakt over schemavalidatie.

JSON Schema lijkt misschien extra werk vooraf, maar het betaalt zich vele malen terug door bugs op te vangen aan de grens van je systeem in plaats van diep in je bedrijfslogica.