Remote Schema Introspection

GraphQL Analyzer can fetch your schema directly from a running GraphQL endpoint via introspection.

Basic setup

schema: https://api.example.com/graphql
documents: src/**/*.{graphql,tsx}

The tool sends an introspection query to the endpoint. Introspection runs each time the schema is loaded; results are held in memory by the running LSP/CLI process.

Remote schema with options

For authenticated endpoints or custom timeouts, use the structured form:

schema:
  url: https://api.example.com/graphql
  headers:
    Authorization: Bearer ${API_TOKEN}
  timeout: 60
  retry: 3

Field	Required	Description
url	Yes	The GraphQL endpoint URL to introspect
headers	No	Map of header name → value; supports ${VAR} interpolation
timeout	No	Request timeout in seconds (default: 30)
retry	No	Number of retry attempts on failure (default: 0)

The ${VAR} syntax pulls values from environment variables at config load time. Use ${VAR:default} to provide a fallback when the variable is unset. This keeps secrets out of config files that are checked into source control.

Per-project remote schemas

projects:
  local:
    schema: schema.graphql
    documents: src/local/**/*.graphql
  remote:
    schema: https://api.example.com/graphql
    documents: src/remote/**/*.graphql

How it works

1. The tool sends a standard introspection query to the endpoint each time the schema is loaded
2. The schema response is held in memory by the running LSP/CLI process
3. Both the LSP and CLI use the in-memory schema for validation

Troubleshooting

Schema loading fails?

Check the endpoint is reachable:

RUST_LOG=debug graphql validate

Look for introspection errors in the debug output.

Schema out of date?

Restart the LSP server to re-fetch the schema. In VS Code: Ctrl/Cmd+Shift+P → “GraphQL Analyzer: Restart Server”.