Ik heb genoeg API's verzonden om precies te weten op welk moment een project een JSON Schema nodig heeft. 't Is nooit aan het begin. 't Is drie weken later, wanneer een tweede team je eindpunt begint te consumeren, iemand een verkeerd opgemaakte aanvraaginstantie stuurt, en een null glijdt in een veld waarvan iedereen aannam dat het altijd een string was Plotseling heb je een contract nodig - een document dat zegt, in een vorm die een machine kan afdwingen, & quot; zo ziet een geldige payload eruit." Dat document is een JSON Schema, en het schrijven van een met de hand vanaf een eindpunt dat al echte gegevens retourneert, is een van de vervelender klussen in backend-werk.
tl;dr: Plak een JSON-monster in de JSON-schemagenerator, kies Draft-07 of 2020-12, en het leidt een schema af - typen,
requiredvelden, samengevoegde array-items en tekenreeksformaten zoalsdate-timeenuuid. Het draait volledig in uw browser, dus payloads met tokens en persoonlijke gegevens verlaten nooit de pagina Behandel de uitvoer als een sterke eerste versie en scherp deze vervolgens aan met de beperkingen die alleen u kent.
Ik heb deze tool gebouwd voor Toolz.dev omdat ik steeds hetzelfde met de hand deed: een responslichaam openen, er naar loensen en de vorm ervan per clausule in een schema-clausule transcriberen Het is repetitief, en repetitieve transcriptie is waar fouten zich verbergen Deze gids legt uit wat de generator doet, waar gevolgtrekking betrouwbaar is, waar het je oordeel nodig heeft, en hoe een gegenereerd schema in een echte validatieworkflow past.
Wat is een JSON Schema, en waarom er een genereren uit data?
JSON Schema is een woordenschat voor het beschrijven van de structuur van JSON, onderhouden als een specificatie op zichzelf in plaats van als conventie Een schema is zelf een JSON-document dat het verwachte type van elk veld declareert, welke velden vereist zijn, welke vorm geneste objecten en arrays aannemen, en - met trefwoorden als pattern, enum, minimum, en format - welke waarden zijn eigenlijk toegestaan Validators in bijna elke taal lezen een schema en vertellen u of een bepaald document conform is. Het komt het dichtst in de buurt van een typesysteem dat over servicegrenzen heen reist.
De reden om een schema te genereren uit een sample, in plaats van het helemaal opnieuw te schrijven, is dat het grootste deel van een schema mechanisch is Lopen met een payload en opnemen & quot; dit is een string, dit is een geheel getal, dit object heeft deze keys" is precies het soort werk dat een machine zou moeten doen Wat is nee mechanisch is de semantische laag: dat weten status mag maar één van de vier snaren zijn, dat age kan niet negatief zijn, dat email moet overeenkomen met een echt adrespatroon Generatie verwerkt de mechanische steigers, zodat u uw aandacht kunt besteden aan de beperkingen die er toe doen U vertrekt van een document dat al overeenkomt met de werkelijkheid en voegt regels toe, in plaats van te beginnen bij een leeg bestand en te hopen dat u elk veld hebt onthouden.
Er is ook een vertrouwensdimensie Wanneer u een schema met de hand typt, codeert u wat u believe het eindpunt keert terug Overtuigingen drijven uit de werkelijkheid - een veld wordt toegevoegd, een geheel getal wordt nullabel, een eindpunt dat een enkel object retourneert, begint een array te retourneren Een schema dat is gegenereerd op basis van een feitelijk antwoord is verankerd in wat de dienst daadwerkelijk heeft verzonden op de dag dat u het vastlegde. Dat anker is veel waard als u foutopsporing doet waarom de validatie tijdens de enscenering doorgaat en mislukt in de productie.
Hoe de generator een schema afleidt
De engine parseert je JSON en loopt de waarde recursief, waarbij voor elk onderdeel van de structuur een schemaknooppunt wordt uitgezonden De regels zijn bewust conservatief, omdat een te los schema nutteloos is en een te strikt schema geldige gegevens afwijst.
Voor scalairen onderscheidt het integer ten gevolge van number teneinde 42 HALD integer, 4.2 HALD number - omdat dat onderscheid betekenisvol is voor validators en voor iedereen die het schema leest. Booleanen en null kaart naar hun eigen types Strings worden type: string, en als de formaatdetectie is ingeschakeld, controleert de engine de waarde aan de hand van een reeks bekende patronen en tagt deze: date-time, date, time, email, uri, uuid, en ipv4.
Voor objecten registreert het elke sleutel, leidt het een schema af voor elke waarde, en - als required gevolgtrekking is ingeschakeld - markeert een sleutel die nodig is wanneer deze aanwezig is in elk object op die positie Voor een enkel object betekent dat alle sleutels; het interessante geval zijn arrays.
Voor arrays van objecten doet de generator iets nuttigers dan een naïeve wandeling In plaats van voor elk element of een spreiding een apart schema uit te zenden anyOf met vrijwel identieke vormen voegt het alle objecten in de array samen tot één items schema dat een enkel element beschrijft Er is een sleutel nodig die in elk element aanwezig is; een sleutel die slechts in enkele elementen aanwezig is, blijft optioneel. Dit weerspiegelt hoe echte API-collecties zich gedragen: een gepagineerde lijst waar de meeste records een avatarUrl maar een paar niet Het samengevoegde schema legt " deze velden verschijnen altijd, deze verschijnen soms" in één leesbare definitie Dit kunt u zien in de ingebouwde sample, waar de members array heeft twee objecten - één met een active veld en één zonder - en de gegenereerde itemschemmarkeringen id en role vereist maar vertrekt active facultatief.
Voor arrays van gemengde scalairen laat de engine de elementtypen in één klappen type array - ["integer", "string", "boolean"] - in plaats van een uitgebreide unie. Wanneer object- en niet-objectvormen werkelijk in één array samenvloeien, valt het terug op anyOf, wat de juiste JSON Schema-constructie is voor " een van deze alternatieven."
Hoe de JSON Schema Generator te gebruiken
Stap 1: Plak een representatief monster
Laat een API-antwoord, een armatuur, een config-bestand of een webhook-body vallen Het allerbelangrijkste dat u kunt doen voor nauwkeurigheid is het plakken van een vertegenwoordiger voorbeeld Als u meerdere records van een echte reactie hebt, neem ze dan allemaal op in een array - de generator zal ze samenvoegen en de optionaliteit correct afleiden Een monster van één record vertelt de engine dat elk veld dat het ziet altijd aanwezig is, wat vaak verkeerd is Laad eerst het ingebouwde monster om te zien hoe geneste objecten, arrays van objecten en geformatteerde strings worden behandeld voordat u uw eigen strings plakt.
Stap 2: Kies het dialect
Kies Draft-07 voor de breedste compatibiliteit tussen validatiebibliotheken, of 2020-12 voor de huidige specificatie. De tool schrijft het juiste $schema identificatie op de root zodat uw validator de juiste regels toepast Voor de object - en arrayvormen die deze generator produceert, is de structurele uitvoer hetzelfde over beide dialecten; het zichtbare verschil is de identificatie Als u niet zeker weet welke uw tooling ondersteunt, is Draft-07 de veilige standaard - het heeft de breedste bibliotheekondersteuning van alle versies.
Stap 3: Stel uw opties in
Voeg een title als u het schema zelfdocumentatie wilt Bepaal of u wilt uitzenden required - meestal wilt u het, maar tijdens vroege verkenning geeft u misschien de voorkeur aan een losser schema Houd de opmaakdetectie ingeschakeld, tenzij u valse positieven ziet. En schakel de strikte modus in (additionalProperties: false) wanneer het schema iets bewaakt dat u volledig beheert, zoals een configuratiebestand of een verzoektekst, en u wilt dat onverwachte sleutels worden afgewezen in plaats van genegeerd.
Stap 4: Genereren, beoordelen en exporteren
Druk op Genereren en lees vervolgens de uitvoer kritisch Controleer dat required komt overeen met uw bedoeling, dat geheel getal-versus-getal kwam er goed uit, en dat alle gedetecteerde formaten correct zijn in plaats van toevallig Als het er goed uitziet, kopieer dan het schema of download het als een .json bestand klaar om in uw validator of repository te worden geplaatst.
Een uitgewerkt voorbeeld
Beschouw deze reactie vanuit een hypothetische /projects eindpunt:
{
"id": "5b2a1f6e-8c3d-4a1b-9f7e-2c1d3e4f5a6b",
"name": "Toolz",
"createdAt": "2026-01-14T09:30:00Z",
"score": 4.8,
"members": [
{ "id": 1, "role": "owner", "active": true },
{ "id": 2, "role": "editor" }
]
}
De generator produceert een schema waarbij id is een string met format: "uuid", createdAt is een string met format: "date-time", score is een number (geen geheel getal, vanwege het decimaalteken), en members is een array waarvan items schema vereist id en role maar niet active. Dat laatste detail is de uitbetaling: uit twee voorbeeldleden heeft het dat terecht afgeleid active is optioneel Die redenering met de hand doen over een grote lading is precies het soort zorgvuldig saai werk dat een generator weghaalt.
Waar gevolgtrekking eindigt en je oordeel begint
Ik wil direct zijn over de limieten, want een gegenereerd schema dat rechtstreeks aan de productie wordt overgedragen, is een vergissing. Inferentie ziet typen en structuur; het kan geen intentie zien.
Dat kan het niet weten role is een enum van owner, editor, en viewer - uit het monster weet het alleen role is een touwtje Dat kan het niet weten score varieert van 0 tot 5, dat name heeft een maximale lengte, of dat een code die er toevallig uitziet als een UUID eigenlijk een ondoorzichtige identificatie is die een gewone tekenreeks moet blijven. Het leidt af required van aanwezigheid, dus een optioneel veld dat toevallig in uw monster verschijnt, wordt gemarkeerd als vereist totdat u het corrigeert. En het werkt op basis van de gegevens die u het geeft: als uw monster nooit een null voor een nullabel veld weet het schema niet dat het veld nul kan zijn.
Het juiste mentale model is steigers De generator bouwt het frame nauwkeurig op - elk veld, zijn type, de nesting, de array vormen, de op aanwezigheid gebaseerde vereiste lijst Je voegt dan de semantische beperkingen toe: enums, patronen, numerieke grenzen, en alle formaten die de engine niet kon zien vanuit één waarde Dit is sneller en minder foutgevoelig dan vanuit niets te beginnen, omdat de vervelende structurele transcriptie al gedaan en correct is.
Draft-07 versus 2020-12: welke moet je kiezen?
| overweging | Ontwerp-07 | 2020-12 |
|---|---|---|
| Bibliotheekondersteuning | Breedste; bijna overal ondersteund | Groeien; controleer uw validator |
| positie | Wijd ingezet, stabiel | Huidige specificatie |
$schema waarde |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| Trefwoorden voor array-items | items voor schema's met één item |
items / prefixItems split voor tupels |
| Beste wanneer | Maximale compatibiliteit is belangrijk | U wilt de nieuwste spec-functies |
Voor de schema's die deze tool genereert - objecten, verplichte lijsten, arrays van een enkele itemvorm - drukken beide dialecten dezelfde structuur uit De praktische beslissing komt neer op wat uw validatiebibliotheek ondersteunt Als u het schema in een gevestigde stapel bedraadt, komt u overeen met de versie van uw validatordocumenten Als u fris begint en geen beperking heeft, blijft Draft-07 de pragmatische keuze voor zijn ongeëvenaarde ecosysteemondersteuning.
Veelvoorkomende gebruiksgevallen
Documenteren van een bestaande API. Wanneer u een eindpunt erft zonder schema, geeft het genereren van een eindpunt uit een echt antwoord u binnen enkele seconden een nauwkeurig startdocument. Vervolgens verfijnt u het tot een gepubliceerd contract. Dit past uiteraard bij het genereren van typen voor uw clientcode - hetzelfde monster kan de json naar typoscript tool zodat uw servercontract en clienttypen uit dezelfde bron van waarheid komen.
Valideren van aanvraaginstanties. Voor een verzoeklichaam dat u beheert, genereert u een schema uit een geldig voorbeeld, schakelt u de strikte modus in om onverwachte sleutels te weigeren en voegt u de opsommingen en grenzen toe die uw eindpunt afdwingt. Nu mislukken verkeerd opgemaakte verzoeken aan de rand met een duidelijke validatiefout in plaats van verwarrende fouten diep in uw handler te veroorzaken.
Config-bestand validatie. Applicaties die JSON config lezen profiteren enorm van een schema Genereer er een uit een known-good config, draai deze aan en valideer bij het opstarten, zodat een typefout in een config-toets luid uitvalt in plaats van een functie stil uit te schakelen.
Testen en armaturen. Een schema doet ook dienst als testmiddel Valideer uw armaturen ertegen in CI, zodat een armatuur die uit vorm raakt, wordt opgevangen voordat deze een misleidende groene test oplevert.
Contracttesten tussen diensten. Wanneer twee diensten een payload overeenkomen, is een gedeeld schema het contract. Door het uit een echt bericht te genereren en te verfijnen, krijgen beide teams een document waartegen ze onafhankelijk kunnen valideren.
Privacy: waarom dit in uw browser draait
API-samples zijn enkele van de meest gevoelige tekst die een ontwikkelaar verwerkt Ze bevatten routinematig toegangstokens, sessie-ID's, e-mailadressen, interne record-ID's en af en toe persoonlijke gegevens die nooit in een willekeurig webformulier mogen worden geplakt Dat is precies de reden waarom de JSON Schema Generator al zijn werkclient-kant doet De parsering, gevolgtrekking en serialisatie gebeuren in JavaScript in uw browser Niets wordt geüpload, geregistreerd of opgeslagen op een server U kunt dit verifiëren door uw netwerktab te openen terwijl u genereert, of door de verbinding met internet te verbreken - de tool werkt nog steeds Ik geef hier om omdat ik geen tool zou gebruiken die mijn payloads naar iemand anders en#39 stuurt; dezelfde server, en ik zou de hele server gebruiken om dezelfde lengte vragen. Gegevensprivacy in online tools opschrijven.
Hoe het past bij de bredere JSON-toolkit
Een schema is één artefact in een grotere JSON-workflow Voordat u een schema genereert, helpt het om schone, geldige invoer te hebben - de JSON-formatter zal een payload formatteren en valideren zodat je geen verkeerd opgemaakte tekst in de generator voert Nadat je een schema hebt, wil je vaak typen voor je applicatiecode, en dat is waar json naar typoscript komt binnen En als uw pijplijn tussen formaten beweegt, zal de json naar yaml converter verwerkt de conversie die veel config- en CI-systemen verwachten. Ik heb geschreven over hoe deze stukken met elkaar verbonden zijn in de Ultieme gids voor JSON-tools, en over het samenstellen van een bredere kit in de Webontwikkelaar Toolkit overzicht. Het punt van een verbonden toolkit is dat een enkel voorbeeld door verschillende tools kan stromen - schema, typen, formaatconversie - zonder ooit uw browser te verlaten.
FAQ
Hoe genereer ik een JSON-schema van JSON?
Plak uw JSON in de editor, kies Draft-07 of 2020-12 en druk op Genereren De tool leidt het type van elk veld af, extraheert de vereiste sleutels en voert een schema uit dat u rechtstreeks naar een validator kunt kopiëren. Er wordt niets geüpload - gevolgtrekking wordt volledig in uw browser uitgevoerd.
Wat is het verschil tussen Draft-07 en 2020-12?
Het zijn twee versies van de JSON Schema specificatie Draft-07 heeft de breedste ondersteuning over bibliotheken heen en is een veilige standaard 2020-12 is de huidige release en verandert onder andere hoe arrays en subschema's worden uitgedrukt Voor de object - en arrayvormen produceert deze tool de structuur is hetzelfde; het belangrijkste zichtbare verschil is de $schema identifier.
Hoe bepaalt de tool welke velden vereist zijn?
Een sleutel is gemarkeerd als deze in elk object verschijnt dat de generator ziet. Voor een enkel object betekent dat elke sleutel; voor een reeks objecten betekent dit dat sleutels in alle elementen aanwezig zijn. Sleutels die in slechts enkele records worden weergegeven, worden buiten de vereiste gelaten, wat een weerspiegeling is van hoe API's optionele velden weglaten. U kunt de detectie van vereiste velden volledig uitschakelen.
Wat gebeurt er met een reeks objecten?
De objecten worden samengevoegd tot één items schema dat een enkel element beschrijft, en de eigenschap wordt getypt als een array ervan Sleutels die in elk element aanwezig zijn, worden verplicht; sleutels die slechts in een deel aanwezig zijn, blijven optioneel. Hierdoor blijft het schema leesbaar in plaats van een grote te produceren anyOf van bijna identieke vormen.
Welke string-indelingen detecteert het?
Het erkent date-time, date, time, email, uri, uuid, en ipv4 tekenreeksen en voegt de matching toe format trefwoord Detectie is de beste inspanning van een enkel voorbeeld, dus bekijk de resultaten - een code die er toevallig uitziet als een UUID wordt als één getagd U kunt opmaakdetectie uitschakelen als u de voorkeur geeft aan gewone tekenreekstypen.
Kan ik een schema genereren uit een enkel monster?
Ja, maar één monster toont slechts één mogelijke vorm Een veld dat een getal in uw monster is, kan nul zijn of een tekenreeks elders, en een optioneel veld dat toevallig aanwezig is, is gemarkeerd vereist. Hoe representatiever het monster - idealiter meerdere echte records - hoe nauwkeuriger de afgeleide typen en de vereiste lijst.
Is een gegenereerd schema klaar voor productievalidatie?
Behandel het als een sterk uitgangspunt in plaats van een voltooid document Inferentie legt typen, structuur en vereiste velden nauwkeurig vast, maar semantische beperkingen - opsommingen, tekenreekspatronen, numerieke minima en maxima, formaten die het niet kan zien vanuit één waarde - moeten nog steeds met de hand worden toegevoegd Genereren verwijdert de vervelende steigers zodat u zich op die regels kunt concentreren.
Is mijn json geüpload naar een server?
Nee De hele inferentie-engine draait als JavaScript in uw browser Er wordt niets verzonden, gelogd of opgeslagen U kunt dit bevestigen door uw netwerktab te bekijken terwijl u genereert, of door de verbinding met internet te verbreken - de tool werkt nog steeds.
