Introspection JSON

GraphQL SDL

Wat is de Introspection JSON naar SDL Converter?

Als je een schema uit Apollo Studio, Postman of Insomnia trekt, of get-graphql-schema tegen een live endpoint draait, krijg je niet de prettige SDL terug die jij geschreven hebt — je krijgt het resultaat van query { __schema { ... } }: 600+ regels geneste JSON die elke type, elk field en elke modifier beschrijven in een boom van kind / name / ofType-objecten. Handig voor een tool, onleesbaar voor een mens. Deze converter neemt die JSON en print hem terug als de SDL die je daadwerkelijk in een repo zou committen, volgens de introspection-regels uit de GraphQL-spec van oktober 2021.

Alles gebeurt in je browser — geen upload, geen AI, geen schema dat ergens heen wordt gestuurd. De conversielogica spiegelt wat graphql-js intern doet met buildClientSchema en printSchema: door de __schema-boom lopen, de introspection-only types (__Schema, __Type, __Field, …) en built-in scalars overslaan, en elke overgebleven definitie uitspuwen met beschrijving, fields, arguments, default values en deprecation-redenen ongeschonden. Of je nu de volledige { "data": { "__schema": ... } }-envelope plakt, alleen { "__schema": ... }, of zelfs de kale __schema-waarde — de pagina kan met alle drie overweg.

De output is gegroepeerd: eerst de scalars, dan enums, interfaces, unions, input types en als laatste object types — alfabetisch binnen elke groep, met inspringing van twee spaties en een lege regel tussen definities. Idempotent genoeg om direct in een <code>.graphql</code>-bestand in je repo te droppen.

Zo gebruik je de converter

Drie stappen. De knoppen hieronder zijn de echte knoppen op deze pagina.

Plakken, uploaden of een voorbeeld laden

Plak je introspection JSON in het linker Input-paneel — de conversie gebeurt automatisch een fractie van een seconde nadat je stopt met typen, dus geen Convert-knop om naar te zoeken. Klik op Uploaden voor een .json-bestand dat je uit Apollo Studio of Postman geëxporteerd hebt, of druk op Voorbeeld om een realistisch Order/Customer/Money introspection-resultaat te laden. Een typische plak begint zo:

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

Je kunt ook de binnenste { "__schema": ... }-waarde plakken of het kale __schema-object — de pagina probeert alle drie de vormen. Tools zoals get-graphql-schema en het introspection-endpoint van Apollo Server produceren standaard een van deze vormen.

Lees de SDL-output

Het rechter Output-paneel rendert het schema als SDL. Elk type krijgt zijn eigen definitie met inspringing van twee spaties, fields een per regel, beschrijvingen blijven boven het type of field als block strings tussen drie aanhalingstekens, en deprecation-redenen worden gerenderd als @deprecated(reason: "...") op dezelfde regel. Built-in scalars en de __-introspection-types worden eruit gefilterd — wat je krijgt is precies het schema dat je server publiceert, op de manier waarop de GraphQL-spec van Relay aanraadt het te documenteren. Als de JSON misvormd is of het __schema-veld mist, krijg je een vriendelijke inline-melding in plaats van een stack trace.

Kopiëren of downloaden

Druk op Kopiëren om de SDL mee te nemen voor een PR-omschrijving, doc of chat. Druk op Downloaden om hem op te slaan als schema.graphql — direct in je repo droppen. De clear-knop op het input-paneel zet je terug naar een leeg startpunt. De conversie is volledig client-side; het introspection-resultaat verlaat de pagina nooit.

Wanneer je dit echt zou gebruiken

Een schema afvangen van een live endpoint

Je erft een GraphQL-service die geen schema-bestand in de repo heeft — alleen de draaiende server. Schiet een introspection-query af, plak de JSON hier, en je hebt binnen vijf minuten een initiële schema.graphql committed. Makkelijker dan buildClientSchema en printSchema uit graphql-js aan elkaar knopen voor één eenmalige actie.

Een Apollo Studio- of Postman-export lezen

De schema-export uit Apollo Studio is de introspection JSON. Hetzelfde voor de "Save schema"-knop in Postman op een GraphQL-request. Converteer hier en je kunt het schema daadwerkelijk doorbladeren in een code-editor in plaats van met samengeknepen ogen naar JSON te turen.

Twee snapshots van een live schema diffen

Draai introspection tegen staging en productie, converteer beide naar SDL, en diff de twee bestanden. Een ontbrekend field of een hernoemde enum-waarde spotten is triviaal in SDL en zo goed als onmogelijk in ruwe introspection JSON.

Type-stubs genereren van een service die niet van jou is

TypeScript-types of React-hooks nodig voor een GraphQL-API van een derde partij? De meeste codegenerators willen SDL, geen introspection JSON. Hier converteren, en dan de SDL je codegen-pipeline in voeren — graphql-react, graphql-codegen, of wat je stack ook gebruikt.

Veelgestelde vragen

Heb ik de volledige { "data": { "__schema": ... } }-envelope nodig?

Nee. De pagina accepteert drie vormen: de volledige GraphQL-response-envelope, alleen { "__schema": ... }, of zelfs het kale __schema-object. Welke je ook plakt, hij vindt de __schema-root en werkt vanaf daar.

Wat als mijn JSON geen __schema-veld heeft?

Je krijgt een vriendelijke melding: "Expected an introspection result. Couldn't find __schema field. Paste the JSON returned by the GraphQL introspection query." Geen crash, geen stack trace.

Worden beschrijvingen en deprecation-redenen behouden?

Ja. Type- en field-beschrijvingen worden uitgespuwd als block strings tussen drie aanhalingstekens boven de definitie. Deprecated fields en enum-waarden krijgen @deprecated(reason: "...") op dezelfde regel. Dit komt overeen met de output van printSchema uit graphql-js.

Hoe zit het met built-in scalars en de __ introspection-types?

Eruit gefilterd. String, Int, Float, Boolean en ID zijn impliciet in SDL — ze duiken alleen op in field-types, niet als top-level definities. Hetzelfde geldt voor __Schema, __Type, __Field en de rest van de introspection-meta-types.

Is de output gegarandeerd dat hij round-tript naar hetzelfde introspection-resultaat?

Semantisch wel — de SDL beschrijft hetzelfde schema. Byte-voor-byte niet, omdat de volgorde van types en fields kan afwijken van je oorspronkelijke bronbestand. De output is alfabetisch gesorteerd binnen elke definitiegroep voor stabiele diffs.

Wordt mijn introspection-resultaat naar een server gestuurd?

Nee. De conversie draait volledig in je browser. Niets wordt geüpload, niets wordt gelogd. Veilig om schemas van interne of nog niet uitgebrachte services te plakken.

Andere GraphQL-tools

Zodra je de SDL hebt, regelen deze de rest:

Introspection JSON naar GraphQL SDL