GraphQL SDL: Schema online validieren und formatieren

Warum GraphQL-SDL vor dem Merge validieren?

Ein Schema, das nicht parst, blockiert Codegenerierung, lässt den GraphQL-Server nicht starten und macht Reviews zum Rätselraten. Typische Ursachen — fehlende Klammer, unbekannter Typ, vergessener Query-Root — verstecken sich in einem 400-Zeilen-SDL-Diff. Der GraphQL-SDL-Validator von FastMinify führt GraphQL.js buildSchema im Browser aus: Schema-Dokument einfügen, Valid/Invalid-Verdict mit Zeile und Spalte, wenn GraphQL.js sie liefert. Das Formatieren bleibt bei Beautify GraphQL (Prettier). Es gibt keinen eigenen Slug format-graphql. Der Rest des Clusters liegt im API-Tools-Hub. Wer auch REST-Verträge pflegt, kombiniert das mit dem OpenAPI-Validierungsleitfaden.

SDL-Syntaxfehler und unbekannte Typen vor CI oder Serverstart finden

Zeile und Spalte, wenn GraphQL.js Locations liefert

Schema-Statistiken: Typanzahl, Query-/Mutation-/Subscription-Felder

100 % im Browser — das Schema wird nie hochgeladen

Queries und SDL getrennt formatieren mit Beautify GraphQL (Prettier)

Ehrliche Grenzen und Review-feste Gewohnheiten

Was validate-graphql nicht tut

Valid bedeutet: GraphQL.js buildSchema hat das eingefügte SDL akzeptiert. Das ist kein Beweis, dass Ihre API in Produktion korrekt antwortet.

Keine Query- oder Mutation-Ausführung — keine Resolver-Aufrufe, keine Variablen-Coercion gegen Livedaten

Keine Introspection eines laufenden Servers — fügen Sie das Schema-Dokument ein, das Sie besitzen

Kein Fetch entfernter .graphql-Dateien, Includes oder Git-URLs

Kein GraphQL-Federation-/Supergraph-Compose — ein SDL-Dokument pro Paste

Maximal 512 KiB UTF-8 am Validator — riesige Monolithe brauchen lokale Tools

Eine Datei, lokaler Check, dann CI

Das Browser-Tool ist die schnelle Schleife vor git push. Teams behalten GraphQL.js, graphql-eslint oder rover in der CI als Merge-Gate.

Eine Schema-Datei (oder gebündeltes SDL) halten, damit das Paste zu dem passt, was CI sieht

FastMinify nicht als Billing- oder Uptime-Monitor für Ihren GraphQL-Endpoint behandeln

Dokumentieren, ob das Repo den Default-Query-Typ oder ein eigenes schema { query: … } nutzt

Wenn Sie auch OpenAPI ausliefern, diesen Vertrag separat validieren — siehe den OpenAPI-Leitfaden

Für JSON-Schema-Instanzen json-schema-validator — anderes Metamodell

Review-Gewohnheiten, die echten Bruch finden

Die meisten SDL-Vorfälle sind Rename-Reste und fehlende Roots, keine exotischen GraphQL-Features.

Nach jedem Typ-Rename das volle Schema einfügen — nicht nur den Hunk

Einen Query-Root (oder eine explizite Schema-Definition) in derselben PR wie neue Typen verlangen

Vor dem Review beautifyen, damit Feldlisten im GitHub-Diff sichtbar sind

Validator-Fehler in die PR-Beschreibung kopieren, wenn CI-Logs laut sind

Formatoptionen (2 vs. 4 Leerzeichen) an die Prettier-Config des Repos angleichen

Schema-SDL vs. Queries: zwei Dokumente, zwei Tools

Was GraphQL-SDL tatsächlich ist

Die Schema Definition Language (SDL) beschreibt Typen, Felder und Roots. Sie ist der Vertrag, den Resolver einhalten müssen — keine ausführbare Query. FastMinify prüft diesen Vertrag mit GraphQL.js buildSchema, nicht über einen Live-Server.

Objekttypen, Interfaces, Enums, Unions, Scalars und Input-Objekte

Root-Felder auf Query, Mutation und Subscription, wenn diese Typen existieren

Das Ergebnispanel zählt diese Typen und Root-Felder nach erfolgreichem Parse

SDL ist ein eingefügtes Dokument — FastMinify holt keine .graphql-Dateien per URL

Valid bedeutet: GraphQL.js hat das Schema-Dokument akzeptiert, nicht dass Produktions-Resolver dazu passen

Queries, Mutations und Fragments gehören nicht hierher

Ein Operationsdokument (query, mutation, subscription, fragment) ist kein Schema-SDL. Einfügen in den Validator lässt buildSchema scheitern. Formatieren Sie diese Dokumente mit Beautify GraphQL.

Validate GraphQL akzeptiert nur Schema-SDL — buildSchema, keine Query-Ausführung

Beautify GraphQL formatiert Schema-SDL und Operationsdokumente mit Prettiers GraphQL-Parser

Codegen und Apollo/Yoga brauchen ein gültiges Schema; eine Query einzurücken behebt keinen unbekannten Typ

Kein Query-Runner und keine Live-Introspection auf FastMinify

Für JSON-REST-Prüfungen den JSON-Validator nutzen — er versteht kein SDL

Der Query-Root ist meist Pflicht

GraphQL.js verlangt typischerweise einen Query-Root-Typ, sofern Ihre Schema-Definition keinen anderen Query-Typ nennt. Ein Dokument nur mit type User { … } ohne Query-Root scheitert meist — das ist erwartet, kein FastMinify-Bug.

Minimales gültiges Paste: type Query { hello: String }

Eigener Root: schema { query: RootQuery } plus type RootQuery { … }

Fehlendes Query ist eine häufige Überraschung nach „in meinem Editor geht es“

Undefinierte Typen scheitern mit einer Meldung wie Unknown type "Foo" — oft mit Zeilennummer

Einige semantische Fehler lassen Locations weg; das Verdict bleibt invalid

Validieren vs. Beautify: nicht vertauschen

Validieren beantwortet „akzeptiert GraphQL.js dieses Schema-SDL?“. Beautify beantwortet „ist dieses GraphQL lesbar?“. Einrückung behebt niemals einen unbekannten Typ.

Validieren: buildSchema — valid oder invalid, Issues mit Zeile/Spalte wenn vorhanden

Beautify: Prettier — tabWidth 2 oder 4, Tabs, printWidth 80 / 100 / 120

JavaScript-Prettier-Optionen (Semikolons, Quotes, Trailing Commas) gelten nicht für GraphQL

Empfohlene Reihenfolge: SDL validieren → Typen korrigieren → beautify → PR öffnen

Beautify kann eine Query formatieren, die validate-graphql zu Recht als Nicht-SDL ablehnt

Erst validieren, dann formatieren: ein praxisnaher Ablauf

Den GraphQL-SDL-Validator nutzen

Öffnen Sie den GraphQL-Validator, fügen Sie ein einzelnes Schema-Dokument ein (max. 512 KiB UTF-8) und warten Sie auf das gedebouncte Verdict. Das Ergebnispanel zeigt Valid oder Invalid, den ersten Fehler mit Zeile und Spalte wenn bekannt, eine Copy-Error-Aktion und Schema-Statistiken nach erfolgreichem Parse.

Nur Schema-SDL einfügen — keine Query, keine Remote-Endpoint-URL

Live-Validierung im Editor — kein Upload, kein Konto

Statistiken nach gutem Parse: Typen, Query-Felder, Mutations, Subscriptions

Fehlermeldung in die PR kopieren, wenn Sie eine Spur brauchen

512-KiB-Grenze — größere Schemas gehören in lokales GraphQL.js oder CI

Mit Beautify GraphQL formatieren

Der GraphQL-Beautifier pretty-printet Schemas und Operationen mit Prettier. Nützlich für Review-Diffs — er ersetzt validate nicht. Optionen: 2 oder 4 Leerzeichen oder Tabs plus Druckbreite. Alle Formatter liegen im Beautify-Tools-Hub.

Lesbares SDL für Menschen — verschachtelte Felder aufgefächert

Dieselbe Prettier-Engine wie die übrige FastMinify-Formatter-Familie

Syntaxfehler mit Zeilenhinweis — korrigieren und erneut versuchen

Queries und Fragments sind hier willkommen; nicht auf validate-graphql

validate → beautify verketten, damit Reviewer ein getyptes, eingerücktes Schema sehen

Szenario — Unbekannter Typ in einer Pull Request

Ein Teammitglied hat Pet in Animal umbenannt, aber pet(id: ID!): Pet auf Query gelassen. CI oder Server schlagen fehl, mit wenig Kontext im GitHub-Overlay.

Schritt 1: Schema in validate-graphql einfügen

Öffnen Sie validate-graphql. Ein invalid-Verdict mit Unknown type "Pet" (und einer Zeile wenn vorhanden) zeigt auf das veraltete Feld.

Schritt 2: Typnamen korrigieren oder den Typ wiederherstellen

Entweder den Rückgabetyp des Felds auf Animal ändern oder type Pet wieder hinzufügen. Erneut einfügen, bis das Panel ein gültiges Schema zeigt.

Schritt 3: Beautify und committen

Das korrigierte SDL durch beautify-graphql jagen, kopieren oder herunterladen, PR aktualisieren. Reviewer lesen Typen, keinen Einzeiler-Blob.

Szenario — Unlesbares SDL vor einem Schema-Review

Ein generiertes oder minifiziert wirkendes Schema landet im Repo. Reviewer sehen nicht, welche Felder auf Query versus Mutation sitzen.

Schritt 1: Zuerst beautify, wenn Sie es nicht einmal lesen können

In beautify-graphql einfügen. Prettier fächert Selections und Typkörper auf. Dieser Schritt beweist nicht, dass das Schema gültig ist.

Schritt 2: Das formatierte Dokument validieren

Das eingerückte SDL in validate-graphql kopieren. Prüfen, dass der Query-Root existiert und jeder benannte Typ definiert ist.

Schritt 3: Die Statistik-Kacheln prüfen

Typanzahl und Root-Feldzahlen helfen, eine leere Query oder verlorene Mutations zu sehen. Dann die formatierte Datei committen.

Fazit

Validieren Sie GraphQL-SDL im Browser mit buildSchema und formatieren Sie danach mit Prettier — lokal, ohne das Schema irgendwohin zu senden. Diese Schleife findet unbekannte Typen und fehlende Query-Roots vor CI oder Gateway. Sie ersetzt keinen laufenden Server, keine Introspection und kein Federation-Compose. Für REST-Verträge bleiben Sie im API-Hub; für lesbare Queries bei Beautify GraphQL.

GraphQL jetzt validieren oder formatieren

Schema-SDL vor jeder Schema-PR in validate-graphql einfügen

Keine Queries in den Validator — auf Beautify GraphQL formatieren

Einen Query-Root erwarten, außer die Schema-Definition nennt einen anderen Typ

Valid als GraphQL.js-Akzeptanz lesen, nicht als Produktionsbeweis

validate → beautify verketten, CI als Merge-Gate behalten