Apollo Docs

Overview

The rover schema describe command provides structured descriptions of a GraphQL schema. Read from a local SDL file or pipe from stdin. Start with a full schema overview, then zoom into individual types, fields, directives, and arguments using a schema coordinate.

Usage

Bash
1rover schema describe [FILE] [OPTIONS]

Pass - as FILE or omit it entirely to read from stdin.

Coordinate (--coord)What you get
(none)Schema overview
TypeType description
Type.fieldField description and return type
Type.field(arg:)Field argument detail
@directiveDirective definition detail
@directive(arg:)Directive argument detail

Options

OptionDescription
-c, --coord <SCHEMA_COORDINATE>Schema coordinate to inspect (e.g. Post, User.posts, @auth)
-d, --depth <N>Expand referenced types N levels deep (default: 0)
--include-deprecatedShow deprecated fields and values
-v, --view <VIEW>Output view: description (default) or sdl

Examples

Schema overview

Bash
1rover schema describe schema.graphql
Text
1SCHEMA schema.graphql
2
330 types
486 fields
53 deprecated fields
6
7Operations
8+----------+---+-------------------+
9| Type     | # | Fields            |
10+==================================+
11| Query    | 5 | user              |
12|          |   | post              |
13|          |   | categories        |
14|          |   | search            |
15|          |   | viewer            |
16|----------+---+-------------------|
17| Mutation | 3 | createPost        |
18|          |   | updatePreferences |
19|          |   | deleteComment     |
20+----------+---+-------------------+
21
22Types
23+------------+----+--------------------------+
24| Kind       | #  | Names                    |
25+============================================+
26| objects    | 16 | Category                 |
27|            |    | Comment                  |
28|            |    | CommentConnection        |
29|            |    | CommentEdge              |
30|            |    | CreatePostPayload        |
31|            |    | DeleteCommentPayload     |
32|            |    | PageInfo                 |
33|            |    | Post                     |
34|            |    | PostConnection           |
35|            |    | PostEdge                 |
36|            |    | Preferences              |
37|            |    | SearchResults            |
38|            |    | Tag                      |
39|            |    | UpdatePreferencesPayload |
40|            |    | User                     |
41|            |    | Viewer                   |
42|------------+----+--------------------------|
43| inputs     | 2  | CreatePostInput          |
44|            |    | UpdatePreferencesInput   |
45|------------+----+--------------------------|
46| enums      | 4  | DigestFrequency          |
47|            |    | Role                     |
48|            |    | SearchType               |
49|            |    | SortOrder                |
50|------------+----+--------------------------|
51| interfaces | 3  | Node                     |
52|            |    | Profile                  |
53|            |    | Timestamped              |
54|------------+----+--------------------------|
55| unions     | 1  | ContentItem              |
56|------------+----+--------------------------|
57| scalars    | 2  | DateTime                 |
58|            |    | URL                      |
59+------------+----+--------------------------+
JSON output (--format json)
JSON
1{
2  "Overview": {
3    "schema_source": "schema.graphql",
4    "total_types": 30,
5    "total_fields": 86,
6    "total_deprecated": 3,
7    "query_fields": [
8      { "name": "user", "return_type": { "Named": "User" } },
9      { "name": "post", "return_type": { "Named": "Post" } },
10      { "name": "categories", "return_type": { "NonNullList": { "NonNullNamed": "Category" } } },
11      { "name": "search", "return_type": { "Named": "SearchResults" } },
12      { "name": "viewer", "return_type": { "Named": "Viewer" } }
13    ],
14    "mutation_fields": [
15      { "name": "createPost", "return_type": { "Named": "CreatePostPayload" } },
16      { "name": "updatePreferences", "return_type": { "Named": "UpdatePreferencesPayload" } },
17      { "name": "deleteComment", "return_type": { "Named": "DeleteCommentPayload" } }
18    ],
19    "objects": ["Category", "Comment", "CommentConnection", "CommentEdge", "CreatePostPayload", "DeleteCommentPayload", "PageInfo", "Post", "PostConnection", "PostEdge", "Preferences", "SearchResults", "Tag", "UpdatePreferencesPayload", "User", "Viewer"],
20    "inputs": ["CreatePostInput", "UpdatePreferencesInput"],
21    "enums": ["DigestFrequency", "Role", "SearchType", "SortOrder"],
22    "interfaces": ["Node", "Profile", "Timestamped"],
23    "unions": ["ContentItem"],
24    "scalars": ["DateTime", "URL"]
25  },
26  "success": true
27}

Type description

Bash
1rover schema describe schema.graphql --coord User
Text
1TYPE User (object)
2
3A registered user
4
5implements Node, Profile
6
78 fields
81 deprecated fields
9
10Fields
11+-----------+----------------+-----------------------------+
12| Field     | Type           | Description                 |
13+==========================================================+
14| id        | ID             |                             |
15|-----------+----------------+-----------------------------|
16| name      | String         |                             |
17|-----------+----------------+-----------------------------|
18| email     | String         | The user's email address    |
19|-----------+----------------+-----------------------------|
20| posts     | PostConnection | Posts authored by this user |
21|-----------+----------------+-----------------------------|
22| bio       | String         |                             |
23|-----------+----------------+-----------------------------|
24| avatarUrl | String         |                             |
25|-----------+----------------+-----------------------------|
26| createdAt | String         |                             |
27+-----------+----------------+-----------------------------+
28
29Available via: Query.user, Mutation.createPost -> CreatePostPayload.post -> Post.author
JSON output (--format json)
JSON
1{
2  "Type": {
3    "type": "object",
4    "name": "User",
5    "description": "A registered user",
6    "implements": ["Node", "Profile"],
7    "fields": [
8      { "name": "id", "return_type": "ID", "description": null, "is_deprecated": false, "deprecation_reason": null, "arg_count": 0 },
9      { "name": "name", "return_type": "String", "description": null, "is_deprecated": false, "deprecation_reason": null, "arg_count": 0 },
10      { "name": "email", "return_type": "String", "description": "The user's email address", "is_deprecated": false, "deprecation_reason": null, "arg_count": 0 },
11      { "name": "posts", "return_type": "PostConnection", "description": "Posts authored by this user", "is_deprecated": false, "deprecation_reason": null, "arg_count": 2 },
12      { "name": "bio", "return_type": "String", "description": null, "is_deprecated": false, "deprecation_reason": null, "arg_count": 0 },
13      { "name": "avatarUrl", "return_type": "String", "description": null, "is_deprecated": false, "deprecation_reason": null, "arg_count": 0 },
14      { "name": "createdAt", "return_type": "String", "description": null, "is_deprecated": false, "deprecation_reason": null, "arg_count": 0 }
15    ],
16    "field_count": 8,
17    "deprecated_count": 1,
18    "expanded_types": [],
19    "via": [
20      { "segments": [{ "type_name": "Query", "field_name": "user" }] },
21      { "segments": [{ "type_name": "Mutation", "field_name": "createPost" }, { "type_name": "CreatePostPayload", "field_name": "post" }, { "type_name": "Post", "field_name": "author" }] }
22    ]
23  },
24  "success": true
25}

Field description

Bash
1rover schema describe schema.graphql --coord User.posts
Text
1FIELD User.posts: PostConnection
2
3Posts authored by this user
4
52 args
6Args
7+--------+------+-------------------------------------------------+
8| Arg    | Type | Notes                                           |
9+=================================================================+
10| limit  | Int  | Maximum number of posts to return (default: 20) |
11|--------+------+-------------------------------------------------|
12| offset | Int  |                                                 |
13+--------+------+-------------------------------------------------+
14
15Available via: Query.user, Mutation.createPost -> CreatePostPayload.post -> Post.author
16
17Return type: PostConnection (object)
18+----------+----------+
19| Field    | Type     |
20+=====================+
21| edges    | PostEdge |
22|----------+----------|
23| pageInfo | PageInfo |
24+----------+----------+
JSON output (--format json)
JSON
1{
2  "Field": {
3    "type_name": "User",
4    "field_name": "posts",
5    "return_type": { "Named": "PostConnection" },
6    "description": "Posts authored by this user",
7    "arg_count": 2,
8    "args": [
9      { "name": "limit", "arg_type": "Int", "description": "Maximum number of posts to return", "default_value": "20" },
10      { "name": "offset", "arg_type": "Int", "description": null, "default_value": null }
11    ],
12    "via": [
13      { "segments": [{ "type_name": "Query", "field_name": "user" }] },
14      { "segments": [{ "type_name": "Mutation", "field_name": "createPost" }, { "type_name": "CreatePostPayload", "field_name": "post" }, { "type_name": "Post", "field_name": "author" }] }
15    ],
16    "input_expansions": [],
17    "return_expansion": {
18      "kind": "object",
19      "name": "PostConnection",
20      "fields": [
21        { "name": "edges", "return_type": "PostEdge", "description": null, "is_deprecated": false, "deprecation_reason": null, "arg_count": 0 },
22        { "name": "pageInfo", "return_type": "PageInfo", "description": null, "is_deprecated": false, "deprecation_reason": null, "arg_count": 0 }
23      ],
24      "implements": [],
25      "implementors": []
26    },
27    "is_deprecated": false,
28    "deprecation_reason": null
29  },
30  "success": true
31}

Field argument detail

Bash
1rover schema describe schema.graphql --coord "User.posts(limit:)"
Text
1FIELD ARG User.posts(limit:): Int
2
3Maximum number of posts to return
4
5Default: 20
JSON output (--format json)
JSON
1{
2  "FieldArg": {
3    "type_name": "User",
4    "field_name": "posts",
5    "arg_name": "limit",
6    "arg_type": { "Named": "Int" },
7    "description": "Maximum number of posts to return",
8    "default_value": "20"
9  },
10  "success": true
11}

Directive description

Bash
1rover schema describe schema.graphql --coord "@auth"
Text
1DIRECTIVE @auth
2
3Marks a field or object as requiring a minimum role
4
5Locations: FIELD_DEFINITION, OBJECT
6
7Args
8+----------+------+----------------------------------------------------------------+
9| Arg      | Type | Notes                                                          |
10+==================================================================================+
11| requires | Role | The minimum role required to access this field (default: USER) |
12+----------+------+----------------------------------------------------------------+
JSON output (--format json)
JSON
1{
2  "Directive": {
3    "name": "auth",
4    "description": "Marks a field or object as requiring a minimum role",
5    "args": [
6      {
7        "name": "requires",
8        "arg_type": "Role",
9        "description": "The minimum role required to access this field",
10        "default_value": "USER"
11      }
12    ],
13    "locations": ["FIELD_DEFINITION", "OBJECT"],
14    "repeatable": false
15  },
16  "success": true
17}

Directive argument detail

Bash
1rover schema describe schema.graphql --coord "@auth(requires:)"
Text
1DIRECTIVE ARG @auth(requires:): Role
2
3The minimum role required to access this field
4
5Default: USER
JSON output (--format json)
JSON
1{
2  "DirectiveArg": {
3    "directive_name": "auth",
4    "arg_name": "requires",
5    "arg_type": "Role",
6    "description": "The minimum role required to access this field",
7    "default_value": "USER"
8  },
9  "success": true
10}

SDL view

Bash
1rover schema describe schema.graphql --coord User --view sdl

Returns the raw SDL for the requested type or directive definition.

Read from stdin

Bash
1cat schema.graphql | rover schema describe --coord Post
2rover schema describe - --coord Post
Feedback

View on GitHub

Ask Community