Setting the file. One moment.
Subchapter 12.4
references/schema.mdMarkdown9 KBView on GitHub
Commands for exploring a GraphQL schema: get a structured overview, zoom into a single type or field, or search for types and fields by keyword. These are designed for agent-driven schema discovery — an agent can search → describe → write a query in a closed loop, without loading a huge SDL into its context.
Local and offline — these take SDL, not a graph ref. rover schema describe and rover schema search read SDL from a file or from stdin only; they do not call GraphOS and need no authentication. Unlike other rover commands, passing a graph ref fails:
❌ rover schema describe my-graph@current
✅ rover graph fetch my-graph@current | rover schema describe -Pipe — don’t read the raw SDL. Running rover graph fetch/introspect on its own dumps the whole schema into context; always pipe it into describe/search so only the compact result reaches you. To explore a graph that lives in GraphOS, fetch its schema first and pipe it in — see GraphOS Schema Exploration.
Describe a schema by type, field, or directive. With no coordinate it prints a schema overview; with --coord it zooms into a single element.
# Schema overview (type counts, root operations)
rover schema describe schema.graphql
# Describe one type
rover schema describe schema.graphql --coord User
# Describe one field
rover schema describe schema.graphql --coord User.posts
# Expand referenced types one level deep
rover schema describe schema.graphql --coord User --depth 1
# Describe a directive
rover schema describe schema.graphql --coord @deprecated
# Raw SDL excerpt for the coordinate instead of a description
rover schema describe schema.graphql --coord User --view sdl
# Read from stdin (omit the file or pass -)
cat schema.graphql | rover schema describe
cat schema.graphql | rover schema describe - --coord User
# Machine-readable output
rover schema describe schema.graphql --coord User --format jsonCoordinate forms (apollo-compiler SchemaCoordinate syntax):
| Form | Matches |
|---|---|
Type | object, interface, enum, input, scalar, or union |
Type.field | field on an object/interface, or value on an enum/input |
Type.field(arg:) | argument on a field |
@directive | directive definition |
@directive(arg:) | argument on a directive |
Options:
| Option | Description |
|---|---|
[FILE] | SDL file to read. Omit or pass - to read from stdin. |
--coord, -c <COORDINATE> | Schema coordinate to inspect. Omit for a full overview. |
--depth, -d <N> | Inline referenced type definitions up to N levels deep (types/fields only; default 0). |
--include-deprecated | Show deprecated fields and enum values. |
--view, -v <VIEW> | Output view: description (default) or sdl. |
--format json | Machine-readable JSON output. Works on the subcommand or top-level (rover --format json schema describe ...). |
Field coordinates automatically include the field’s argument and return types, so a single
--coord Type.fieldcall gives an agent enough context to use it.
Find types and fields by keyword. Each result is a schema coordinate plus the path(s) from a root operation that reach it — enough to write a query from a single search.
# Single keyword
rover schema search schema.graphql email
# Multiple terms — all must match (AND)
rover schema search schema.graphql "create post"
# Comma-separated clauses — any clause matches (OR)
rover schema search schema.graphql "email, displayName"
# Limit results (default 10)
rover schema search schema.graphql author --limit 20
# Include deprecated members
rover schema search schema.graphql id --include-deprecated
# Read from stdin (FILE must be -)
cat schema.graphql | rover schema search - user
# Machine-readable output
rover --format json schema search schema.graphql emailExample output:
1 result for "email"
User.email — The user's email address
field · via Query.user, Mutation.createPost -> Post.authorThe via line lists complete paths from a Query/Mutation root to the match, with intermediate types included — so an agent can turn a result straight into an operation.
Ranking — results are ordered by match tier (strongest first), then alphabetically by coordinate. Names are split on camelCase / snake_case and matching is case-insensitive:
| Tier | Matches when the term… |
|---|---|
| Exact | is a substring of the name or a name token |
| Stem | shares an English stem with a name token |
| Fuzzy | is within one edit of a name token (terms ≥ 4 chars; shorter terms must match a token exactly) |
| Description | appears in the SDL description, with no name match |
Options:
| Option | Description |
|---|---|
<FILE> | SDL file to read (required). Pass - to read from stdin. |
<TERMS>... | Search terms (required). Space-separated = all match (AND); comma-separated = OR clauses. |
--limit, -n <N> | Maximum number of results (default 10). |
--include-deprecated | Include deprecated fields and enum values. |
--format json | Machine-readable JSON output. Works on the subcommand or top-level. |
schema describe and schema search work on local SDL, so to explore a graph registered in GraphOS you fetch its schema first and pipe it in. Any rover ... fetch command prints SDL to stdout in its default (plain) format, so it pipes directly.
Authentication: the fetch step calls GraphOS and needs auth (
rover config authorAPOLLO_KEY) and a graph reference (graph@variant). Theschema describe/schema searchstep is local and needs neither.
Fetch sources:
| Command | Returns |
|---|---|
rover graph fetch <GRAPH_REF> | API schema (client-facing) — best default for discovering what clients can query; omits federation internals |
rover subgraph fetch <GRAPH_REF> --name <NAME> | one subgraph’s schema (with federation directives) |
rover supergraph fetch <GRAPH_REF> | full supergraph SDL — includes federation internals (join__/link__ types); use only for composition/federation inspection |
Pipe directly (no temp file):
# Overview of a GraphOS graph
rover graph fetch my-graph@current | rover schema describe
# Find fields by keyword
rover graph fetch my-graph@current | rover schema search - "playback"
# Zoom into a coordinate from the search results
rover graph fetch my-graph@current | rover schema describe - --coord <Type.field> --depth 1Save once, explore repeatedly (more efficient for large schemas):
rover supergraph fetch my-graph@current > schema.graphql
rover schema search schema.graphql "playback"
rover schema describe schema.graphql --coord <Type.field> --depth 1A local running server works too, via introspection:
rover subgraph introspect http://localhost:4001/graphql | rover schema search - "user"With these two commands an agent can go from a vague request to an executable query with no human guidance:
# 1. What's in this graph?
rover graph fetch mcp-showcase-spotify@current | rover schema describe
# 2. Find the relevant fields — returns Player.currentlyPlaying
# via Query.me -> CurrentUser.player
rover graph fetch mcp-showcase-spotify@current | rover schema search - "currently playing"
# 3. Expand the type on the returned path
rover graph fetch mcp-showcase-spotify@current | rover schema describe - --coord Player.currentlyPlaying --depth 1
# 4. Write and run the query using the `via` path from step 2.When piping, prefer the save-once pattern in step 2–3 if you run several searches against the same graph — it avoids re-fetching.
Running it (step 4): Rover does not execute operations. Get the endpoint — rover subgraph list <graph@variant> shows the Routing Url for a single-subgraph graph, or use the router URL from GraphOS Studio (for a cloud router, rover cloud config fetch <graph@variant>) for a federated one — then send the query with curl. Don’t hunt for it via the Platform API; the API key lives in Rover’s profile/keychain, not $APOLLO_KEY.
search vs describe: use search to find a field by concept/keyword — it surfaces nested fields with their path from a root operation. Use describe for the overview or a known coordinate. The overview lists only root fields, so search is how you locate nested ones (e.g. search "service provider" → Launch.launchServiceProvider, which no overview shows).fetch/introspect step needs network and auth.--coord Type.field --depth 1 to pull a field plus its argument and return types in one call.rover --format json schema search ... (or describe) when a script or tool consumes the output.apollo-mcp-server skill — rover schema search is keyword/fuzzy (lexical) matching.