Wat is een JSON Schema?

Een JSON Schema beschrijft hoe een JSON-document eruit moet zien: welke eigenschappen een object heeft, welke daarvan verplicht zijn, welk type elke waarde heeft, welke bereiken en lengtes zijn toegestaan en welke patronen en indelingen gelden, zoals voor e-mailadressen of datums. API's, configuratiebestanden en formulierbouwers gebruiken schema's om gegevens te controleren voordat ze erop vertrouwen. OpenAPI beschrijft er aanvraag- en antwoordinhoud mee.

De validator gebruiken

  1. Plak of typ het JSON Schema in het eerste vak.
  2. Plak of typ de JSON-gegevens die je wilt controleren in het tweede vak.
  3. Het resultaat verschijnt terwijl je typt: de JSON is geldig, of alle fouten worden vermeld, met het pad naar de waarde die niet aan de regels voldoet, het schemazoekwoord dat wordt geschonden en een korte uitleg.
  4. Elke waarde die niet aan de regels voldoet, wordt gemarkeerd in de gegevens. Klik op een fout om naar die waarde in de gegevens te scrollen, of klik op een markering om de bijbehorende fout in de lijst te vinden.

Het veld Schema-versie toont tegen welke draft van JSON Schema de gegevens zijn gecontroleerd.

Welke drafts worden ondersteund

Het zoekwoord $schema van het schema bepaalt de draft:

  • Draft 2020-12: https://json-schema.org/draft/2020-12/schema
  • Draft 2019-09: https://json-schema.org/draft/2019-09/schema
  • Draft 7: http://json-schema.org/draft-07/schema#
  • Draft 6: http://json-schema.org/draft-06/schema#

Een schema zonder $schema wordt gecontroleerd als Draft 7. Draft 4 en oudere versies worden niet ondersteund. Eerst wordt het schema zelf gecontroleerd aan de hand van het meta-schema van de bijbehorende draft. Een typefout zoals "type": "strin" wordt dus gemeld als een ongeldig schema en niet genegeerd. Annotaties zoals title, description en examples zijn toegestaan, net als zoekwoorden die de draft niet kent, zoals je eigen x--annotaties: die worden genegeerd.

Fouten lezen

  • Paden worden geschreven als JSONPath, beginnend bij $, het volledige document: $.ingredients[1].unit is de unit van het tweede ingrediënt.
  • Een ontbrekende verplichte eigenschap wordt gemeld bij het object waarin die eigenschap hoort te staan, met de naam van de eigenschap in het bericht.
  • Als het schema een extra eigenschap niet toestaat, verwijst de fout naar de naam van die eigenschap.
  • Bij enum en const vermeldt het bericht de toegestane waarden.
  • Bij anyOf en oneOf levert elke tak die niet aan de regels voldoet eigen fouten op, gevolgd door een fout voor het zoekwoord zelf. Eén onjuiste waarde kan dus meerdere fouten opleveren.

De foutmeldingen zijn afkomstig uit de Ajv-bibliotheek en zijn in het Engels.

Indelingen

Waarden met een format worden ook gecontroleerd: email, uri, uri-reference, date, time, date-time, duration, uuid, ipv4, ipv6, hostname, regex, json-pointer en meer. Een indeling die de validator niet kent, wordt genegeerd, zoals de JSON Schema-specificatie toestaat.

Verwijzingen

$ref werkt voor definities binnen hetzelfde schema, zoals #/$defs/address of #/definitions/address. Verwijzingen naar andere bestanden of URL's worden niet opgehaald: een schema dat zo'n verwijzing nodig heeft, wordt als ongeldig gemeld, met de verwijzing die niet kon worden opgelost.

Werking

De tool voert de validatie uit met Ajv, een veelgebruikte JSON Schema-validator, en controleert indelingen met ajv-formats. Alles wordt in je browser uitgevoerd: het schema en de gegevens worden nooit geüpload.

Functies

  • JSON Schema-drafts 6, 7, 2019-09 en 2020-12, geselecteerd op basis van $schema
  • Elke fout met het bijbehorende pad, zoekwoord en bericht
  • Waarden die niet aan de regels voldoen, gemarkeerd in de gegevens; klik erop om ernaartoe te scrollen
  • Indelingscontroles voor e-mailadressen, URI's, datums, UUID's, IP-adressen en meer
  • Controle van het schema aan de hand van het meta-schema
  • Regel en kolom van JSON-syntaxisfouten
  • Werkt in je browser