Introspection-JSON

GraphQL SDL

Was ist der Introspection-JSON-zu-SDL-Konverter?

Wenn du ein Schema aus Apollo Studio, Postman, Insomnia ziehst oder get-graphql-schema gegen einen Live-Endpoint laufen lässt, bekommst du nicht das freundliche SDL zurück, das du geschrieben hast — sondern das Ergebnis von query { __schema { ... } }: 600+ Zeilen verschachteltes JSON, das jeden Typ, jedes Feld und jeden Modifier in einem Baum aus kind-/name-/ofType-Objekten beschreibt. Für ein Tool nützlich, für einen Menschen unlesbar. Dieser Konverter nimmt das JSON und gibt es als SDL aus, wie du es tatsächlich in ein Repo committen würdest, gemäß den Introspection-Regeln der GraphQL-Spec vom Oktober 2021.

Alles passiert in deinem Browser — kein Upload, keine KI, kein Schema verlässt den Rechner. Die Konvertierungslogik spiegelt das, was graphql-js intern mit buildClientSchema und printSchema macht: durch den __schema-Baum laufen, die introspection-eigenen Typen (__Schema, __Type, __Field, …) und die eingebauten Skalare überspringen und jede verbleibende Definition mit ihrer Beschreibung, ihren Feldern, Argumenten, Default-Werten und Deprecation-Gründen unverändert ausgeben. Egal ob du den vollen Envelope { "data": { "__schema": ... } } einfügst, nur { "__schema": ... }, oder sogar nur den nackten __schema-Wert — die Seite kommt mit allen drei Varianten klar.

Die Ausgabe ist gruppiert: zuerst Skalare, dann Enums, Interfaces, Unions, Input-Typen und zum Schluss Object-Typen — innerhalb jeder Gruppe alphabetisch, mit zwei Leerzeichen Einrückung und einer Leerzeile zwischen den Definitionen. Idempotent genug, um direkt in eine <code>.graphql</code>-Datei deines Repos zu wandern.

So benutzt du den Konverter

Drei Schritte. Die Buttons unten sind die echten Buttons dieser Seite.

Einfügen, hochladen oder Beispiel laden

Füge dein Introspection-JSON in das linke Eingabe-Panel ein — die Konvertierung passiert automatisch einen Sekundenbruchteil nachdem du aufhörst zu tippen, also kein Convert-Button, den man suchen müsste. Klicke auf Hochladen für eine .json-Datei, die du aus Apollo Studio oder Postman exportiert hast, oder auf Beispiel, um ein realistisches Order/Customer/Money-Introspection-Ergebnis zu laden. Ein typisches Einfügen beginnt so:

{
  "data": {
    "__schema": {
      "queryType": { "name": "Query" },
      "types": [
        { "kind": "OBJECT", "name": "Order", "fields": [...] },
        ...
      ]
    }
  }
}

Du kannst auch den inneren { "__schema": ... }-Wert oder das nackte __schema-Objekt einfügen — die Seite probiert alle drei Formen. Tools wie get-graphql-schema und der Introspection-Endpoint von Apollo Server liefern standardmäßig eine dieser Formen.

SDL-Ausgabe lesen

Das rechte Ausgabe-Panel rendert das Schema als SDL. Jeder Typ steht in seiner eigenen Definition mit zwei Leerzeichen Einrückung, Felder ein pro Zeile, Beschreibungen über dem Typ oder Feld als Triple-Quoted-Block-Strings, und Deprecation-Gründe werden als @deprecated(reason: "...") in derselben Zeile gerendert. Eingebaute Skalare und die __-Introspection-Typen werden herausgefiltert — was du bekommst, ist exakt das Schema, das dein Server veröffentlicht, so wie es die GraphQL-Spec von Relay zur Dokumentation empfiehlt. Wenn das JSON kaputt ist oder das __schema-Feld fehlt, bekommst du eine freundliche Inline-Meldung statt eines Stack-Traces.

Kopieren oder herunterladen

Drück Kopieren, um dir das SDL für eine PR-Beschreibung, ein Doc oder einen Chat zu schnappen. Herunterladen speichert es als schema.graphql — direkt rein in dein Repo. Der Clear-Button im Eingabe-Panel setzt dich auf einen leeren Stand zurück. Die Konvertierung läuft komplett client-seitig; das Introspection-Ergebnis verlässt die Seite nie.

Wann du das wirklich brauchst

Schema von einem Live-Endpoint einfangen

Du übernimmst einen GraphQL-Service, der keine Schema-Datei im Repo hat — nur den laufenden Server. Du feuerst eine Introspection-Query ab, fügst das JSON hier ein, und in fünf Minuten ist eine erste schema.graphql committed. Einfacher, als buildClientSchema und printSchema aus graphql-js für eine einmalige Aktion zu verdrahten.

Apollo-Studio- oder Postman-Export lesen

Der Schema-Export aus Apollo Studio ist Introspection-JSON. Genauso der "Save schema"-Button in Postman bei einer GraphQL-Request. Wandle es hier um und du kannst das Schema in einem Code-Editor tatsächlich überfliegen, statt mit zusammengekniffenen Augen JSON anzustarren.

Zwei Snapshots eines Live-Schemas vergleichen

Lass die Introspection gegen Staging und Production laufen, wandle beide in SDL um und diff die zwei Dateien. Ein fehlendes Feld oder einen umbenannten Enum-Wert zu finden, ist in SDL trivial und in rohem Introspection-JSON praktisch unmöglich.

Type-Stubs für einen fremden Service generieren

Brauchst du TypeScript-Typen oder React-Hooks für eine fremde GraphQL-API? Die meisten Code-Generatoren wollen SDL, kein Introspection-JSON. Hier umwandeln und dann das SDL in deine Codegen-Pipeline geben — graphql-react, graphql-codegen, oder was dein Stack so verwendet.

Häufige Fragen

Brauche ich den vollen { "data": { "__schema": ... } }-Envelope?

Nein. Die Seite akzeptiert drei Formen: den vollständigen GraphQL-Response-Envelope, nur { "__schema": ... }, oder sogar das nackte __schema-Objekt. Egal welche du einfügst — sie findet die __schema-Wurzel und arbeitet von dort aus.

Was, wenn mein JSON kein __schema-Feld hat?

Du bekommst eine freundliche Meldung: "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." Kein Crash, kein Stack-Trace.

Bleiben Beschreibungen und Deprecation-Gründe erhalten?

Ja. Typ- und Feldbeschreibungen werden als Triple-Quoted-Block-Strings über der Definition ausgegeben. Deprecated-Felder und Enum-Werte bekommen @deprecated(reason: "...") in derselben Zeile. Das entspricht der Ausgabe von printSchema aus graphql-js.

Was ist mit den eingebauten Skalaren und den __-Introspection-Typen?

Werden herausgefiltert. String, Int, Float, Boolean und ID sind im SDL implizit — sie tauchen nur in Feldtypen auf, nicht als Top-Level-Definitionen. Das Gleiche gilt für __Schema, __Type, __Field und den Rest der Introspection-Meta-Typen.

Kommt die Ausgabe garantiert wieder beim selben Introspection-Ergebnis raus?

Semantisch ja — das SDL beschreibt dasselbe Schema. Byte-für-Byte nein, weil die Reihenfolge der Typen und Felder von deiner ursprünglichen Quelldatei abweichen kann. Die Ausgabe ist innerhalb jeder Definitionsgruppe alphabetisch sortiert, damit Diffs stabil bleiben.

Wird mein Introspection-Ergebnis an einen Server geschickt?

Nein. Die Konvertierung läuft komplett im Browser. Es wird nichts hochgeladen, nichts geloggt. Sicher, um Schemas aus internen oder noch unveröffentlichten Services einzufügen.

Weitere GraphQL-Tools

Sobald du das SDL hast, übernehmen diese den Rest:

Introspection-JSON zu GraphQL SDL