JSON-naar-JSON-Schema-generator

Wat is JSON Schema?

JSON Schema is een woordenschat om JSON te beschrijven. Het zegt "dit object moet deze keys hebben, van deze types, met waarden die deze patronen matchen" — en validators (Ajv, jsonschema, opis/json-schema, elke OpenAPI-tool) handhaven dat contract. De huidige standaard is Draft 2020-12, wat OpenAPI 3.1 gebruikt; Draft 7 is de vorige versie en nog steeds gangbaar in oudere toolchains. Beide hebben kleine syntactische verschillen — deze generator levert beide.

Zo gebruik je het

Plak een JSON-sample. Het uitvoerpaneel produceert een corresponderend schema waarbij elke leaf getypt is als string, integer, number, boolean, null, plus object / array voor containers. Met Formaten detecteren aan krijgen strings die matchen op gangbare patronen een format-hint — email, uri, date, date-time, uuid, ipv4. Met Markeer als required aan wordt elke key in de sample aan required toegevoegd — drop een array van meerdere objecten erin voor een eerlijke required-lijst (alleen keys aanwezig in elk object overleven). Optionele Titel- en $id-velden worden bovenaan het schema gezet.

Gedetecteerde formaten

email — alles dat past bij het simpele local@host.tld-patroon.
uri — strings die starten met http:// of https://.
date — YYYY-MM-DD (RFC 3339 full-date).
date-time — YYYY-MM-DDTHH:MM:SS[.fff][Z|+HH:MM] (RFC 3339).
time — HH:MM:SS[.fff][Z|+HH:MM].
uuid — RFC 4122 v1–v5 UUID's.
ipv4 — dotted-decimal IPv4-adressen.

Andere formaten uit de spec (uri-reference, idn-email, regex, json-pointer) worden niet auto-gedetecteerd; voeg ze handmatig toe als je ze nodig hebt.

Veelgestelde vragen

Mag ik een gegenereerd schema in productie vertrouwen?

Behandel het als startpunt. De inferrer ziet alleen wat er in je sample zit — als een veld toevallig in elk voorbeeld een positief geheel getal is, maar gedocumenteerd nul of negatief toelaat, is het schema te krap. Andersom: velden die in 100% van je samples staan kunnen in werkelijkheid optioneel zijn. Review altijd tegen het gedocumenteerde contract van je API.

Hoe kiest het required-velden?

Voor één object wordt elke key als required gemarkeerd (omdat elke key aanwezig is). Voor een array van objecten worden alleen keys aanwezig in elk object als required gemarkeerd — keys die in sommige maar niet alle voorkomen worden optioneel. Dat past bij hoe validators het schema lezen: "dit veld moet altijd aanwezig zijn".

Wat is het verschil tussen Draft 2020-12 en Draft 7?

Voor 95% van schema's niets — de basiswoordenschat is identiek. Verschillen verschijnen in geavanceerde features: $dynamicRef vervangt $recursiveRef, items vervangt additionalItems voor tuple-validatie en een paar keywords zijn tussen vocabularies verhuisd. Integreer je met OpenAPI 3.1 of Ajv 8+, kies dan 2020-12; voor oudere Ajv (v6), oudere Stoplight of iets gegenereerd voor 2019 kies Draft 7.

Waarom wordt mijn datum als date-time gedetecteerd en niet als date?

De volgorde van detectie is date-time voor date, dus 2024-01-15T00:00:00Z matcht eerst op date-time. Alleen 2024-01-15 matcht date. Wil je een date-only-veld dat tijd bevat, bewerk het schema handmatig of strip de tijdcomponent uit je sample.

Behoudt het schema enum-achtige velden?

Nee — "dit moet een van [active, paused, archived] zijn" inferreren vereist meer samples dan een typische plak bevat, en false positives zijn gevaarlijk (één tenant die naar een nieuwe staat overgaat zou validatie in productie breken). Voeg enum: [...] handmatig toe nadat je je domein hebt gereviewd.

Mag ik de uitvoer met OpenAPI gebruiken?

Ja — drop de body van het schema (alles behalve $schema en $id) in een components.schemas.MyType-entry. OpenAPI 3.1 ondersteunt de volledige Draft 2020-12-woordenschat; OpenAPI 3.0 ondersteunt een subset dichtbij Draft 7 maar met enkele eigenaardigheden (geen nullable-keyword in Draft 7 — OpenAPI 3.0 voegde een eigen toe).

JSON-naar-JSON-Schema-generator