JSON (JavaScript Object Notation) ist zum De-facto-Standard für den Datenaustausch in REST-APIs und Webdiensten geworden. Durch sein einfaches textbasiertes Format ist JSON einfach zu lesen und zu analysieren und gleichzeitig leichtgewichtig und leistungsstark. Im Gegensatz zu XML wird JSON direkt auf native Datenstrukturen in modernen Programmiersprachen wie JavaScript, Python, Ruby und Java abgebildet, sodass keine benutzerdefinierten Parser erforderlich sind.

Der Aufstieg von Single-Page-Anwendungen, mobilen Apps und IoT-Geräten, die über APIs interagieren, hat die Popularität von JSON für die serialisierte Datenübertragung gefestigt. Aufgrund seiner Allgegenwart ist JSON eine natürliche Wahl, um die Kommunikation zwischen verschiedenen Systemen zu ermöglichen. Die Einfachheit, Universalität und integrierte Sprachunterstützung von JSON haben bewiesen, dass es sich um ein robustes, skalierbares Datenaustauschformat handelt.

Durch die Definition strenger JSON-Schemas können Entwickler Datenformate und Werte zur Laufzeit validieren. Dies verbessert die allgemeine API-Qualität und -Zuverlässigkeit. Gut definierte JSON-Schemas dienen als Vertrag zwischen API-Clients und -Servern und reduzieren Unklarheiten und mögliche Fehlerquellen. In diesem Artikel werden JSON-Schemadefinitionen, Validierungstools, Designtipps und mehr erläutert.

Definieren von JSON-Schemas

Das JSON-Schema definiert die Struktur und Datentypen für ein JSON-Dokument. Es wird zur Validierung verwendet, um sicherzustellen, dass die Struktur den Erwartungen entspricht.

Ein JSON-Schema ist selbst eine JSON-Datei, die die Form anderer JSON-Dokumente deklariert. Das Schema spezifiziert Anforderungen wie:

– Welche Eigenschaften ein JSON-Objekt enthalten kann

• Erforderliche vs. optionale Eigenschaften – Datentypen für Werte wie Zeichenfolgen, Zahlen, Arrays
• Längenbeschränkungen oder zulässige Wertesätze für Strings

Zu den Schlüsselkomponenten eines JSON-Schemas gehören:

• $schema – Deklariert die JSON-Schemaversion – type – Der Datentyp (Objekt, Array, String usw.)
• properties – Gibt Eigenschaften eines Objekts als Schlüssel-Wert-Paare an
• required – Listet auf, welche Objekteigenschaften obligatorisch sind – additionalProperties – Ob zusätzliche nicht spezifizierte Eigenschaften zulässig sind
• minLength / maxLength – Grenzen der Zeichenfolgenlänge
• minimum / maximum – Numerische Wertgrenzen – enum – Zulässige Wertoptionen, die ein Wert sein kann

Mithilfe von Schemata kann überprüft werden, ob ein JSON-Dokument mit der deklarierten Struktur übereinstimmt. Sie dienen als Vertrag zwischen dem API-Produzenten und dem Konsumenten. Klar definierte Schemata erleichtern die Integration und machen Schnittstellen robuster.

SchemavalidierungDie Validierung von JSON-Daten anhand eines vordefinierten Schemas ist einer der größten Vorteile der Definition von JSON-Schemas. Durch die Schemavalidierung wird sichergestellt, dass die an und von einer API gesendeten JSON-Nutzdaten dem erwarteten Datenformat entsprechen.

Wenn ein Client eine Anfrage an Ihre API stellt, kann die Anfragenutzlast anhand Ihres Anfrageschemas validiert werden, bevor sie überhaupt Ihren Anwendungscode erreicht. Dies schützt Ihre API vor fehlerhaften Daten und stellt sicher, dass die Eingaben den Erwartungen Ihrer App entsprechen.

Ebenso können die Antworten Ihrer API anhand eines Antwortschemas validiert werden. Dies stellt sicher, dass die API-Ausgaben mit dem Vertrag übereinstimmen und Clients die Antwort zuverlässig analysieren können.

Die Schemavalidierung hat mehrere Vorteile:

• Erkennt Fehler frühzeitig, indem ungültige Datenformate abgelehnt werden
• Erzwingt Disziplin bei API-Verträgen und Datenstrukturen
  – Reduziert Annahmen über Datenformen im Client- und Servercode
• Bietet klare Erwartungen für die Nutzung und Integration
• Dient als Dokumentation und Leitfaden für die Umsetzung
• Einfache Integration der Validierung in die bestehende Pipeline mit JSON-Schema-Bibliotheken
• Kann Validierungscode für mehrere Sprachen wie TypeScript generieren

Insgesamt ist die JSON-Schemavalidierung eine wesentliche Praxis für robuste und wartbare APIs. Das Definieren von Schemata ist nur die halbe Miete – die Validierung anhand dieser Schemata lässt die Schemata wirklich lebendig werden.

Validierungstools

Durch die Validierung des JSON-Schemas wird sichergestellt, dass Ihre JSON-Daten dem erwarteten Format entsprechen. Es gibt mehrere nützliche Open-Source-Bibliotheken für die Schemavalidierung:

• Ajv – Schneller JSON-Schema-Validator, geschrieben in JavaScript. Unterstützt Draft-04/06/07.

• jsonschema – Implementierung des JSON-Schemas für Python.

• JSV – Eigenständiger JSON-Schema-Validator, geschrieben in JavaScript.

• json-schema-validator – Node.js-Validator für JSON-Schema-Entwürfe 04–07.

• JaySchema – JSON-Schema-Validator für Java.

• Jsonix Schema Compiler – Erzeugt Schemavalidatoren in JavaScript.

• Go JSON Schema Validator – JSON Schema Validator geschrieben in Go.Diese Bibliotheken ermöglichen die Validierung von JSON-Daten anhand von Schemata, um Formatierungsprobleme frühzeitig zu erkennen. Sie lassen sich einfach in Build-Pipelines und Testsuiten integrieren, um die Schema-Compliance durchzusetzen. Die meisten unterstützen die neuesten JSON-Schemaentwürfe und können hinsichtlich der Validierungsstrenge konfiguriert werden.

Schema-Design-Tipps

Befolgen Sie beim Entwerfen von JSON-Schemas die folgenden Best Practices:

• Halten Sie Schemata einfach und modular. Teilen Sie Schemadefinitionen in logische Blöcke auf, die nach Bedarf kombiniert werden können. Vermeiden Sie große monolithische Schemata.

– Verwenden Sie beschreibende und konsistente Eigenschaftsnamen wie firstName anstelle von Abkürzungen.

• Geben Sie klare Beschreibungen und Titel für Ihre Schemata und Eigenschaften an.

• Machen Sie die entsprechenden Eigenschaften zu Pflicht- und optionalen Eigenschaften. Machen Sie eine Eigenschaft nur dann erforderlich, wenn die Daten erforderlich sind.

– Beschränken Sie Zeichenfolgenwerte gegebenenfalls mit minLength und maxLength.

• Verwenden Sie Aufzählungen für kleine feste Mengen vordefinierter Werte.

• Definieren Sie erwartete Datentypen und Formate für Eigenschaften. Verwenden Sie beispielsweise integer für ganze Zahlen und string mit format: date-time für Zeitstempel.

– Legen Sie relevante Mindest- und Höchstwerte für numerische Eigenschaften wie minimum: 0 oder maximum: 100 fest.

– Verwenden Sie Standardwerte für optionale Eigenschaften, wenn es sinnvoll ist.

– Erlauben Sie NULL-Werte nur bei Bedarf mit "type": ["string", "null"] und nicht nur mit "type": "string".

• Validieren Sie die Eindeutigkeit bei Bedarf mit "uniqueItems": true.

• Verwenden Sie "$ref", um Definitionen zu referenzieren und wiederzuverwenden, anstatt sie zu duplizieren.

• Schreiben Sie klare Validierungsfehlermeldungen, die Kunden verstehen können.

• Geben Sie Beispiele für gültige und ungültige Daten für jedes Schema an.

• Verwenden Sie "$comment"-Felder, um Ihre Schemata zu dokumentieren.

• Versionieren Sie Ihre Schemata, während sie sich weiterentwickeln.

Die Befolgung der Best Practices für das Schemadesign verbessert die Wartbarkeit, Testbarkeit und Benutzerfreundlichkeit von JSON-APIs.

Häufige Fallstricke

Beim Entwerfen von JSON-Schemas ist es wichtig, einige häufige Fehler zu vermeiden, die zu spröden oder schwer zu pflegenden Schemata führen können:

Zu strenge Validierung

Es ist verlockend, Schemata sehr streng zu gestalten, um alle Möglichkeiten zu berücksichtigen. Dies erschwert jedoch die Aktualisierung von Schemata und blockiert häufig gültige Daten. Beginnen Sie mit grundlegenden Validierungen und fügen Sie nur dann weitere Einschränkungen hinzu, wenn dies wirklich erforderlich ist.

Version: „2.0.0“ Überall

Vermeiden Sie am besten die Verwendung von "version": "2.0.0" in jedem Schema, es sei denn, Sie planen, es bei jeder Änderung zu erhöhen. Dies erhöht den Mehraufwand und bietet in den meisten Fällen keine sinnvolle Versionierung. Verwenden Sie stattdessen Tags oder Revisions-IDs.

Erweiterbarkeit ist nicht geplantSchemata sollten künftig neue Eigenschaften und Daten berücksichtigen. Fordern Sie nur die Eigenschaften an, die Sie heute benötigen, und lassen Sie zusätzliche Eigenschaften zu.

Datenvarianten ignorieren

Datenformate haben oft mehrere zulässige Darstellungen wie Datumsangaben oder IDs. Schemata sollten gemeinsame Varianten ermöglichen, um Validierungsfehler zu vermeiden.

Übermäßig komplexe verschachtelte Objekte

Wenn Objekte und Arrays zu tief verschachtelt sind, sind Schemata schwer zu verstehen und zu ändern. Versuchen Sie, die Schemata relativ flach zu halten. Teilen Sie wiederverwendete verschachtelte Elemente in Definitionen auf.

Entscheidungen nicht dokumentieren

Dokumentieren Sie mithilfe von Beschreibungen, warum Validierungsentscheidungen im Schema getroffen wurden. Dies hilft zukünftigen Betreuern, die Gründe und beabsichtigten Verwendungszwecke zu verstehen.

Wenn Sie von Anfang an die Best Practices für Schemata befolgen, können Sie diese häufigen Fehltritte vermeiden. Konzentrieren Sie sich bei Schemata auf Kernvalidierungen und ermöglichen Sie Flexibilität für Erweiterungen.

Schemaentwicklung

JSON-Schemas müssen sich im Laufe der Zeit weiterentwickeln, wenn sich die Anforderungen ändern. Dies beinhaltet die Durchführung von Updates, die bestehende Clients beschädigen könnten. Die Schemaentwicklung erfordert eine sorgfältige Planung und Kommunikation zwischen API-Anbietern und -Verbrauchern.

Es gibt einige Ansätze für den Umgang mit Schemaänderungen:

• Versionieren Sie Ihre Schemata und nehmen Sie inkompatible Änderungen in neuen Versionen vor. Ermöglichen Sie Clients, die von ihnen unterstützte Version anzugeben.

• Einführung neuer optionaler Eigenschaften, die bestehende Clients nicht beeinträchtigen. Machen Sie Eigenschaften später erforderlich, nachdem die Clients Zeit für die Aktualisierung haben.

– Verwenden Sie das „anyOf“-Konstrukt, um neue und alte Schemavarianten gleichzeitig zuzulassen. Stellen Sie Clients schrittweise auf das neue Schema um.

• Geben Sie bei wichtigen Änderungen eine Vorankündigung und Migrationsanweisungen an. Wenden Sie Änderungen zunächst hinter einem Funktionsschalter oder auf einem Canary-Cluster an.

– Verwenden Sie eine Schema-Registrierung, die den Schemaverlauf und die Metadaten speichert. Dies hilft dabei, Schema-Lebenszyklen zentral über alle Dienste hinweg zu verwalten.

• Bereitstellung von Tools zum Erkennen von Schemaänderungen, zum Migrieren von Daten und zum Generieren aktualisierter Clientmodelle. Automatisieren Sie den Übergang so weit wie möglich.

Bei der Entwicklung von Schemata ist eine sorgfältige Planung unerlässlich. Kommunizieren Sie Änderungen frühzeitig und klar gegenüber Verbrauchern. Unterstützen Sie Legacy-Schemata bei Übergängen. Automatisieren Sie Migrationsmechanismen nach Möglichkeit. Mit einer guten Schema-Governance können Teams Schemata im Laufe der Zeit anpassen und gleichzeitig größere Breaking Changes für Kunden vermeiden.

Code generierenEiner der Hauptvorteile der Definition von JSON-Schemas ist die Möglichkeit, automatisch Code zu generieren, damit Clients die Schemata nutzen können. Dadurch entfällt das manuelle Schreiben von Modellen und Serialisierern, was erhebliche Entwicklungszeit und -aufwand spart. Es gibt mehrere Tools, die Code aus JSON-Schemas generieren können:

• Quicktype – Ein Open-Source-Tool, das Typen und Parser für über 35 Sprachen generiert, darunter TypeScript, C#, Java, Go und Swift. Es unterstützt komplexe Schemata mit Funktionen wie Aufzählungen, nullbaren Typen, Unions und Generika.

• JSON Schema Codegen – Ein Java-Befehlszeilentool, das Java-, C#-, Go-, Typescript-, JavaScript-, Swift-, Kotlin- und Rust-Code aus JSON-Schemas generieren kann. Es verfügt über ein Plugin-Ökosystem, das eine individuelle Anpassung der Codegenerierung ermöglicht.

• JWT-Schema – Konzentriert sich auf die Generierung von Code für JWT-Tokens basierend auf JSON-Schemas. Unterstützt Java, Typescript, C#, Go, Ruby und PHP.

• GraphQL-Codegenerator – Hauptsächlich zum Generieren von GraphQL-Schema und Resolver-Code, unterstützt aber auch das Generieren von TypeScript-Typen aus JSON-Schema.

• API Script – Ein GUI-basiertes Tool für Windows und Mac, das Code für TypeScript, C#, Java, Go, Ruby und mehr generiert. Enthält einen Mocking-Server zum Testen des generierten Codes.

• JSONSchema2Pojo – Ein Maven- und Gradle-Plugin zum Generieren von Java-POJOs aus JSON-Schemas. Anpassbar über Anmerkungen und konfigurierbare Regeln.

Der automatisch generierte Code erspart viel repetitive Arbeit und erzwingt die in den Schemata definierte Struktur. Die generierten Modelle können direkt in die Codebasis der Anwendung importiert und bei Bedarf zusätzlich angepasst werden. Die allgemeine schemagesteuerte Codegenerierung rationalisiert die Entwicklung und trägt dazu bei, die Konsistenz zwischen der API-Schnittstelle und der Implementierung sicherzustellen.

Schema-Registrierung

Eine Schemaregistrierung stellt ein zentrales Repository für die Schemaspeicherung und den Schemaabruf bereit. Es ermöglicht die Schemaverwaltung im großen Maßstab in großen Organisationen mit mehreren Anwendungen und Diensten. Zu den wichtigsten Vorteilen einer Schema-Registrierung gehören:

• Zentralisierte Schemaspeicherung – Alle Schemadefinitionen werden an einem Ort gespeichert und bieten so eine einzige Informationsquelle. Dadurch werden Doppelarbeit und Inkonsistenzen vermieden.

• Schemaversionierung – Die Registrierung verwaltet Versionen jedes Schemas. Dies unterstützt die kontrollierte Entwicklung von Schemata im Laufe der Zeit. Neue Schemata beeinträchtigen bestehende Verbraucher nicht.

• Schemasuche – Dienste können Schemadefinitionen einfach nach ID oder Betreff suchen. Reduziert die Kopplung zwischen Produzenten und Verbrauchern.- Schemakompatibilitätsprüfungen – Die Registrierung kann die Kompatibilität zwischen neuen Schemaversionen und vorhandenen Versionen prüfen. Verhindert, dass Breaking Changes eingeführt werden.

• Governance der Schemaentwicklung – Registrierungsrichtlinien steuern, wie sich Schemata im Laufe der Zeit weiterentwickeln können. Zum Beispiel die Durchsetzung der Abwärtskompatibilität für bestimmte Themen.

• Leistung und Skalierbarkeit – Zentralisiertes Caching von Schemas verbessert die Leistung. Die horizontale Skalierung der Registrierung übernimmt die Last.

Eine Schema-Registrierung ist für umfangreiche Produktionsbereitstellungen ereignisgesteuerter Architekturen mit Apache Kafka unerlässlich. Zu den beliebten Open-Source-Optionen gehören Confluent Schema Registry und Apicurio Registry. Die Registrierung ist eine Schlüsselkomponente, die einen robusten und zuverlässigen Datenaustausch über Schemata und Schemavalidierung ermöglicht.

Fazit

Wie wir untersucht haben, spielen JSON-Schemas eine entscheidende Rolle bei der Definition von Erwartungen und der Validierung von Daten in modernen API-Architekturen. Durch die Erstellung präziser JSON-Schemata erstellen Entwickler einen klaren Vertrag für Anforderungs- und Antwortnutzlasten. Dies verbessert die Zuverlässigkeit, Robustheit und das Verständnis zwischen API-Clients und -Servern.

Schemavalidierungstools wie JSON Schema bieten integrierte Funktionen zur Validierung von JSON-Daten anhand von Schemas. Dies hilft, Fehler frühzeitig zu erkennen und sicherzustellen, dass die richtigen Formate verwendet werden. Die Validierung verhindert, dass fehlerhafte Daten später zu Ausfällen führen.

Beim Entwerfen von JSON-Schemas ist es wichtig, sich auf Klarheit, Flexibilität und Kompatibilität zu konzentrieren. Schemata sollten das Wesentliche des Datenformats erfassen, ohne übermäßig restriktiv zu sein. Durch die abwärtskompatible Weiterentwicklung von Schemata können APIs verbessert werden, ohne dass bestehende Clients beschädigt werden.

Insgesamt bieten JSON-Schemas und -Validierung große Vorteile für die API-Entwicklung. Die Definition strenger Verträge durch Schemata ermöglicht unabhängige und modulare Softwaresysteme. Die Validierung gibt Entwicklern die Gewissheit, dass die Daten den definierten Spezifikationen entsprechen. Robuste Schemata und Validierung sind wichtige Voraussetzungen für skalierbare und zuverlässige API-Architekturen.

Da die Nutzung von JSON- und REST-APIs weiter zunimmt, wird die Entwicklung leistungsfähiger JSON-Schemata weiterhin eine wesentliche Fähigkeit für API-Entwickler bleiben. Die Beherrschung der Best Practices für Schemadesign und Validierung ist für die Erstellung hochwertiger Web-APIs unerlässlich.Bleiben Sie auf dem Laufenden mit APIRobots für weitere Einblicke und Updates zu diesem spannenden Bereich. Verpassen Sie nicht die Chancen, die APIs für Ihr Unternehmen bieten können. Kontaktieren Sie uns noch heute unter API Robots an APIs Development Agency und lassen Sie uns gemeinsam das volle Potenzial von APIs erschließen.