JSON Schema-validatie: complete gids voor drafts en regels

Wat is JSON Schema?

JSON Schema is een vocabulaire voor het annoteren en valideren van JSON-documenten. Het definieert de structuur, typen en beperkingen waaraan een JSON-document moet voldoen. Beschouw het als een contract — het schema beschrijft hoe geldige gegevens eruitzien, en validators controleren of een document voldoet aan dat contract.

JSON Schema is geschreven in JSON zelf, waardoor het machineleesbaar en taalonafhankelijk is. Het wordt ondersteund door validators in elke grote programmeertaal (JavaScript/Ajv, Python/jsonschema, Java/everit, Go/gojsonschema) en wordt gebruikt voor API-validatie, configuratiebestanden en formuliergeneratie.

JSON Schema basisbeginselen

De kernsleutelwoorden definiëren de structuur van geldige JSON-documenten.

• type — specificeert het toegestane JSON-type: string, number, integer, boolean, object, array of null. De meest fundamentele beperking.
• properties en required — voor objecten definieert 'properties' het schema van elk veld en somt 'required' op welke velden aanwezig moeten zijn. Velden die niet in 'required' staan zijn standaard optioneel.
• enum en const — 'enum' beperkt een waarde tot een vaste reeks keuzes, terwijl 'const' deze beperkt tot één exacte waarde. Handig voor statusvelden, categorieën en configuratieopties.
• pattern en format — 'pattern' valideert strings tegen een reguliere expressie. 'format' biedt semantische validatie zoals 'email', 'uri', 'date-time' en 'ipv4' zonder regex.

Deze basissleutelwoorden dekken de meeste validatiebehoeften. Een eenvoudig schema kan een objecttype definiëren met verplichte 'name' (string) en optionele 'age' (integer, minimum 0) eigenschappen.

Geavanceerde schemafuncties

Voor complexe validatievereisten biedt JSON Schema compositie, referenties en voorwaardelijke logica.

• $ref-referenties — hergebruik schemadefinities door ze te verwijzen met $ref. Verwijs naar definities binnen hetzelfde document ($ref: #/$defs/Address) of externe bestanden. Elimineert duplicatie in grote schema's.
• allOf / anyOf / oneOf — compositiesleutelwoorden die meerdere schema's combineren. 'allOf' vereist dat alle deelschema's overeenkomen, 'anyOf' vereist minstens één, en 'oneOf' vereist precies één. Handig voor polymorfische typen.
• if / then / else — voorwaardelijke schema's die verschillende validatieregels toepassen op basis van gegevenswaarden. Als het land bijvoorbeeld 'US' is, moet de postcode overeenkomen met een patroon van 5 cijfers, anders is elk formaat toegestaan.
• additionalProperties — regelt of een object eigenschappen kan bevatten die niet zijn opgenomen in 'properties'. Stel in op false voor strikte validatie of op een schema om extra eigenschappen te beperken.

Schema-ontwerpversies

JSON Schema heeft zich ontwikkeld via verschillende versies, elk met nieuwe functies en verfijning van bestaand gedrag.

• Draft-04 — de eerste veel gebruikte versie. Introduceerde $ref, required als array en basisvalidatiesleutelwoorden. Nog steeds gebruikt in veel legacy-systemen en OpenAPI 3.0.
• Draft-06 — voegde het const-sleutelwoord, propertyNames, contains voor arrays en booleaanse schema's (true/false als geldige schema's) toe. Kleine maar nuttige toevoegingen.
• Draft-07 — voegde if/then/else-voorwaardelijke logica, readOnly/writeOnly-annotaties en inhoudscoderingssleutelwoorden toe. De meest populaire versie van vandaag.
• 2019-09 (Draft 2019-09) — grote herstructurering. Introduceerde $defs (ter vervanging van definitions), $anchor, unevaluatedProperties en vocabulairesysteem. Beter voor grootschalig schemaontwerp.
• 2020-12 (Draft 2020-12) — de nieuwste stabiele versie. Verfijnde dynamische referenties, prefixItems toegevoegd voor tuplevalidatie (ter vervanging van items als array) en verbeterde uitvoerformaten. Aanbevolen voor nieuwe projecten.

Veelvoorkomende gebruiksscenario's

JSON Schema wordt gebruikt overal waar JSON-gegevens gevalideerd of gedocumenteerd moeten worden.

• API-validatie — valideer verzoekbodies en queryparameters tegen schema's in Express/Fastify-middleware. OpenAPI/Swagger-specificaties bevatten JSON Schema voor API-contractdefinitie.
• Configuratievalidatie — valideer applicatieconfiguratiebestanden (JSON, YAML geconverteerd naar JSON) bij opstarten. Detecteer typefouten en ontbrekende velden voordat ze runtime-fouten veroorzaken.
• Formuliergeneratie — tools zoals react-jsonschema-form en vue-jsonschema-form genereren automatisch HTML-formulieren vanuit JSON Schema-definities, inclusief validatieregels en UI-widgets.
• Codegeneratie — genereer TypeScript-interfaces, Go-structs of Python-dataklassen vanuit JSON Schema-definities. Houdt typen gesynchroniseerd met API-contracten.

Veelvoorkomende validatiefouten

Bij het valideren van JSON tegen een schema zijn dit de meest voorkomende fouten die u tegenkomt.

• Typemismatch — het waardetype komt niet overeen met de 'type'-beperking van het schema. Veelvoorkomende voorbeelden: string waar een getal wordt verwacht, null voor een niet-nullbaar veld, of een object waar een array vereist is.
• Ontbrekende verplichte velden — het JSON-object mist een eigenschap die in de 'required'-array staat. Validators melden welk specifiek veld ontbreekt.
• Patroonmislukking — een stringwaarde komt niet overeen met de 'pattern'-regex. Dit detecteert vaak ongeldige e-mailformaten, telefoonnummers of aangepaste identifiers die het verwachte patroon niet volgen.
• $ref-resolutiefout — het schema verwijst via $ref naar een ander schema dat niet gevonden kan worden. Dit gebeurt wanneer een $defs-vermelding ontbreekt, het pad onjuist is of externe schemabestanden niet toegankelijk zijn.

Veelgestelde vragen

Welk JSON Schema-ontwerp moet ik gebruiken voor nieuwe projecten?

Gebruik Draft 2020-12 voor nieuwe projecten tenzij u beperkingen heeft. Het heeft de meeste functies (prefixItems voor tuples, unevaluatedProperties, dynamische verwijzingen) en de beste specificatiekwaliteit. Als u OpenAPI 3.0-compatibiliteit nodig heeft, gebruik dan Draft-04. Als u de breedste bibliotheekondersteuning nodig heeft, is Draft-07 de veiligste keuze — bijna elke validator ondersteunt het.

Hoe hergebruik ik schema's over meerdere bestanden?

Gebruik $ref om schema's via URI te refereren. Voor lokale definities plaatst u herbruikbare schema's onder $defs in hetzelfde bestand en verwijst u ernaar met $ref: '#/$defs/SchemaNaam'. Voor verwijzingen tussen bestanden gebruikt u relatieve URI's ($ref: './address.json') of absolute URI's. De meeste validators ondersteunen zowel lokale als externe $ref-resolutie.

Kan JSON Schema geneste objecten valideren?

Ja. Definieer geneste schema's in de 'properties' van het bovenliggende object. Elke geneste eigenschap kan zijn eigen type, verplichte velden en validatieregels hebben. Gebruik voor diep geneste structuren $ref om het schema leesbaar te houden. Er is geen limiet aan de nestdiepte — de validator valideert elk niveau recursief.