GraphQL

GraphQL is a query language and execution engine tied to any backend servic...

README

GraphQL


GraphQL Logo

The GraphQL specification is edited in the markdown files found in
[/spec](./spec) the latest release of which is published at
https://graphql.github.io/graphql-spec/.

The latest draft specification can be found at
https://graphql.github.io/graphql-spec/draft/ which tracks the latest commit to
the main branch in this repository.

Previous releases of the GraphQL specification can be found at permalinks that
match their release tag. For
example, https://graphql.github.io/graphql-spec/October2016/. If you are linking
directly to the GraphQL specification, it's best to link to a tagged permalink
for the particular referenced version.

Overview


This is a Working Draft of the Specification for GraphQL, a query language for
APIs created by Facebook.

The target audience for this specification is not the client developer, but
those who have, or are actively interested in, building their own GraphQL
implementations and tools.

In order to be broadly adopted, GraphQL will have to target a wide variety of
backend environments, frameworks, and languages, which will necessitate a
collaborative effort across projects and organizations. This specification
serves as a point of coordination for this effort.

Looking for help? Find resources

Getting Started


GraphQL consists of a type system, query language and execution semantics,
static validation, and type introspection, each outlined below. To guide you
through each of these components, we've written an example designed to
illustrate the various pieces of GraphQL.

This example is not comprehensive, but it is designed to quickly introduce the
core concepts of GraphQL, to provide some context before diving into the more
detailed specification or the
GraphQL.js reference implementation.

The premise of the example is that we want to use GraphQL to query for
information about characters and locations in the original Star Wars trilogy.

Type System


At the heart of any GraphQL implementation is a description of what types of
objects it can return, described in a GraphQL type system and returned in the
GraphQL Schema.

For our Star Wars example, the
file in GraphQL.js defines this type system.

The most basic type in the system will be Human, representing characters like
Luke, Leia, and Han. All humans in our type system will have a name, so we
define the Human type to have a field called "name". This returns a String,
and we know that it is not null (since all Humans have a name), so we will
define the "name" field to be a non-nullable String. Using a shorthand notation
that we will use throughout the spec and documentation, we would describe the
human type as:

  1. ```graphql
  2. type Human {
  3.   name: String
  4. }
  5. ```

This shorthand is convenient for describing the basic shape of a type system;
the JavaScript implementation is more full-featured, and allows types and fields
to be documented. It also sets up the mapping between the type system and the
underlying data; for a test case in GraphQL.js, the underlying data is a
but in most cases the backing data will be accessed through some service, and
this type system layer will be responsible for mapping from types and fields to
that service.

A common pattern in many APIs, and indeed in GraphQL is to give objects an ID
that can be used to refetch the object. So let's add that to our Human type.
We'll also add a string for their home planet.

  1. ```graphql
  2. type Human {
  3.   id: String
  4.   name: String
  5.   homePlanet: String
  6. }
  7. ```

Since we're talking about the Star Wars trilogy, it would be useful to describe
the episodes in which each character appears. To do so, we'll first define an
enum, which lists the three episodes in the trilogy:

  1. ```graphql
  2. enum Episode {
  3.   NEWHOPE
  4.   EMPIRE
  5.   JEDI
  6. }
  7. ```

Now we want to add a field to Human describing what episodes they were in.
This will return a list of Episodes:

  1. ```graphql
  2. type Human {
  3.   id: String
  4.   name: String
  5.   appearsIn: [Episode]
  6.   homePlanet: String
  7. }
  8. ```

Now, let's introduce another type, Droid:

  1. ```graphql
  2. type Droid {
  3.   id: String
  4.   name: String
  5.   appearsIn: [Episode]
  6.   primaryFunction: String
  7. }
  8. ```

Now we have two types! Let's add a way of going between them: humans and droids
both have friends. But humans can be friends with both humans and droids. How do
we refer to either a human or a droid?

If we look, we note that there's common functionality between humans and droids;
they both have IDs, names, and episodes in which they appear. So we'll add an
interface, Character, and make both Human and Droid implement it. Once we
have that, we can add the friends field, that returns a list of Characters.

Our type system so far is:

  1. ```graphql
  2. enum Episode {
  3.   NEWHOPE
  4.   EMPIRE
  5.   JEDI
  6. }

  7. interface Character {
  8.   id: String
  9.   name: String
  10.   friends: [Character]
  11.   appearsIn: [Episode]
  12. }

  13. type Human implements Character {
  14.   id: String
  15.   name: String
  16.   friends: [Character]
  17.   appearsIn: [Episode]
  18.   homePlanet: String
  19. }

  20. type Droid implements Character {
  21.   id: String
  22.   name: String
  23.   friends: [Character]
  24.   appearsIn: [Episode]
  25.   primaryFunction: String
  26. }
  27. ```

One question we might ask, though, is whether any of those fields can return
null. By default, null is a permitted value for any type in GraphQL, since
fetching data to fulfill a GraphQL query often requires talking to different
services that may or may not be available. However, if the type system can
guarantee that a type is never null, then we can mark it as Non Null in the type
system. We indicate that in our shorthand by adding an "!" after the type. We
can update our type system to note that the id is never null.

Note that while in our current implementation, we can guarantee that more fields
are non-null (since our current implementation has hard-coded data), we didn't
mark them as non-null. One can imagine we would eventually replace our hardcoded
data with a backend service, which might not be perfectly reliable; by leaving
these fields as nullable, we allow ourselves the flexibility to eventually
return null to indicate a backend error, while also telling the client that the
error occurred.

  1. ```graphql
  2. enum Episode {
  3.   NEWHOPE
  4.   EMPIRE
  5.   JEDI
  6. }

  7. interface Character {
  8.   id: String!
  9.   name: String
  10.   friends: [Character]
  11.   appearsIn: [Episode]
  12. }

  13. type Human implements Character {
  14.   id: String!
  15.   name: String
  16.   friends: [Character]
  17.   appearsIn: [Episode]
  18.   homePlanet: String
  19. }

  20. type Droid implements Character {
  21.   id: String!
  22.   name: String
  23.   friends: [Character]
  24.   appearsIn: [Episode]
  25.   primaryFunction: String
  26. }
  27. ```

We're missing one last piece: an entry point into the type system.

When we define a schema, we define an object type that is the basis for all
query operations. The name of this type is Query by convention, and it
describes our public, top-level API. Our Query type for this example will look
like this:

  1. ```graphql
  2. type Query {
  3.   hero(episode: Episode): Character
  4.   human(id: String!): Human
  5.   droid(id: String!): Droid
  6. }
  7. ```

In this example, there are three top-level operations that can be done on our
schema:

- hero returns the Character who is the hero of the Star Wars trilogy; it
  takes an optional argument that allows us to fetch the hero of a specific
  episode instead.
- human accepts a non-null string as a query argument, a human's ID, and
  returns the human with that ID.
- droid does the same for droids.

These fields demonstrate another feature of the type system, the ability for a
field to specify arguments that configure their behavior.

When we package the whole type system together, defining the Query type above
as our entry point for queries, this creates a GraphQL Schema.

This example just scratched the surface of the type system. The specification
goes into more detail about this topic in the "Type System" section, and the
type directory in
GraphQL.js contains code implementing a specification-compliant GraphQL type
system.

Query Syntax


GraphQL queries declaratively describe what data the issuer wishes to fetch from
whoever is fulfilling the GraphQL query.

For our Star Wars example, the
file in the GraphQL.js repository contains a number of queries and responses.
That file is a test file that uses the schema discussed above and a set of
sample data, located in
This test file can be run to exercise the reference implementation.

An example query on the above schema would be:

  1. ```graphql
  2. query HeroNameQuery {
  3.   hero {
  4.     name
  5.   }
  6. }
  7. ```

The initial line, query HeroNameQuery, defines a query with the operation name
HeroNameQuery that starts with the schema's root query type; in this case,
Query. As defined above, Query has a hero field that returns a
Character, so we'll query for that. Character then has a name field that
returns a String, so we query for that, completing our query. The result of
this query would then be:

  1. ``` json
  2. {
  3.   "hero": {
  4.     "name": "R2-D2"
  5.   }
  6. }
  7. ```

Specifying the query keyword and an operation name is only required when a
GraphQL document defines multiple operations. We therefore could have written
the previous query with the query shorthand:

  1. ```graphql
  2. {
  3.   hero {
  4.     name
  5.   }
  6. }
  7. ```

Assuming that the backing data for the GraphQL server identified R2-D2 as the
hero. The response continues to vary based on the request; if we asked for
R2-D2's ID and friends with this query:

  1. ```graphql
  2. query HeroNameAndFriendsQuery {
  3.   hero {
  4.     id
  5.     name
  6.     friends {
  7.       id
  8.       name
  9.     }
  10.   }
  11. }
  12. ```

then we'll get back a response like this:

  1. ``` json
  2. {
  3.   "hero": {
  4.     "id": "2001",
  5.     "name": "R2-D2",
  6.     "friends": [
  7.       {
  8.         "id": "1000",
  9.         "name": "Luke Skywalker"
  10.       },
  11.       {
  12.         "id": "1002",
  13.         "name": "Han Solo"
  14.       },
  15.       {
  16.         "id": "1003",
  17.         "name": "Leia Organa"
  18.       }
  19.     ]
  20.   }
  21. }
  22. ```

One of the key aspects of GraphQL is its ability to nest queries. In the above
query, we asked for R2-D2's friends, but we can ask for more information about
each of those objects. So let's construct a query that asks for R2-D2's friends,
gets their name and episode appearances, then asks for each of _their_ friends.

  1. ```graphql
  2. query NestedQuery {
  3.   hero {
  4.     name
  5.     friends {
  6.       name
  7.       appearsIn
  8.       friends {
  9.         name
  10.       }
  11.     }
  12.   }
  13. }
  14. ```

which will give us the nested response

  1. ``` json
  2. {
  3.   "hero": {
  4.     "name": "R2-D2",
  5.     "friends": [
  6.       {
  7.         "name": "Luke Skywalker",
  8.         "appearsIn": ["NEWHOPE", "EMPIRE", "JEDI"],
  9.         "friends": [
  10.           { "name": "Han Solo" },
  11.           { "name": "Leia Organa" },
  12.           { "name": "C-3PO" },
  13.           { "name": "R2-D2" }
  14.         ]
  15.       },
  16.       {
  17.         "name": "Han Solo",
  18.         "appearsIn": ["NEWHOPE", "EMPIRE", "JEDI"],
  19.         "friends": [
  20.           { "name": "Luke Skywalker" },
  21.           { "name": "Leia Organa" },
  22.           { "name": "R2-D2" }
  23.         ]
  24.       },
  25.       {
  26.         "name": "Leia Organa",
  27.         "appearsIn": ["NEWHOPE", "EMPIRE", "JEDI"],
  28.         "friends": [
  29.           { "name": "Luke Skywalker" },
  30.           { "name": "Han Solo" },
  31.           { "name": "C-3PO" },
  32.           { "name": "R2-D2" }
  33.         ]
  34.       }
  35.     ]
  36.   }
  37. }
  38. ```

The Query type above defined a way to fetch a human given their ID. We can use
it by hard-coding the ID in the query:

  1. ```graphql
  2. query FetchLukeQuery {
  3.   human(id: "1000") {
  4.     name
  5.   }
  6. }
  7. ```

to get

  1. ``` json
  2. {
  3.   "human": {
  4.     "name": "Luke Skywalker"
  5.   }
  6. }
  7. ```

Alternately, we could have defined the query to have a query parameter:

  1. ```graphql
  2. query FetchSomeIDQuery($someId: String!) {
  3.   human(id: $someId) {
  4.     name
  5.   }
  6. }
  7. ```

This query is now parameterized by $someId; to run it, we must provide that
ID. If we ran it with $someId set to "1000", we would get Luke; set to "1002",
we would get Han. If we passed an invalid ID here, we would get null back for
the human, indicating that no such object exists.

Notice that the key in the response is the name of the field, by default. It is
sometimes useful to change this key, for clarity or to avoid key collisions when
fetching the same field with different arguments.

We can do that with field aliases, as demonstrated in this query:

  1. ```graphql
  2. query FetchLukeAliased {
  3.   luke: human(id: "1000") {
  4.     name
  5.   }
  6. }
  7. ```

We aliased the result of the human field to the key luke. Now the response
is:

  1. ``` json
  2. {
  3.   "luke": {
  4.     "name": "Luke Skywalker"
  5.   }
  6. }
  7. ```

Notice the key is "luke" and not "human", as it was in our previous example
where we did not use the alias.

This is particularly useful if we want to use the same field twice with
different arguments, as in the following query:

  1. ```graphql
  2. query FetchLukeAndLeiaAliased {
  3.   luke: human(id: "1000") {
  4.     name
  5.   }
  6.   leia: human(id: "1003") {
  7.     name
  8.   }
  9. }
  10. ```

We aliased the result of the first human field to the key luke, and the
second to leia. So the result will be:

  1. ``` json
  2. {
  3.   "luke": {
  4.     "name": "Luke Skywalker"
  5.   },
  6.   "leia": {
  7.     "name": "Leia Organa"
  8.   }
  9. }
  10. ```

Now imagine we wanted to ask for Luke and Leia's home planets. We could do so
with this query:

  1. ```graphql
  2. query DuplicateFields {
  3.   luke: human(id: "1000") {
  4.     name
  5.     homePlanet
  6.   }
  7.   leia: human(id: "1003") {
  8.     name
  9.     homePlanet
  10.   }
  11. }
  12. ```

but we can already see that this could get unwieldy, since we have to add new
fields to both parts of the query. Instead, we can extract out the common fields
into a fragment, and include the fragment in the query, like this:

  1. ```graphql
  2. query UseFragment {
  3.   luke: human(id: "1000") {
  4.     ...HumanFragment
  5.   }
  6.   leia: human(id: "1003") {
  7.     ...HumanFragment
  8.   }
  9. }

  10. fragment HumanFragment on Human {
  11.   name
  12.   homePlanet
  13. }
  14. ```

Both of those queries give this result:

  1. ``` json
  2. {
  3.   "luke": {
  4.     "name": "Luke Skywalker",
  5.     "homePlanet": "Tatooine"
  6.   },
  7.   "leia": {
  8.     "name": "Leia Organa",
  9.     "homePlanet": "Alderaan"
  10.   }
  11. }
  12. ```

The UseFragment and DuplicateFields queries will both get the same result,
but UseFragment is less verbose; if we wanted to add more fields, we could add
it to the common fragment rather than copying it into multiple places.

We defined the type system above, so we know the type of each object in the
output; the query can ask for that type using the special field __typename,
defined on every object.

  1. ```graphql
  2. query CheckTypeOfR2 {
  3.   hero {
  4.     __typename
  5.     name
  6.   }
  7. }
  8. ```

Since R2-D2 is a droid, this will return

  1. ``` json
  2. {
  3.   "hero": {
  4.     "__typename": "Droid",
  5.     "name": "R2-D2"
  6.   }
  7. }
  8. ```

This was particularly useful because hero was defined to return a Character,
which is an interface; we might want to know what concrete type was actually
returned. If we instead asked for the hero of Episode V:

  1. ```graphql
  2. query CheckTypeOfLuke {
  3.   hero(episode: EMPIRE) {
  4.     __typename
  5.     name
  6.   }
  7. }
  8. ```

We would find that it was Luke, who is a Human:

  1. ``` json
  2. {
  3.   "hero": {
  4.     "__typename": "Human",
  5.     "name": "Luke Skywalker"
  6.   }
  7. }
  8. ```

As with the type system, this example just scratched the surface of the query
language. The specification goes into more detail about this topic in the
"Language" section, and the
directory in GraphQL.js contains code implementing a specification-compliant
GraphQL query language parser and lexer.

Validation


By using the type system, it can be predetermined whether a GraphQL query is
valid or not. This allows servers and clients to effectively inform developers
when an invalid query has been created, without having to rely on runtime
checks.

For our Star Wars example, the file
contains a number of demonstrations of invalid operations, and is a test file
that can be run to exercise the reference implementation's validator.

To start, let's take a complex valid query. This is the NestedQuery example
from the above section, but with the duplicated fields factored out into a
fragment:

  1. ```graphql
  2. query NestedQueryWithFragment {
  3.   hero {
  4.     ...NameAndAppearances
  5.     friends {
  6.       ...NameAndAppearances
  7.       friends {
  8.         ...NameAndAppearances
  9.       }
  10.     }
  11.   }
  12. }

  13. fragment NameAndAppearances on Character {
  14.   name
  15.   appearsIn
  16. }
  17. ```

And this query is valid. Let's take a look at some invalid queries!

When we query for fields, we have to query for a field that exists on the given
type. So as hero returns a Character, we have to query for a field on
Character. That type does not have a favoriteSpaceship field, so this query:

  1. ```graphql
  2. # INVALID: favoriteSpaceship does not exist on Character
  3. query HeroSpaceshipQuery {
  4.   hero {
  5.     favoriteSpaceship
  6.   }
  7. }
  8. ```

is invalid.

Whenever we query for a field and it returns something other than a scalar or an
enum, we need to specify what data we want to get back from the field. Hero
returns a Character, and we've been requesting fields like name and
appearsIn on it; if we omit that, the query will not be valid:

  1. ```graphql
  2. # INVALID: hero is not a scalar, so fields are needed
  3. query HeroNoFieldsQuery {
  4.   hero
  5. }
  6. ```

Similarly, if a field is a scalar, it doesn't make sense to query for additional
fields on it, and doing so will make the query invalid:

  1. ```graphql
  2. # INVALID: name is a scalar, so fields are not permitted
  3. query HeroFieldsOnScalarQuery {
  4.   hero {
  5.     name {
  6.       firstCharacterOfName
  7.     }
  8.   }
  9. }
  10. ```

Earlier, it was noted that a query can only query for fields on the type in
question; when we query for hero which returns a Character, we can only
query for fields that exist on Character. What happens if we want to query for
R2-D2s primary function, though?

  1. ```graphql
  2. # INVALID: primaryFunction does not exist on Character
  3. query DroidFieldOnCharacter {
  4.   hero {
  5.     name
  6.     primaryFunction
  7.   }
  8. }
  9. ```

That query is invalid, because primaryFunction is not a field on Character.
We want some way of indicating that we wish to fetch primaryFunction if the
Character is a Droid, and to ignore that field otherwise. We can use the
fragments we introduced earlier to do this. By setting up a fragment defined on
Droid and including it, we ensure that we only query for primaryFunction
where it is defined.

  1. ```graphql
  2. query DroidFieldInFragment {
  3.   hero {
  4.     name
  5.     ...DroidFields
  6.   }
  7. }

  8. fragment DroidFields on Droid {
  9.   primaryFunction
  10. }
  11. ```

This query is valid, but it's a bit verbose; named fragments were valuable above
when we used them multiple times, but we're only using this one once. Instead of
using a named fragment, we can use an inline fragment; this still allows us to
indicate the type we are querying on, but without naming a separate fragment:

  1. ```graphql
  2. query DroidFieldInInlineFragment {
  3.   hero {
  4.     name
  5.     ... on Droid {
  6.       primaryFunction
  7.     }
  8.   }
  9. }
  10. ```

This has just scratched the surface of the validation system; there are a number
of validation rules in place to ensure that a GraphQL query is semantically
meaningful. The specification goes into more detail about this topic in the
"Validation" section, and the
directory in GraphQL.js contains code implementing a specification-compliant
GraphQL validator.

Introspection


It's often useful to ask a GraphQL schema for information about what queries it
supports. GraphQL allows us to do so using the introspection system!

For our Star Wars example, the file
contains a number of queries demonstrating the introspection system, and is a
test file that can be run to exercise the reference implementation's
introspection system.

We designed the type system, so we know what types are available, but if we
didn't, we can ask GraphQL, by querying the __schema field, always available
on the root type of a Query. Let's do so now, and ask what types are available.

  1. ```graphql
  2. query IntrospectionTypeQuery {
  3.   __schema {
  4.     types {
  5.       name
  6.     }
  7.   }
  8. }
  9. ```

and we get back:

  1. ``` json
  2. {
  3.   "__schema": {
  4.     "types": [
  5.       {
  6.         "name": "Query"
  7.       },
  8.       {
  9.         "name": "Character"
  10.       },
  11.       {
  12.         "name": "Human"
  13.       },
  14.       {
  15.         "name": "String"
  16.       },
  17.       {
  18.         "name": "Episode"
  19.       },
  20.       {
  21.         "name": "Droid"
  22.       },
  23.       {
  24.         "name": "__Schema"
  25.       },
  26.       {
  27.         "name": "__Type"
  28.       },
  29.       {
  30.         "name": "__TypeKind"
  31.       },
  32.       {
  33.         "name": "Boolean"
  34.       },
  35.       {
  36.         "name": "__Field"
  37.       },
  38.       {
  39.         "name": "__InputValue"
  40.       },
  41.       {
  42.         "name": "__EnumValue"
  43.       },
  44.       {
  45.         "name": "__Directive"
  46.       }
  47.     ]
  48.   }
  49. }
  50. ```

Wow, that's a lot of types! What are they? Let's group them:

- Query, Character, Human, Episode, Droid - These are the ones that we
  defined in our type system.
- String, Boolean - These are built-in scalars that the type system
  provided.
- __Schema, __Type, __TypeKind, __Field, __InputValue,
  __EnumValue, __Directive - These all are preceded with a double
  underscore, indicating that they are part of the introspection system.

Now, let's try and figure out a good place to start exploring what queries are
available. When we designed our type system, we specified what type all queries
would start at; let's ask the introspection system about that!

  1. ```graphql
  2. query IntrospectionQueryTypeQuery {
  3.   __schema {
  4.     queryType {
  5.       name
  6.     }
  7.   }
  8. }
  9. ```

and we get back:

  1. ``` json
  2. {
  3.   "__schema": {
  4.     "queryType": {
  5.       "name": "Query"
  6.     }
  7.   }
  8. }
  9. ```

And that matches what we said in the type system section, that the Query type
is where we will start! Note that the naming here was just by convention; we
could have named our Query type anything else, and it still would have been
returned here if we had specified it as the starting type for queries. Naming it
Query, though, is a useful convention.

It is often useful to examine one specific type. Let's take a look at the
Droid type:

  1. ```graphql
  2. query IntrospectionDroidTypeQuery {
  3.   __type(name: "Droid") {
  4.     name
  5.   }
  6. }
  7. ```

and we get back:

  1. ``` json
  2. {
  3.   "__type": {
  4.     "name": "Droid"
  5.   }
  6. }
  7. ```

What if we want to know more about Droid, though? For example, is it an
interface or an object?

  1. ```graphql
  2. query IntrospectionDroidKindQuery {
  3.   __type(name: "Droid") {
  4.     name
  5.     kind
  6.   }
  7. }
  8. ```

and we get back:

  1. ``` json
  2. {
  3.   "__type": {
  4.     "name": "Droid",
  5.     "kind": "OBJECT"
  6.   }
  7. }
  8. ```

kind returns a __TypeKind enum, one of whose values is OBJECT. If we asked
about Character instead:

  1. ```graphql
  2. query IntrospectionCharacterKindQuery {
  3.   __type(name: "Character") {
  4.     name
  5.     kind
  6.   }
  7. }
  8. ```

and we get back:

  1. ``` json
  2. {
  3.   "__type": {
  4.     "name": "Character",
  5.     "kind": "INTERFACE"
  6.   }
  7. }
  8. ```

We'd find that it is an interface.

It's useful for an object to know what fields are available, so let's ask the
introspection system about Droid:

  1. ```graphql
  2. query IntrospectionDroidFieldsQuery {
  3.   __type(name: "Droid") {
  4.     name
  5.     fields {
  6.       name
  7.       type {
  8.         name
  9.         kind
  10.       }
  11.     }
  12.   }
  13. }
  14. ```

and we get back:

  1. ``` json
  2. {
  3.   "__type": {
  4.     "name": "Droid",
  5.     "fields": [
  6.       {
  7.         "name": "id",
  8.         "type": {
  9.           "name": null,
  10.           "kind": "NON_NULL"
  11.         }
  12.       },
  13.       {
  14.         "name": "name",
  15.         "type": {
  16.           "name": "String",
  17.           "kind": "SCALAR"
  18.         }
  19.       },
  20.       {
  21.         "name": "friends",
  22.         "type": {
  23.           "name": null,
  24.           "kind": "LIST"
  25.         }
  26.       },
  27.       {
  28.         "name": "appearsIn",
  29.         "type": {
  30.           "name": null,
  31.           "kind": "LIST"
  32.         }
  33.       },
  34.       {
  35.         "name": "primaryFunction",
  36.         "type": {
  37.           "name": "String",
  38.           "kind": "SCALAR"
  39.         }
  40.       }
  41.     ]
  42.   }
  43. }
  44. ```

Those are our fields that we defined on Droid!

id looks a bit weird there, it has no name for the type. That's because it's a
"wrapper" type of kind NON_NULL. If we queried for ofType on that field's
type, we would find the String type there, telling us that this is a non-null
String.

Similarly, both friends and appearsIn have no name, since they are the
LIST wrapper type. We can query for ofType on those types, which will tell
us what these are lists of.

  1. ```graphql
  2. query IntrospectionDroidWrappedFieldsQuery {
  3.   __type(name: "Droid") {
  4.     name
  5.     fields {
  6.       name
  7.       type {
  8.         name
  9.         kind
  10.         ofType {
  11.           name
  12.           kind
  13.         }
  14.       }
  15.     }
  16.   }
  17. }
  18. ```

and we get back:

  1. ``` json
  2. {
  3.   "__type": {
  4.     "name": "Droid",
  5.     "fields": [
  6.       {
  7.         "name": "id",
  8.         "type": {
  9.           "name": null,
  10.           "kind": "NON_NULL",
  11.           "ofType": {
  12.             "name": "String",
  13.             "kind": "SCALAR"
  14.           }
  15.         }
  16.       },
  17.       {
  18.         "name": "name",
  19.         "type": {
  20.           "name": "String",
  21.           "kind": "SCALAR",
  22.           "ofType": null
  23.         }
  24.       },
  25.       {
  26.         "name": "friends",
  27.         "type": {
  28.           "name": null,
  29.           "kind": "LIST",
  30.           "ofType": {
  31.             "name": "Character",
  32.             "kind": "INTERFACE"
  33.           }
  34.         }
  35.       },
  36.       {
  37.         "name": "appearsIn",
  38.         "type": {
  39.           "name": null,
  40.           "kind": "LIST",
  41.           "ofType": {
  42.             "name": "Episode",
  43.             "kind": "ENUM"
  44.           }
  45.         }
  46.       },
  47.       {
  48.         "name": "primaryFunction",
  49.         "type": {
  50.           "name": "String",
  51.           "kind": "SCALAR",
  52.           "ofType": null
  53.         }
  54.       }
  55.     ]
  56.   }
  57. }
  58. ```

Let's end with a feature of the introspection system particularly useful for
tooling; let's ask the system for documentation!

  1. ```graphql
  2. query IntrospectionDroidDescriptionQuery {
  3.   __type(name: "Droid") {
  4.     name
  5.     description
  6.   }
  7. }
  8. ```

yields

  1. ``` json
  2. {
  3.   "__type": {
  4.     "name": "Droid",
  5.     "description": "A mechanical creature in the Star Wars universe."
  6.   }
  7. }
  8. ```

So we can access the documentation about the type system using introspection,
and create documentation browsers, or rich IDE experiences.

This has just scratched the surface of the introspection system; we can query
for enum values, what interfaces a type implements, and more. We can even
introspect on the introspection system itself. The specification goes into more
detail about this topic in the "Introspection" section, and the
file in GraphQL.js contains code implementing a specification-compliant GraphQL
query introspection system.

Additional Content


This README walked through the GraphQL.js reference implementation's type
system, query execution, validation, and introspection systems. There's more in
both GraphQL.js and specification,
including a description and implementation for executing queries, how to format
a response, explaining how a type system maps to an underlying implementation,
and how to format a GraphQL response, as well as the grammar for GraphQL.

Contributing to this repo


This repository is managed by EasyCLA. Project participants must sign the free
before making a contribution. You only need to do this one time, and it can be
signed by
their employers.

To initiate the signature process please open a PR against this repo. The
EasyCLA bot will block the merge if we still need a membership agreement from
you.

You can find
If you have issues, please email

If your company benefits from GraphQL and you would like to provide essential
financial support for the systems and people that power our community, please
also consider membership in the