What is introspection?

GraphQL's built-in way to query the schema itself. A special `__schema` query returns the entire API shape — types, fields, arguments, descriptions.

SDL (Schema Definition Language) is more readable than introspection JSON. Useful for committing to git, generating docs, or sharing with other tools.

Does it preserve descriptions?

Yes — descriptions on types, fields, and arguments all carry over as SDL comments. Comments become proper `""" description """` blocks in SDL 2018+.

Can I go SDL → introspection?

Different tool. This one goes introspection → SDL because that's the common debug direction (querying a live server to see its schema).

GraphQL Introspection → SDL

DevTools Surf

Example: GraphQL Introspection → SDL

A worked example, rendered from real sample data. Sign in to run the tool on your own input.

Input

{"data":{"__schema":{"types":[{"kind":"OBJECT","name":"User","fields":[{"name":"id","type":{"kind":"NON_NULL","ofType":{"kind":"SCALAR","name":"ID"}}},{"name":"name","type":{"kind":"SCALAR","name":"String"}},{"name":"email","type":{"kind":"SCALAR","name":"String"}}]},{"kind":"ENUM","name":"Role","enumValues":[{"name":"ADMIN"},{"name":"USER"}]}]}}}

Output

enum Role {
  ADMIN
  USER
}

type User {
  id: ID!
  name: String
  email: String
}

About GraphQL Introspection → SDL

GraphQL Introspection → SDL preview - Developer Utilities tool

Convert GraphQL introspection JSON to SDL schema. Part of the DevTools Surf developer suite. Browse more tools in the Developer Utilities collection.

Use Cases

API developers converting runtime schemas to version-controlled SDL files
Security auditors documenting API surface area from introspection
Migration teams recreating schemas from legacy GraphQL endpoints
DevOps engineers generating schema docs from running services

Tips

Paste the full introspection JSON including the __schema key
Compare generated SDL against your source schema for drift
Use the SDL output to initialize schema-first development

Fun Facts

GraphQL introspection is a built-in feature of the spec — every compliant server must respond to the __schema query, which is both powerful and a security consideration.
Many production APIs disable introspection to prevent schema leakage — Apollo Server has it off by default in production since Apollo Server 4, released in 2022.
SDL (Schema Definition Language) was not part of the original GraphQL spec — it was added in the June 2018 specification update after widespread community adoption.

FAQ

What is introspection?: GraphQL's built-in way to query the schema itself. A special `__schema` query returns the entire API shape — types, fields, arguments, descriptions.
Why convert to SDL?: SDL (Schema Definition Language) is more readable than introspection JSON. Useful for committing to git, generating docs, or sharing with other tools.
Does it preserve descriptions?: Yes — descriptions on types, fields, and arguments all carry over as SDL comments. Comments become proper `""" description """` blocks in SDL 2018+.
Can I go SDL → introspection?: Different tool. This one goes introspection → SDL because that's the common debug direction (querying a live server to see its schema).

Related Developer Utilities Tools

Collection JSON → cURL Git Diff → HTML Regex Visualizer Makefile Explainer Shell Script Linter GitHub Actions Visualizer HAR File Viewer API Response Mocker