GRAPHQL Introspection Trimmer

GraphQL Schema & Introspection Trimming Protocol

Overview

When integrating with or debugging a GraphQL API, agents often run full schema introspection queries (__schema { types { name fields { name type } } }) or ingest full 10,000-line schema.graphql SDL files.

Full schema introspection results in massive Context Overflow: a production enterprise GraphQL schema (Shopify, GitHub, Stripe) is 500KB to 3MB of raw JSON (consuming 80,000+ tokens), even if the agent only needs to query 2 fields on the User object.

The GraphQL Schema Trimming Protocol parses the schema AST and extracts strictly the targeted operation and its transitively referenced types, discarding unreferenced queries, mutations, and deprecated fields.

Full Introspection Dump vs. Targeted Subgraph SDL

┌─────────────────────────────────────────────────────────────┐
│                 GraphQL Schema Context Impact               │
│                                                             │
│  Full Introspection JSON Dump (65,000 Tokens):              │
│  • 420 Object Types (Billing, Inventory, Webhooks, Admin)   │
│  • 180 Mutations & Subscriptions                            │
│  • 1,200 Field descriptions and deprecation reasons         │
│  ↳ 65,000 tokens billed, blows context limit                │
│                                                             │
│  Targeted Subgraph SDL (240 Tokens - 99.6% Reduction!):     │
│  type Query { getUser(id: ID!): User }                      │
│  type User { id: ID!, email: String!, role: Role! }         │
│  enum Role { ADMIN, MEMBER, VIEWER }                        │
│  ↳ 240 clean tokens, exact type contracts preserved         │
└─────────────────────────────────────────────────────────────┘

The 3-Step Schema Pruning Algorithm

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. IDENTIFY ROOT OPERATION: Target query (e.g. `Query.searchProducts`)     │
│ 2. RECURSIVE TYPE RESOLUTION: Follow field return types & input arguments │
│ 3. STRIP METADATA: Drop description strings, `@deprecated`, & uncalled SDL│
└───────────────────────────────────────────────────────────────────────────┘

Production Python GraphQL Trimmer (graphql-core)

from graphql import parse, print_ast, TypeDefinitionNode, FieldDefinitionNode
from typing import Set

def prune_graphql_schema(sdl_source: str, target_queries: list) -> str:
    """Extracts only the types and fields required for specific queries."""
    ast = parse(sdl_source)
    needed_types: Set[str] = set(target_queries)
    
    # 1. First pass: find return types of target queries
    for defn in ast.definitions:
        if getattr(defn, "name", None) and defn.name.value in ["Query", "Mutation"]:
            for field in defn.fields:
                if field.name.value in target_queries:
                    # Extract return type name
                    curr = field.type
                    while hasattr(curr, "type"):
                        curr = curr.type
                    needed_types.add(curr.name.value)

    # 2. Second pass: filter definitions
    pruned_definitions = [
        defn for defn in ast.definitions
        if getattr(defn, "name", None) and defn.name.value in needed_types
    ]
    
    ast.definitions = pruned_definitions
    return print_ast(ast)

Production TypeScript Schema Trimmer (graphql)

import { buildSchema, print, parse } from "graphql";

export function getMinimalOperationSDL(fullSDL: string, rootTypeName: string): string {
  const schema = buildSchema(fullSDL);
  const targetType = schema.getType(rootTypeName);
  
  if (!targetType) throw new Error(`Type ${rootTypeName} not found in schema.`);
  
  // Return clean SDL representation for target type only
  return `type ${targetType.name} {\n${Object.values(targetType.toConfig().fields || {})
    .map((f: any) => `  ${f.name}: ${f.type.toString()}`)
    .join("\n")}\n}`;
}

Benchmark Comparison

Querying a single user endpoint against a large e-commerce GraphQL schema:

Agent Operational Directive

MANDATORY: Never inject full GraphQL Introspection JSON dumps into conversation context. Use client-side AST tooling to prune the schema to the specific queries, mutations, and types required for the active prompt.