Ich habe genug APIs versendet, um den genauen Moment zu kennen, in dem ein Projekt ein JSON-Schema benötigt Es ist nie am Start Es ist drei Wochen her, wenn ein zweites Team beginnt, Ihren Endpunkt zu konsumieren, jemand eine fehlerhafte Anfragestelle sendet und eine null Gleitet in ein Feld, von dem alle annahmen, dass es immer eine Zeichenfolge war Plötzlich braucht man einen Vertrag - ein Dokument, das besagt, in einer Form, die eine Maschine erzwingen kann, & quot; so sieht eine gültige Nutzlast aus." Dieses Dokument ist ein JSON-Schema, und das manuelle Schreiben eines Dokuments von einem Endpunkt, der bereits reale Daten zurückgibt, ist einer der mühsameren Jobs in der Backend-Arbeit.
tl; dr: Fügen Sie eine JSON-Probe in die ein JSON-Schema-GeneratorWählen Sie Draft-07 oder 2020-12 und leiten Sie daraus ein Schema ab - Typen,
requiredFelder, zusammengeführte Array-Elemente und Zeichenfolgenformate wiedate-timeunduuid. Es läuft vollständig in Ihrem Browser, so dass Nutzlasten, die Token und persönliche Daten tragen, niemals die Seite verlassen Behandeln Sie die Ausgabe als einen starken ersten Entwurf, dann verschärfen Sie sie mit den Einschränkungen, die nur Sie kennen.
Ich habe dieses Tool für Toolz.dev gebaut, weil ich immer wieder dasselbe von Hand gemacht habe: einen Antwortkörper öffnen, ihn anschielen und seine Form in einen Schemasatz für Satz transkribieren. Es ist repetitiv, und bei der repetitiven Transkription verbergen sich Fehler Dieser Leitfaden erklärt, was der Generator tut, wo Inferenz zuverlässig ist, wo sie Ihr Urteilsvermögen braucht und wie ein generiertes Schema in einen echten Validierungsworkflow passt.
Was ist ein JSON-Schema und warum ein aus Daten generieren?
JSON Schema ist ein Vokabular zur Beschreibung der Struktur von JSON, das als beibehalten wird Eine eigenständige Spezifikation Statt als Konvention Ein Schema ist selbst ein JSON-Dokument, das den erwarteten Typ jedes Feldes angibt, welche Felder benötigt werden, welche Form verschachtelte Objekte und Arrays annehmen und - mit Schlüsselwörtern wie pattern, enum, minimum, und format - welche Werte sind eigentlich erlaubt Validatoren in fast jeder Sprache lesen ein Schema und sagen Ihnen, ob ein bestimmtes Dokument konform ist Es ist das, was die JSON-Welt einem Typsystem am nächsten kommt, das sich über Dienstgrenzen hinweg bewegt.
Der Grund, ein Schema aus einem Sample zu generieren, anstatt es von Grund auf neu zu schreiben, ist, dass das meiste eines Schemas mechanisch ist Gehen einer Nutzlast und Aufzeichnen von & quot; dies ist eine Zeichenfolge, dies ist eine ganze Zahl, dieses Objekt hat diese Schlüssel" ist genau die Art von Arbeit, die eine Maschine tun sollte Was ist nicht Mechanisch ist die semantische Schicht: das zu wissen status Darf nur eine von vier Saiten sein, das age Kann nicht negativ sein, das email Einem echten Adressmuster entsprechen muss Generation handhabt das mechanische Gerüst, damit ihr eure Aufmerksamkeit auf die Einschränkungen richten könnt, die wichtig sind Ihr geht von einem Dokument aus, das bereits mit der Realität übereinstimmt und fügt Regeln hinzu, anstatt von einer leeren Datei zu beginnen und zu hoffen, dass ihr euch an jedes Feld erinnert.
Es gibt auch eine Vertrauensdimension Wenn Sie ein Schema von Hand eingeben, kodieren Sie, was Sie Glauben glauben Der Endpunkt kehrt zurück Überzeugungen driften aus der Realität - ein Feld wird hinzugefügt, eine ganze Zahl wird nullbar, ein Endpunkt, der ein einzelnes Objekt zurückgegeben hat, beginnt ein Array zurückzugeben Ein Schema, das aus einer tatsächlichen Antwort generiert wird, ist auf dem verankert, was der Dienst an dem Tag, an dem Sie ihn erfasst haben, wirklich gesendet hat Dieser Anker ist viel wert, wenn Sie darüber debuggen, warum die Validierung in der Inszenierung durchläuft und in der Produktion fehlschlägt.
Wie der Generator ein Schema ableitet
Die Engine analysiert Ihren JSON und geht den Wert rekursiv, wobei für jeden Teil der Struktur ein Schema-Knoten emittiert wird, die Regeln sind bewusst konservativ, denn ein zu lockeres Schema ist nutzlos und ein zu strenges Schema lehnt gültige Daten ab.
Bei Skalaren unterscheidet es integer aus number - 42 wird integer, 4.2 wird number - weil diese Unterscheidung für Validatoren und jeden, der das Schema liest, von Bedeutung ist Boolesche und null Karte zu ihren eigenen Typen. Strings werden type: string, und wenn die Formaterkennung eingeschaltet ist, prüft die Engine den Wert mit einer Reihe bekannter Muster und markiert ihn mit: date-time, date, time, email, uri, uuid, und ipv4drohen
Für Objekte zeichnet es jeden Schlüssel auf, leitet für jeden Wert ein Schema ab und - wenn required Inferenz ist aktiviert - markiert einen Schlüssel, der benötigt wird, wenn er in jedem Objekt an dieser Position vorhanden ist Für ein einzelnes Objekt bedeutet das alle Schlüssel; der interessante Fall sind Arrays.
Bei Arrays von Objekten macht der Generator etwas Nützlicheres als einen naiven Spaziergang Anstatt für jedes Element ein eigenes Schema oder eine Zersiedelung auszusenden anyOf Es hat nahezu identische Formen und fügt alle Objekte in der Anordnung in einem zusammen items Schema, das ein einzelnes Element beschreibt Ein in jedem Element vorhandener Schlüssel ist erforderlich; ein Schlüssel, der nur in einigen Elementen vorhanden ist, bleibt optional Dies spiegelt wider, wie sich echte API-Sammlungen verhalten: eine paginierte Liste, in der die meisten Datensätze eine tragen avatarUrl Ein paar aber nicht Das zusammengeführte Schema erfasst " diese Felder erscheinen immer, diese erscheinen manchmal" in einer lesbaren Definition Das sehen Sie in der eingebauten Stichprobe, wo die members Array hat zwei Objekte - eines mit einem active Feld und eins ohne - und die generierten Item-Schema-Markierungen id und role Benötigt, sondern geht active Optional.
Bei Arrays gemischter Skalare kollabiert die Engine die Elementtypen in einer einzigen type Array - ["integer", "string", "boolean"] - statt einer ausschweifenden Vereinigung Wenn sich Objekt - und Nichtobjektformen wirklich in einem Array vermischen, fällt es zurück auf anyOf" ist das richtige JSON-Schema-Konstrukt. eine dieser Alternativen. "
So verwenden Sie den JSON Schema Generator
Schritt 1: Fügen Sie eine repräsentative Probe ein
Geben Sie eine API-Antwort, eine Vorrichtung, eine Konfigurationsdatei oder einen Webhook-Body ein. Das Wichtigste, was Sie für die Genauigkeit tun können, ist, eine einzufügen Vertreter Beispiel Wenn Sie mehrere Datensätze aus einer realen Antwort haben, fügen Sie sie alle in ein Array ein - der Generator führt sie zusammen und schließt auf Optionalität korrekt Ein Ein-Datensatz-Beispiel teilt der Engine mit, dass jedes Feld, das sie sieht, immer vorhanden ist, was oft falsch ist Laden Sie zuerst das integrierte Sample, um zu sehen, wie verschachtelte Objekte, Arrays von Objekten und formatierte Zeichenfolgen gehandhabt werden, bevor Sie Ihre eigenen einfügen.
Schritt 2: Wählen Sie den Dialekt
Wählen Sie Draft-07 für die weitestgehende Kompatibilität zwischen Validierungsbibliotheken oder 2020-12 für die aktuelle Spezifikation. Das Tool schreibt das Richtige $schema Bezeichner auf die Wurzel, damit Ihr Validator die richtigen Regeln anwendet Für die Objekt - und Arrayformen, die dieser Generator erzeugt, ist die strukturelle Ausgabe über beide Dialekte hinweg gleich; der sichtbare Unterschied ist der Bezeichner Wenn Sie sich nicht sicher sind, welches Tool Sie unterstützen, ist Draft-07 die sichere Voreinstellung - es verfügt über die breiteste Bibliotheksunterstützung aller Versionen.
Schritt 3: Legen Sie Ihre Optionen fest
Fügen Sie ein hinzu title Wenn Sie das Schema selbstdokumentieren möchten Entscheiden Sie, ob Sie emittieren required - meistens willst du es, aber während der frühen Erkundung magst du ein lockereres Schema bevorzugen Formaterkennung weiter eingeschaltet halten, es sei denn du siehst falsch positive Und den strengen Modus einschalten (additionalProperties: false) wenn das Schema etwas schützt, das Sie vollständig kontrollieren, wie eine Konfigurationsdatei oder einen Anforderungstext, und Sie möchten, dass unerwartete Schlüssel abgelehnt und nicht ignoriert werden.
Schritt 4: Generieren, überprüfen und exportieren
Drücken Sie Generieren, dann lesen Sie die Ausgabe kritischÜberprüfen Sie das required Passt zu Ihrer Absicht, dass Ganzzahl-gegen-Zahl richtig herausgekommen ist, und dass alle erkannten Formate richtig und nicht zufällig sind Wenn es richtig aussieht, kopieren Sie das Schema oder laden Sie es als .json Datei zum Ablegen in Ihren Validator oder Ihr Repository.
Ein gearbeitetes Beispiel
Betrachten Sie diese Antwort aus einer hypothetischen /projects Endpunkt:
{
"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" }
]
}
Der Generator erzeugt ein Schema, bei dem id ist eine Zeichenfolge mit format: "uuid", createdAt ist eine Zeichenfolge mit format: "date-time", score ist ein number (wegen der Dezimalzahl keine ganze Zahl) und members Array ist, dessen items Schema erfordert id und role Aber nicht active. Dieses letzte Detail ist die Auszahlung: Aus zwei Beispielmitgliedern wurde dies korrekt abgeleitet active Optional ist, dass das Denken von Hand über eine große Nutzlast hinweg genau die Art von sorgfältiger, langweiliger Arbeit ist, die ein Generator entfernt.
Wo Schlussfolgerung endet und Ihr Urteil beginnt
Ich möchte direkt über die Grenzen sprechen, denn ein generiertes Schema, das direkt in die Produktion übergeben wird, ist ein Fehler. Schlussfolgerung sieht Typen und Struktur; es kann keine Absicht erkennen.
Das kann es nicht wissen role ist eine Enum von owner, editor, und viewer - aus der Probe weiß es nur role String ist Es kann nicht wissen, dass score Spanne von 0 bis 5, das name Maximal lang ist, oder dass ein Code, der zufällig wie eine UUID aussieht, tatsächlich eine undurchsichtige Kennung ist, die eine einfache Zeichenfolge bleiben soll Es schließt required von Anwesenheit, so dass ein optionales Feld, das zufällig in Ihrer Probe erscheint, markiert wird erforderlich, bis Sie es korrigieren Und es funktioniert aus den Daten, die Sie ihm geben: wenn Ihre Probe nie ein null Für ein nullbares Feld weiß das Schema nicht, dass das Feld null sein kann.
Das richtige mentale Modell ist Gerüst Der Generator baut den Rahmen genau auf - jedes Feld, seine Art, die Verschachtelung, die Array-Formen, die Präsenz-basierte erforderliche Liste, Sie fügen dann die semantischen Einschränkungen hinzu: Enums, Muster, numerische Grenzen, und alle Formate, die die Engine nicht von einem Wert sehen konnte Das ist schneller und weniger fehleranfällig, als von nichts zu starten, denn die mühsame strukturelle Transkription ist bereits erledigt und korrekt.
Draft-07 gegen 2020-12: Welche sollten Sie auswählen?
| Rücksicht | Entwurf-07 | 2020-12 |
|---|---|---|
| Bibliothek Unterstützung | Am weitesten gefasst; fast überall unterstützt | Wachsen; Überprüfen Sie Ihren Validator |
| Status | Weit verbreitet, stabil | Aktuelle Spezifikation |
$schema schätzen |
http://json-schema.org/draft-07/schema# |
https://json-schema.org/draft/2020-12/schema |
| Stichwörter für Array-Elemente | items Für Einzelpostenschemata |
items / prefixItems Tupel aufteilen |
| Am besten wann | Maximale Kompatibilität ist wichtig | Sie möchten die neuesten Spezifikationsfunktionen |
Für die Schemata, die dieses Tool generiert - Objekte, benötigte Listen, Arrays einer einzelnen Elementform - drücken beide Dialekte dieselbe Struktur aus Die praktische Entscheidung hängt davon ab, was Ihre Validierungsbibliothek unterstützt Wenn Sie das Schema in einen etablierten Stapel verkabeln, passen Sie die Version Ihrer Validatordokumente an Wenn Sie neu anfangen und keine Einschränkung haben, bleibt Draft-07 die pragmatische Wahl für seine unübertroffene Ökosystemunterstützung.
Häufige Anwendungsfälle
Dokumentation einer bestehenden API. Wenn Sie einen Endpunkt ohne Schema erben, erhalten Sie durch die Generierung eines aus einer echten Antwort in Sekundenschnelle ein genaues Startdokument. Anschließend verfeinern Sie es in einen veröffentlichten Vertrag. Dies passt natürlich zu Generierungstypen für Ihren Client-Code - dasselbe Beispiel kann den Feed-Code verwenden json zu typeScript Tool, damit Ihr Serververtrag und Ihre Client-Typen aus derselben Wahrheitsquelle stammen.
Validierende Antragsstellen. Für einen von Ihnen gesteuerten Anforderungskörper generieren Sie ein Schema aus einem gültigen Beispiel, schalten den strengen Modus ein, um unerwartete Schlüssel abzulehnen, und fügen die Enums und Grenzen Ihrer Endpunkt-Erzwingungen hinzu. Jetzt scheitern fehlerhafte Anfragen am Rand mit einem klaren Validierungsfehler, anstatt verwirrende Fehler tief in Ihrem Handler zu verursachen.
Konfigurationsdateivalidierung. Anwendungen, die JSON config lesen, profitieren enorm von einem Schema Generieren Sie eines aus einer Config bekanntermaßen gut, ziehen Sie es fest und validieren Sie es beim Start, damit ein Tippfehler in einer Config-Taste lautstark ausfällt, anstatt eine Funktion stillschweigend zu deaktivieren.
Prüfung und Vorrichtungen. Ein Schema dient gleichzeitig als Testwert. Validieren Sie Ihre Spielpläne in CI, damit eine aus der Form geratene Spielvorrichtung gefangen wird, bevor sie einen irreführenden Grüntest erzeugt.
Vertragsprüfung zwischen Diensten. Wenn sich zwei Dienste auf eine Nutzlast einigen, ist ein gemeinsames Schema der Vertrag, das Erzeugen aus einer echten Nachricht und das Verfeinern gibt beiden Teams ein Dokument, gegen das sie unabhängig validieren können.
Privatsphäre: warum das in Ihrem Browser läuft
API-Samples gehören zu den sensibelsten Texten, die ein Entwickler verarbeitet Sie enthalten routinemäßig Zugriffstoken, Sitzungskennungen, E-Mail-Adressen, interne Datensatz-IDs, und gelegentlich persönliche Daten, die niemals in ein zufälliges Webformular eingefügt werden sollten Genau deshalb erledigt der JSON Schema Generator seine gesamte Arbeit clientseitig Das Parsen, Inferenzieren und Serialisieren geschieht in JavaScript in Ihrem Browser Nichts wird hochgeladen, protokolliert oder auf einem Server gespeichert Sie können dies überprüfen, indem Sie Ihr Netzwerk-Tab öffnen, während Sie generieren, oder indem Sie die Verbindung zum Internet trennen - das Tool funktioniert immer noch. Ich würde mich darum kümmern, weil ich nicht ein ganzes Tool verwenden würde, um jemand anderes' s Server-Prinzip, das Sie entweder zu machen, um das Sie das gleiche Server-Prinzip. Datenschutz in Online-Tools Aufschreiben.
Wie es zum breiteren JSON-Toolkit passt
Ein Schema ist ein Artefakt in einem größeren JSON-Workflow Bevor Sie ein Schema generieren, hilft es, eine saubere, gültige Eingabe zu haben - die JSON-Formater Eine Nutzlast formatieren und validieren wird, damit Sie keinen fehlerhaften Text in den Generator einspeisen Nachdem Sie ein Schema haben, möchten Sie häufig Typen für Ihren Anwendungscode, bei dem json zu typeScript Kommt rein Und wenn sich deine Pipeline zwischen Formaten bewegt, wird die json zu Yaml Konverter übernimmt die Konvertierung, die viele Config- und CI-Systeme erwarten. Ich habe darüber geschrieben, wie sich diese Teile verbinden Ultimative Anleitung zu JSON-Tools, und über die Montage eines breiteren Kits im Webentwickler-Toolkit Übersicht. Der Sinn eines verbundenen Toolkits ist, dass ein einzelnes Sample durch mehrere Tools - Schema, Typen, Formatkonvertierung - fließen kann, ohne jemals Ihren Browser zu verlassen.
FAQ
Wie generiere ich ein JSON-Schema aus JSON?
Fügen Sie Ihr JSON in den Editor ein, wählen Sie Draft-07 oder 2020-12 und drücken Sie Generate Das Tool leitet den Typ jedes Feldes ab, extrahiert die erforderlichen Schlüssel und gibt ein Schema aus, das Sie direkt in einen Validator kopieren können Es wird nichts hochgeladen - Inferenz läuft vollständig in Ihrem Browser.
Was ist der Unterschied zwischen Draft-07 und 2020-12?
Es handelt sich um zwei Versionen der JSON Schema Spezifikation Draft-07 hat die breiteste Unterstützung über Bibliotheken hinweg und ist eine sichere Voreinstellung.2020-12 ist die aktuelle Version und ändert, wie Arrays und Unterschemata ausgedrückt werden, unter anderem Für die Objekt - und Arrayformen erzeugt dieses Tool die Struktur gleich; der wichtigste sichtbare Unterschied ist der $schema Kennung.
Wie entscheidet das Tool, welche Felder benötigt werden?
Ein Schlüssel wird markiert, wenn er in jedem Objekt erscheint, das der Generator sieht. Für ein einzelnes Objekt bedeutet das jeden Schlüssel, für ein Array von Objekten bedeutet es Schlüssel in allen Elementen. Schlüssel, die nur in einigen Datensätzen angezeigt werden, werden nicht benötigt, was die Art und Weise widerspiegelt, wie APIs optionale Felder weglassen. Sie können die erforderliche Felderkennung vollständig ausschalten.
Was passiert mit einer Reihe von Objekten?
Die Objekte werden zu einem zusammengeführt items Schema, das ein einzelnes Element beschreibt, und die Eigenschaft wird als Array davon eingegeben Schlüssel, die in jedem Element vorhanden sind, werden erforderlich; Schlüssel, die nur in einigen vorhanden sind, bleiben optional. Dadurch bleibt das Schema lesbar, anstatt ein großes zu erzeugen anyOf Von nahezu identischen Formen.
Welche String-Formate erkennt es?
Es erkennt date-time, date, time, email, uri, uuid, und ipv4 Strings und fügt das Matching hinzu format Schlüsselwort. Erkennung ist der beste Aufwand aus einem einzelnen Sample, also überprüfen Sie die Ergebnisse - ein Code, der zufällig wie eine UUID aussieht, wird als eine markiert Sie können die Formaterkennung deaktivieren, wenn Sie einfache Stringtypen bevorzugen.
Kann ich ein Schema aus einer einzelnen Probe generieren?
Ja, aber ein Sample zeigt nur eine mögliche Form an Ein Feld, das eine Zahl in Ihrer Sample ist, könnte null oder eine Zeichenfolge an anderer Stelle sein, und ein optionales Feld, das zufällig vorhanden ist, wird markiert erforderlich Je repräsentativer das Sample - idealerweise mehrere reale Datensätze - desto genauer sind die abgeleiteten Typen und die erforderliche Liste.
Ist ein generiertes Schema für die Produktionsvalidierung bereit?
Behandeln Sie es als einen starken Ausgangspunkt und nicht als ein fertiges Dokument Inferenz erfasst Typen, Struktur und benötigte Felder genau, aber semantische Einschränkungen - Enums, String-Muster, numerische Minima und Maxima, Formate, die es nicht von einem Wert sehen kann - müssen noch von Hand hinzugefügt werden Durch die Generierung wird das mühsame Gerüst entfernt, sodass Sie sich auf diese Regeln konzentrieren können.
Wird mein JSON auf einen Server hochgeladen?
Nein. Die gesamte Inferenz-Engine läuft in Ihrem Browser als JavaScript. Es wird nichts übertragen, protokolliert oder gespeichert. Sie können dies bestätigen, indem Sie Ihren Netzwerk-Tab während der Generierung ansehen oder indem Sie die Verbindung zum Internet trennen - das Tool funktioniert immer noch.
