Schema Support

The Laboratory provides comprehensive schema support through automatic introspection and a visual Builder that helps you explore and build GraphQL operations.

Schema Introspection

The Laboratory automatically introspects your GraphQL schema when you provide an endpoint. This enables:

• Auto-completion - The editor suggests available fields, types, and arguments
• Validation - Real-time checking of your queries against the schema
• Type information - See field types, required arguments, and descriptions
• Builder - Visual exploration of your entire schema

Setting Your Endpoint

Default Endpoint

If your Laboratory is configured with a default endpoint, it will be automatically loaded. You can restore the default endpoint at any time using the restore button in the Builder panel.

Custom Endpoint

To use a different endpoint:

1. Open the Builder panel (left side of the Laboratory)
2. Enter your GraphQL endpoint URL in the endpoint input field
3. The Laboratory will automatically fetch the schema via introspection

The endpoint can be:

• A standard HTTP/HTTPS GraphQL endpoint
• A GraphQL endpoint with custom path (e.g., /graphql, /api/graphql)
• Any endpoint that supports GraphQL introspection

Refreshing the Schema

If your schema changes, you can refresh it:

1. Open the Command Palette (⌘J)
2. Select "Refetch schema"
3. Or use the refresh button in the Builder panel

Introspection Headers

Some GraphQL APIs require authentication or custom headers for schema introspection, not only for operations. Configure this in Settings (gear icon in the left sidebar, or Introspection settings in the Builder panel) under the Introspection section.

Introspection requests use headers from two sources, which you can combine:

1. Static headers — JSON configured in the Headers editor under Introspection settings
2. Active operation headers — Optional headers from the currently active operation tab

No headers

To introspect without extra headers:

1. Set Headers to an empty object: {}
2. Turn off Include active operation headers

The Laboratory sends the introspection query with no custom HTTP headers (aside from defaults such as Content-Type).

Static headers from settings

Use the Headers editor to define headers sent with every introspection request. Headers are JSON, same format as operation headers:

{
  "Authorization": "Bearer your-token-here",
  "X-API-Key": "your-api-key"
}

Environment variable substitution

Static introspection headers support the same {{variableName}} template syntax as operation headers. Values are resolved from Environment Variables before the introspection request is sent. The preflight script does not run for static headers alone.

{
  "Authorization": "Bearer {{AUTH_TOKEN}}",
  "X-API-Key": "{{API_KEY}}"
}

Active operation headers

Enable Include active operation headers to merge headers from the active operation tab into the introspection request. This is useful when the same auth headers you use for queries should apply to schema discovery.

• Static introspection headers are applied first
• Active operation headers are merged on top (same header name in the operation tab overrides the static value)
• Your Preflight script runs before introspection (same as before running an operation), so tokens and headers set in preflight apply to the schema fetch

When preflight runs for introspection (and on schema polling), the same script executes repeatedly. If your script uses lab.prompt(), you may see many popup dialogs. A friendly approach is to store values in Environment Variables and read them with lab.environment.get() instead—though prompts are still fine if you prefer them.

Example workflow:

1. Add Authorization (and any other required headers) on your operation’s Headers tab
2. Enable Include active operation headers in Introspection settings
3. Switch the active operation tab to control which headers are used for introspection

You can use static settings headers alone, active operation headers alone (with an empty {} in Headers), or both together.

Other introspection options

The Introspection settings section also includes:

• Method — GET or POST for the introspection HTTP request (default: POST)
• Schema description — Include field descriptions in the introspection result when supported

Fetch and subscription behavior are configured in separate sections of the same Settings panel.

The Builder

The Builder provides a visual way to explore your schema and construct operations.

Schema Navigation

The Builder organizes your schema into three main sections:

• Query - All query operations available in your schema
• Mutation - All mutation operations
• Subscription - All subscription operations

Each section shows all available fields with their types and arguments.

Building Operations Visually

To build an operation using the Builder:

1. Select a root field - Click on a query, mutation, or subscription field
2. Choose nested fields - Expand object types to select nested fields
3. Add arguments - Check arguments you want to include
4. Watch it build - The query is automatically generated in the editor

Field Types

The Builder displays different icons for different field types:

• Scalar fields - Simple types like String, Int, Boolean
• Object fields - Complex types that can be expanded
• List fields - Arrays indicated by [Type]
• Required fields - Marked with ! (non-nullable)

Arguments

When a field has arguments:

1. Expand the [arguments] section
2. Check the arguments you want to include
3. Arguments are automatically added to your query with placeholder values
4. Fill in the actual values in the Variables tab

Collapsing and Expanding

• Expand all - Click on fields to expand and see nested types
• Collapse all - Use the collapse button to close all expanded sections
• Auto-expand - Fields used in your current query are automatically expanded

Schema-Aware Editor

The operation editor uses your schema to provide:

Auto-completion

As you type, the editor suggests:

• Field names
• Argument names
• Type names
• Enum values

Press Tab or Enter to accept suggestions.

Validation

The editor validates your query in real-time:

• Red underlines - Syntax errors
• Yellow underlines - Schema validation errors
• Hover for details - See specific error messages

Type Information

Hover over any field or type to see:

• Field type
• Description (if available)
• Required arguments
• Deprecation status

Working Without a Schema

If you don't have a schema available, you can still:

• Write operations manually
• Use the editor without auto-completion
• Execute operations against any endpoint

However, you won't have access to:

• Visual Builder
• Auto-completion
• Schema validation
• Type information

Schema Caching

The Laboratory caches your schema to improve performance:

• Fast loading - Previously introspected schemas load instantly
• Automatic refresh - Schema is refreshed when you change endpoints
• Manual refresh - Use Command Palette to force a refresh

Best Practices

1. Use the Builder for exploration - Great for discovering available fields and types
2. Combine Builder and editor - Start with Builder, then fine-tune in the editor
3. Keep schema updated - Refresh when your API schema changes
4. Check types - Hover over fields to understand their types before using them
5. Validate early - Use schema validation to catch errors before execution

Troubleshooting

Schema Not Loading

If your schema doesn't load:

1. Check endpoint - Verify the endpoint URL is correct
2. Check CORS - Ensure your server allows introspection requests
3. Check authentication - Some endpoints require authentication for introspection. Configure introspection headers (static settings, active operation headers, or both) and ensure environment variables resolve if you use {{...}} in static headers
4. Check network - Verify you can reach the endpoint
5. Check preflight - If you use Include active operation headers, confirm your preflight script runs without errors before the schema fetch

Schema Out of Date

If your schema seems outdated:

1. Use "Refetch schema" from the Command Palette
2. Change and restore your endpoint
3. Refresh the page

Missing Fields

If fields don't appear in the Builder:

1. Check if you're looking in the correct tab (Query/Mutation/Subscription)
2. Verify the field exists in your schema
3. Refresh the schema
4. Some fields may be hidden based on permissions or schema configuration