<!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements.  See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership.  The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
-->

# Language

Clients use the GraphQL query language to make requests to a GraphQL service. We
refer to these _request_ sources as documents. A document may contain operations
(queries, mutations, and subscriptions) as well as fragments, a common unit of
composition allowing for data requirement reuse.

A GraphQL document is defined as a syntactic grammar where terminal symbols are
tokens (indivisible lexical units). These tokens are defined in a lexical
grammar which matches patterns of source characters. In this document, syntactic
grammar productions are distinguished with a colon `:` while lexical grammar
productions are distinguished with a double-colon `::`.

The source text of a GraphQL document must be a sequence of {SourceCharacter}.
The character sequence must be described by a sequence of {Token} and {Ignored}
lexical grammars. The lexical token sequence, omitting {Ignored}, must be
described by a single {Document} syntactic grammar.

Note: See [Appendix A](#sec-Appendix-Notation-Conventions) for more information
about the lexical and syntactic grammar and other notational conventions used
throughout this document.

**Lexical Analysis & Syntactic Parse**

The source text of a GraphQL document is first converted into a sequence of
lexical tokens ({Token}) and ignored tokens ({Ignored}). The source text is
scanned from left to right, repeatedly taking the next possible sequence of code
points allowed by the lexical grammar productions as the next token. This
sequence of lexical tokens is then scanned from left to right to produce an
abstract syntax tree (AST) according to the {Document} syntactic grammar.

Lexical grammar productions in this document use _lookahead restrictions_ to
remove ambiguity and ensure a single valid lexical analysis. A lexical token is
only valid if not followed by a character in its lookahead restriction.

For example, an {IntValue} has the restriction {[lookahead != Digit]}, so cannot
be followed by a {Digit}. Because of this, the sequence {`123`} cannot represent
the tokens ({`12`}, {`3`}) since {`12`} is followed by the {Digit} {`3`} and so
must only represent a single token. Use {Whitespace} or other {Ignored} between
characters to represent multiple tokens.

Note: This typically has the same behavior as a
"[maximal munch](https://en.wikipedia.org/wiki/Maximal_munch)" longest possible
match, however some lookahead restrictions include additional constraints.

## Source Text

SourceCharacter :: "Any Unicode scalar value"

GraphQL documents are interpreted from a source text, which is a sequence of
{SourceCharacter}, each {SourceCharacter} being a _Unicode scalar value_ which
may be any Unicode code point from U+0000 to U+D7FF or U+E000 to U+10FFFF
(informally referred to as _"characters"_ through most of this specification).

A GraphQL document may be expressed only in the ASCII range to be as widely
compatible with as many existing tools, languages, and serialization formats as
possible and avoid display issues in text editors and source control. Non-ASCII
Unicode scalar values may appear within {StringValue} and {Comment}.

Note: An implementation which uses _UTF-16_ to represent GraphQL documents in
memory (for example, JavaScript or Java) may encounter a _surrogate pair_. This
encodes one _supplementary code point_ and is a single valid source character,
however an unpaired _surrogate code point_ is not a valid source character.

### White Space

Whitespace ::

- "Horizontal Tab (U+0009)"
- "Space (U+0020)"

Whitespace is used to improve legibility of source text and separates other
tokens. Any amount of whitespace may appear before or after any token.
Whitespace between tokens is not significant to the semantic meaning of a
GraphQL document, however whitespace characters may appear within a {String} or
{Comment} token.

Note: GraphQL intentionally does not consider Unicode "Zs" category characters
as whitespace, avoiding misinterpretation by text editors and source control
tools.

### Line Terminators

LineTerminator ::

- "New Line (U+000A)"
- "Carriage Return (U+000D)" [lookahead != "New Line (U+000A)"]
- "Carriage Return (U+000D)" "New Line (U+000A)"

Like whitespace, line terminators are used to improve the legibility of source
text and separate lexical tokens, any amount may appear before or after any
other token and have no significance to the semantic meaning of a GraphQL
Document.

Note: Any error reporting which provides the line number in the source of the
offending syntax should use the preceding amount of {LineTerminator} to produce
the line number.

### Comments

Comment :: `#` CommentChar\* [lookahead != CommentChar]

CommentChar :: SourceCharacter but not LineTerminator

GraphQL source documents may contain single-line comments, starting with the
{`#`} marker.

A comment may contain any {SourceCharacter} except {LineTerminator} so a comment
always consists of all {SourceCharacter} starting with the {`#`} character up to
but not including the {LineTerminator} (or end of the source).

Comments are {Ignored} like whitespace and may appear after any token, or before
a {LineTerminator}, and have no significance to the semantic meaning of a
GraphQL document.

### Insignificant Commas

Comma :: ,

Similar to whitespace and line terminators, commas ({`,`}) are used to improve
the legibility of source text and separate lexical tokens but are otherwise
syntactically and semantically insignificant within GraphQL documents.

Non-significant comma characters ensure that the absence or presence of a comma
does not meaningfully alter the interpreted syntax of the document, as this can
be a common user error in other languages. It also allows for the stylistic use
of either trailing commas or line terminators as list delimiters which are both
often desired for legibility and maintainability of source code.

### Lexical Tokens

Token ::

- Punctuator
- Name
- IntValue
- FloatValue
- StringValue

A GraphQL document is composed of several kinds of indivisible lexical tokens
defined here in a lexical grammar by patterns of source Unicode characters.
Lexical tokens may be separated by {Ignored} tokens.

Tokens are later used as terminal symbols in GraphQL syntactic grammar rules.

### Ignored Tokens

Ignored ::

- UnicodeBOM
- Whitespace
- LineTerminator
- Comment
- Comma

{Ignored} tokens are used to improve readability and provide separation between
lexical tokens, but are otherwise insignificant and not referenced in syntactic
grammar productions.

Any amount of {Ignored} may appear before and after every lexical token. No
ignored regions of a source document are significant, however {SourceCharacter}
which appear in {Ignored} may also appear within a lexical {Token} in a
significant way, for example a {StringValue} may contain whitespace characters.
No {Ignored} may appear _within_ a {Token}, for example no whitespace characters
are permitted between the characters defining a {FloatValue}.

**Byte Order Mark**

UnicodeBOM :: "Byte Order Mark (U+FEFF)"

The _Byte Order Mark_ is a special Unicode code point which may appear at the
beginning of a file which programs may use to determine the fact that the text
stream is Unicode, and what specific encoding has been used. As files are often
concatenated, a _Byte Order Mark_ may appear before or after any lexical token
and is {Ignored}.

### Punctuators

Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | }

GraphQL documents include punctuation in order to describe structure. GraphQL is
a data description language and not a programming language; therefore, GraphQL
lacks the punctuation often used to describe mathematical expressions.

### Names

Name ::

- NameStart NameContinue\* [lookahead != NameContinue]

NameStart ::

- Letter
- `_`

NameContinue ::

- Letter
- Digit
- `_`

Letter :: one of

- `A` `B` `C` `D` `E` `F` `G` `H` `I` `J` `K` `L` `M`
- `N` `O` `P` `Q` `R` `S` `T` `U` `V` `W` `X` `Y` `Z`
- `a` `b` `c` `d` `e` `f` `g` `h` `i` `j` `k` `l` `m`
- `n` `o` `p` `q` `r` `s` `t` `u` `v` `w` `x` `y` `z`

Digit :: one of

- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`

GraphQL documents are full of named things: operations, fields, arguments,
types, directives, fragments, and variables. All names must follow the same
grammatical form.

Names in GraphQL are case-sensitive. That is to say `name`, `Name`, and `NAME`
all refer to different names. Underscores are significant, which means
`other_name` and `othername` are two different names.

A {Name} must not be followed by a {NameContinue}. In other words, a {Name}
token is always the longest possible valid sequence. The source characters
{`a1`} cannot be interpreted as two tokens since {`a`} is followed by the
{NameContinue} {`1`}.

Note: Names in GraphQL are limited to the Latin <acronym>ASCII</acronym> subset
of {SourceCharacter} in order to support interoperation with as many other
systems as possible.

**Reserved Names**

Any {Name} within a GraphQL type system must not start with two underscores
{"\_\_"} unless it is part of the [introspection system](#sec-Introspection) as
defined by this specification.

## Descriptions

Description : StringValue

Documentation is a first-class feature of GraphQL by including written
descriptions on all named definitions in executable {Document} and GraphQL type
systems, which is also made available via introspection ensuring the
documentation of a GraphQL service remains consistent with its capabilities (see
[Type System Descriptions](#sec-Type-System-Descriptions)).

GraphQL descriptions are provided as Markdown (as specified by
[CommonMark](https://commonmark.org/)). Description strings (often
{BlockString}) occur immediately before the definition they describe.

Descriptions in GraphQL executable documents are purely for documentation
purposes. They MUST NOT affect the execution, validation, or response of a
GraphQL document. It is safe to remove all descriptions and comments from
executable documents without changing their behavior or results.

This is an example of a well-described operation:

```graphql example
"""
Request the current status of a time machine and its operator.
You can also check the status for a particular year.
**Warning:** certain years may trigger an anomaly in the space-time continuum.
"""
query GetTimeMachineStatus(
  "The unique serial number of the time machine to inspect."
  $machineId: ID!
  "The year to check the status for."
  $year: Int
) {
  timeMachine(id: $machineId) {
    ...TimeMachineDetails
    status(year: $year)
  }
}

"Details about a time machine and its operator."
fragment TimeMachineDetails on TimeMachine {
  id
  model
  lastMaintenance
  operator {
    name
    licenseLevel
  }
}
```

## Document

Document : Definition+

Definition :

- ExecutableDefinition
- TypeSystemDefinitionOrExtension

ExecutableDocument : ExecutableDefinition+

ExecutableDefinition :

- OperationDefinition
- FragmentDefinition

A GraphQL document describes a complete file or request string operated on by a
GraphQL service or client. A document contains multiple definitions, either
executable or representative of a GraphQL type system.

Documents are only executable by a GraphQL service if they are
{ExecutableDocument} and contain at least one {OperationDefinition}. A Document
which contains {TypeSystemDefinitionOrExtension} must not be executed; GraphQL
execution services which receive a Document containing these should return a
descriptive error.

GraphQL services which only seek to execute GraphQL requests and not construct a
new GraphQL schema may choose to only permit {ExecutableDocument}.

Documents which do not contain {OperationDefinition} or do contain
{TypeSystemDefinitionOrExtension} may still be parsed and validated to allow
client tools to represent many GraphQL uses which may appear across many
individual files.

If a Document contains only one operation, that operation may be unnamed. If
that operation is a query without variables or directives then it may also be
represented in the shorthand form, omitting both the {`query`} keyword as well
as the operation name. Otherwise, if a GraphQL document contains multiple
operations, each operation must be named. When submitting a Document with
multiple operations to a GraphQL service, the name of the desired operation to
be executed must also be provided.

## Operations

OperationDefinition :

- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet
- SelectionSet

OperationType : one of `query` `mutation` `subscription`

There are three types of operations that GraphQL models:

- query - a read-only fetch.
- mutation - a write followed by a fetch.
- subscription - a long-lived request that fetches data in response to a
  sequence of events over time.

Each operation is represented by an optional operation name and a _selection
set_.

For example, this mutation operation might "like" a story and then retrieve the
new number of likes:

```graphql example
"""
Mark story 12345 as "liked"
and return the updated number of likes on the story
"""
mutation {
  likeStory(storyID: 12345) {
    story {
      likeCount
    }
  }
}
```

**Query Shorthand**

If a document contains only one operation and that operation is a query which
defines no variables and has no directives applied to it then that operation may
be represented in a shorthand form which omits the {`query`} keyword and
operation name.

For example, this unnamed query operation is written via query shorthand.

```graphql example
{
  field
}
```

Descriptions are not permitted on query shorthand.

Note: many examples below will use the query shorthand syntax.

## Selection Sets

SelectionSet : { Selection+ }

Selection :

- Field
- FragmentSpread
- InlineFragment

An operation selects the set of information it needs, and will receive exactly
that information and nothing more, avoiding over-fetching and under-fetching
data.

:: A _selection set_ defines an ordered set of selections (fields, fragment
spreads and inline fragments) against an object, union or interface type.

```graphql example
{
  id
  firstName
  lastName
}
```

In this query operation, the `id`, `firstName`, and `lastName` fields form a
_selection set_. Selection sets may also contain fragment references.

## Fields

Field : Alias? Name Arguments? Directives? SelectionSet?

A _selection set_ is primarily composed of fields. A field describes one
discrete piece of information available to request within a selection set.

Some fields describe complex data or relationships to other data. In order to
further explore this data, a field may itself contain a selection set, allowing
for deeply nested requests. All GraphQL operations must specify their selections
down to fields which return scalar values to ensure an unambiguously shaped
response.

For example, this operation selects fields of complex data and relationships
down to scalar values.

```graphql example
{
  me {
    id
    firstName
    lastName
    birthday {
      month
      day
    }
    friends {
      name
    }
  }
}
```

Fields in the top-level _selection set_ of an operation often represent some
information that is globally accessible to your application and its current
viewer. Some typical examples of these top fields include references to a
current logged-in viewer, or accessing certain types of data referenced by a
unique identifier.

```graphql example
# `me` could represent the currently logged in viewer.
{
  me {
    name
  }
}

# `user` represents one of many users in a graph of data, referred to by a
# unique identifier.
{
  user(id: 4) {
    name
  }
}
```

## Arguments

Arguments[Const] : ( Argument[?Const]+ )

Argument[Const] : Name : Value[?Const]

Fields are conceptually functions which return values, and occasionally accept
arguments which alter their behavior. These arguments often map directly to
function arguments within a GraphQL service's implementation.

In this example, we want to query a specific user (requested via the `id`
argument) and their profile picture of a specific `size`:

```graphql example
{
  user(id: 4) {
    id
    name
    profilePic(size: 100)
  }
}
```

Many arguments can exist for a given field:

```graphql example
{
  user(id: 4) {
    id
    name
    profilePic(width: 100, height: 50)
  }
}
```

**Arguments Are Unordered**

Arguments may be provided in any syntactic order and maintain identical semantic
meaning.

These two operations are semantically identical:

```graphql example
{
  picture(width: 200, height: 100)
}
```

```graphql example
{
  picture(height: 100, width: 200)
}
```

## Field Alias

Alias : Name :

:: A _response name_ is the key in the response object which correlates with a
field's result. By default the response name will use the field's name; however,
you can define a different response name by specifying an alias.

In this example, we can fetch two profile pictures of different sizes and ensure
the resulting response object will not have duplicate keys:

```graphql example
{
  user(id: 4) {
    id
    name
    smallPic: profilePic(size: 64)
    bigPic: profilePic(size: 1024)
  }
}
```

which returns the result:

```json example
{
  "user": {
    "id": 4,
    "name": "Mark Zuckerberg",
    "smallPic": "https://cdn.site.io/pic-4-64.jpg",
    "bigPic": "https://cdn.site.io/pic-4-1024.jpg"
  }
}
```

The fields at the top level of an operation can also be given an alias:

```graphql example
{
  zuck: user(id: 4) {
    id
    name
  }
}
```

which returns the result:

```json example
{
  "zuck": {
    "id": 4,
    "name": "Mark Zuckerberg"
  }
}
```

## Fragments

FragmentSpread : ... FragmentName Directives?

FragmentDefinition : Description? fragment FragmentName TypeCondition
Directives? SelectionSet

FragmentName : Name but not `on`

Fragments are the primary unit of composition in GraphQL.

Fragments allow for the reuse of common repeated selections of fields, reducing
duplicated text in the document. Inline Fragments can be used directly within a
selection to condition upon a type condition when querying against an interface
or union.

For example, if we wanted to fetch some common information about mutual friends
as well as friends of some user:

```graphql example
query noFragments {
  user(id: 4) {
    friends(first: 10) {
      id
      name
      profilePic(size: 50)
    }
    mutualFriends(first: 10) {
      id
      name
      profilePic(size: 50)
    }
  }
}
```

The repeated fields could be extracted into a fragment and composed by a parent
fragment or operation.

```graphql example
query withFragments {
  user(id: 4) {
    friends(first: 10) {
      ...friendFields
    }
    mutualFriends(first: 10) {
      ...friendFields
    }
  }
}

"Common fields for a user's friends."
fragment friendFields on User {
  id
  name
  profilePic(size: 50)
}
```

Fragments are consumed by using the spread operator (`...`). All fields selected
by the fragment will be added to the field selection at the same level as the
fragment invocation. This happens through multiple levels of fragment spreads.

For example:

```graphql example
query withNestedFragments {
  user(id: 4) {
    friends(first: 10) {
      ...friendFields
    }
    mutualFriends(first: 10) {
      ...friendFields
    }
  }
}

fragment friendFields on User {
  id
  name
  ...standardProfilePic
}

fragment standardProfilePic on User {
  profilePic(size: 50)
}
```

The operations `noFragments`, `withFragments`, and `withNestedFragments` all
produce the same response object.

### Type Conditions

TypeCondition : on NamedType

Fragments must specify the type they apply to. In this example, `friendFields`
can be used in the context of querying a `User`.

Fragments cannot be specified on any input value (scalar, enumeration, or input
object).

Fragments can be specified on object types, interfaces, and unions.

Selections within fragments only return values when the concrete type of the
object it is operating on matches the type of the fragment.

For example in this operation using the Facebook data model:

```graphql example
query FragmentTyping {
  profiles(handles: ["zuck", "coca-cola"]) {
    handle
    ...userFragment
    ...pageFragment
  }
}

fragment userFragment on User {
  friends {
    count
  }
}

fragment pageFragment on Page {
  likers {
    count
  }
}
```

The `profiles` root field returns a list where each element could be a `Page` or
a `User`. When the object in the `profiles` result is a `User`, `friends` will
be present and `likers` will not. Conversely when the result is a `Page`,
`likers` will be present and `friends` will not.

```json example
{
  "profiles": [
    {
      "handle": "zuck",
      "friends": { "count": 1234 }
    },
    {
      "handle": "coca-cola",
      "likers": { "count": 90234512 }
    }
  ]
}
```

### Inline Fragments

InlineFragment : ... TypeCondition? Directives? SelectionSet

Fragments can also be defined inline within a _selection set_. This is useful
for conditionally including fields based on a type condition or applying a
directive to a selection set.

This feature of standard fragment inclusion was demonstrated in the
`query FragmentTyping` example above. We could accomplish the same thing using
inline fragments.

```graphql example
query inlineFragmentTyping {
  profiles(handles: ["zuck", "coca-cola"]) {
    handle
    ... on User {
      friends {
        count
      }
    }
    ... on Page {
      likers {
        count
      }
    }
  }
}
```

Inline fragments may also be used to apply a directive to a group of fields. If
the TypeCondition is omitted, an inline fragment is considered to be of the same
type as the enclosing context.

```graphql example
query inlineFragmentNoType($expandedInfo: Boolean) {
  user(handle: "zuck") {
    id
    name
    ... @include(if: $expandedInfo) {
      firstName
      lastName
      birthday
    }
  }
}
```

## Input Values

Value[Const] :

- [~Const] Variable
- IntValue
- FloatValue
- StringValue
- BooleanValue
- NullValue
- EnumValue
- ListValue[?Const]
- ObjectValue[?Const]

Field and directive arguments accept input values of various literal primitives;
input values can be scalars, enumeration values, lists, or input objects.

If not defined as constant (for example, in {DefaultValue}), input values can be
specified as a variable. List and inputs objects may also contain variables
(unless defined to be constant).

### Int Value

IntValue :: IntegerPart [lookahead != {Digit, `.`, NameStart}]

IntegerPart ::

- NegativeSign? 0
- NegativeSign? NonZeroDigit Digit\*

NegativeSign :: -

NonZeroDigit :: Digit but not `0`

An {IntValue} is specified without a decimal point or exponent but may be
negative (e.g. {-123}). It must not have any leading {0}.

An {IntValue} must not be followed by a {Digit}. In other words, an {IntValue}
token is always the longest possible valid sequence. The source characters {12}
cannot be interpreted as two tokens since {1} is followed by the {Digit} {2}.
This also means the source {00} is invalid since it can neither be interpreted
as a single token nor two {0} tokens.

An {IntValue} must not be followed by a {`.`} or {NameStart}. If either {`.`} or
{ExponentIndicator} follows then the token must only be interpreted as a
possible {FloatValue}. No other {NameStart} character can follow. For example
the sequences `0x123` and `123L` have no valid lexical representations.

### Float Value

FloatValue ::

- IntegerPart FractionalPart ExponentPart [lookahead != {Digit, `.`, NameStart}]
- IntegerPart FractionalPart [lookahead != {Digit, `.`, NameStart}]
- IntegerPart ExponentPart [lookahead != {Digit, `.`, NameStart}]

FractionalPart :: . Digit+

ExponentPart :: ExponentIndicator Sign? Digit+

ExponentIndicator :: one of `e` `E`

Sign :: one of + -

A {FloatValue} includes either a decimal point (e.g. {1.0}) or an exponent (e.g.
{1e50}) or both (e.g. {6.0221413e23}) and may be negative. Like {IntValue}, it
also must not have any leading {0}.

A {FloatValue} must not be followed by a {Digit}. In other words, a {FloatValue}
token is always the longest possible valid sequence. The source characters
{1.23} cannot be interpreted as two tokens since {1.2} is followed by the
{Digit} {3}.

A {FloatValue} must not be followed by a {.}. For example, the sequence {1.23.4}
cannot be interpreted as two tokens ({1.2}, {3.4}).

A {FloatValue} must not be followed by a {NameStart}. For example the sequence
`0x1.2p3` has no valid lexical representation.

Note: The numeric literals {IntValue} and {FloatValue} both restrict being
immediately followed by a letter (or other {NameStart}) to reduce confusion or
unexpected behavior since GraphQL only supports decimal numbers.

### Boolean Value

BooleanValue : one of `true` `false`

The two keywords `true` and `false` represent the two boolean values.

### String Value

StringValue ::

- `""` [lookahead != `"`]
- `"` StringCharacter+ `"`
- BlockString

StringCharacter ::

- SourceCharacter but not `"` or `\` or LineTerminator
- `\u` EscapedUnicode
- `\` EscapedCharacter

EscapedUnicode ::

- `{` HexDigit+ `}`
- HexDigit HexDigit HexDigit HexDigit

HexDigit :: one of

- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`
- `A` `B` `C` `D` `E` `F`
- `a` `b` `c` `d` `e` `f`

EscapedCharacter :: one of `"` `\` `/` `b` `f` `n` `r` `t`

BlockString :: `"""` BlockStringCharacter\* `"""`

BlockStringCharacter ::

- SourceCharacter but not `"""` or `\"""`
- `\"""`

A {StringValue} is evaluated to a _Unicode text_ value, a sequence of _Unicode
scalar value_, by interpreting all escape sequences using the static semantics
defined below. Whitespace and other characters ignored between lexical tokens
are significant within a string value.

The empty string {`""`} must not be followed by another {`"`} otherwise it would
be interpreted as the beginning of a block string. As an example, the source
{`""""""`} can only be interpreted as a single empty block string and not three
empty strings.

**Escape Sequences**

In a single-quoted {StringValue}, any _Unicode scalar value_ may be expressed
using an escape sequence. GraphQL strings allow both C-style escape sequences
(for example `\n`) and two forms of Unicode escape sequences: one with a
fixed-width of 4 hexadecimal digits (for example `\u000A`) and one with a
variable-width most useful for representing a _supplementary character_ such as
an Emoji (for example `\u{1F4A9}`).

The hexadecimal number encoded by a Unicode escape sequence must describe a
_Unicode scalar value_, otherwise must result in a parse error. For example both
sources `"\uDEAD"` and `"\u{110000}"` should not be considered valid
{StringValue}.

Escape sequences are only meaningful within a single-quoted string. Within a
block string, they are simply that sequence of characters (for example
`"""\n"""` represents the _Unicode text_ [U+005C, U+006E]). Within a comment an
escape sequence is not a significant sequence of characters. They may not appear
elsewhere in a GraphQL document.

Since {StringCharacter} must not contain some code points directly (for example,
a {LineTerminator}), escape sequences must be used to represent them. All other
escape sequences are optional and unescaped non-ASCII Unicode characters are
allowed within strings. If using GraphQL within a system which only supports
ASCII, then escape sequences may be used to represent all Unicode characters
outside of the ASCII range.

For legacy reasons, a _supplementary character_ may be escaped by two
fixed-width unicode escape sequences forming a _surrogate pair_. For example the
input `"\uD83D\uDCA9"` is a valid {StringValue} which represents the same
_Unicode text_ as `"\u{1F4A9}"`. While this legacy form is allowed, it should be
avoided as a variable-width unicode escape sequence is a clearer way to encode
such code points.

When producing a {StringValue}, implementations should use escape sequences to
represent non-printable control characters (U+0000 to U+001F and U+007F to
U+009F). Other escape sequences are not necessary, however an implementation may
use escape sequences to represent any other range of code points (for example,
when producing ASCII-only output). If an implementation chooses to escape a
_supplementary character_, it should only use a variable-width unicode escape
sequence.

**Block Strings**

Block strings are sequences of characters wrapped in triple-quotes (`"""`).
Whitespace, line terminators, quote, and backslash characters may all be used
unescaped to enable verbatim text. Characters must all be valid
{SourceCharacter}.

Since block strings represent freeform text often used in indented positions,
the string value semantics of a block string excludes uniform indentation and
blank initial and trailing lines via {BlockStringValue()}.

For example, the following operation containing a block string:

```raw graphql example
mutation {
  sendEmail(message: """
    Hello,
      World!

    Yours,
      GraphQL.
  """)
}
```

Is identical to the standard quoted string:

```graphql example
mutation {
  sendEmail(message: "Hello,\n  World!\n\nYours,\n  GraphQL.")
}
```

Since block string values strip leading and trailing empty lines, there is no
single canonical printed block string for a given value. Because block strings
typically represent freeform text, it is considered easier to read if they begin
and end with an empty line.

```graphql example
"""
This starts with and ends with an empty line,
which makes it easier to read.
"""
```

```graphql counter-example
"""This does not start with or end with any empty lines,
which makes it a little harder to read."""
```

Note: If non-printable ASCII characters are needed in a string value, a standard
quoted string with appropriate escape sequences must be used instead of a block
string.

**Static Semantics**

:: A {StringValue} describes a _Unicode text_ value, which is a sequence of
_Unicode scalar value_.

These semantics describe how to apply the {StringValue} grammar to a source text
to evaluate a _Unicode text_. Errors encountered during this evaluation are
considered a failure to apply the {StringValue} grammar to a source and must
result in a parsing error.

StringValue :: `""`

- Return an empty sequence.

StringValue :: `"` StringCharacter+ `"`

- Return the _Unicode text_ by concatenating the evaluation of all
  {StringCharacter}.

StringCharacter :: SourceCharacter but not `"` or `\` or LineTerminator

- Return the _Unicode scalar value_ {SourceCharacter}.

StringCharacter :: `\u` EscapedUnicode

- Let {value} be the hexadecimal value represented by the sequence of {HexDigit}
  within {EscapedUnicode}.
- Assert: {value} is a within the _Unicode scalar value_ range (>= 0x0000 and <=
  0xD7FF or >= 0xE000 and <= 0x10FFFF).
- Return the _Unicode scalar value_ {value}.

StringCharacter :: `\u` HexDigit HexDigit HexDigit HexDigit `\u` HexDigit
HexDigit HexDigit HexDigit

- Let {leadingValue} be the hexadecimal value represented by the first sequence
  of {HexDigit}.
- Let {trailingValue} be the hexadecimal value represented by the second
  sequence of {HexDigit}.
- If {leadingValue} is >= 0xD800 and <= 0xDBFF (a _Leading Surrogate_):
  - Assert: {trailingValue} is >= 0xDC00 and <= 0xDFFF (a _Trailing Surrogate_).
  - Return ({leadingValue} - 0xD800) × 0x400 + ({trailingValue} - 0xDC00) +
    0x10000.
- Otherwise:
  - Assert: {leadingValue} is within the _Unicode scalar value_ range.
  - Assert: {trailingValue} is within the _Unicode scalar value_ range.
  - Return the sequence of the _Unicode scalar value_ {leadingValue} followed by
    the _Unicode scalar value_ {trailingValue}.

Note: If both escape sequences encode a _Unicode scalar value_, then this
semantic is identical to applying the prior semantic on each fixed-width escape
sequence. A variable-width escape sequence must only encode a _Unicode scalar
value_.

StringCharacter :: `\` EscapedCharacter

- Return the _Unicode scalar value_ represented by {EscapedCharacter} according
  to the table below.

| Escaped Character | Scalar Value | Character Name               |
| ----------------- | ------------ | ---------------------------- |
| {`"`}             | U+0022       | double quote                 |
| {`\`}             | U+005C       | reverse solidus (back slash) |
| {`/`}             | U+002F       | solidus (forward slash)      |
| {`b`}             | U+0008       | backspace                    |
| {`f`}             | U+000C       | form feed                    |
| {`n`}             | U+000A       | line feed (new line)         |
| {`r`}             | U+000D       | carriage return              |
| {`t`}             | U+0009       | horizontal tab               |

StringValue :: BlockString

- Return the _Unicode text_ by evaluating the {BlockString}.

BlockString :: `"""` BlockStringCharacter\* `"""`

- Let {rawValue} be the _Unicode text_ by concatenating the evaluation of all
  {BlockStringCharacter} (which may be an empty sequence).
- Return the result of {BlockStringValue(rawValue)}.

BlockStringCharacter :: SourceCharacter but not `"""` or `\"""`

- Return the _Unicode scalar value_ {SourceCharacter}.

BlockStringCharacter :: `\"""`

- Return the character sequence `"""`.

BlockStringValue(rawValue):

- Let {lines} be the result of splitting {rawValue} by {LineTerminator}.
- Let {commonIndent} be {null}.
- For each {line} in {lines}:
  - If {line} is the first item in {lines}, continue to the next {line}.
  - Let {length} be the number of characters in {line}.
  - Let {indent} be the number of leading consecutive {Whitespace} characters in
    {line}.
  - If {indent} is less than {length}:
    - If {commonIndent} is {null} or {indent} is less than {commonIndent}:
      - Let {commonIndent} be {indent}.
- If {commonIndent} is not {null}:
  - For each {line} in {lines}:
    - If {line} is the first item in {lines}, continue to the next line.
    - Remove {commonIndent} characters from the beginning of {line}.
- While the first item {line} in {lines} contains only {Whitespace}:
  - Remove the first item from {lines}.
- While the last item {line} in {lines} contains only {Whitespace}:
  - Remove the last item from {lines}.
- Let {formatted} be the empty character sequence.
- For each {line} in {lines}:
  - If {line} is the first item in {lines}:
    - Append {formatted} with {line}.
  - Otherwise:
    - Append {formatted} with a line feed character (U+000A).
    - Append {formatted} with {line}.
- Return {formatted}.

### Null Value

NullValue : `null`

Null values are represented as the keyword {null}.

GraphQL has two semantically different ways to represent the lack of a value:

- Explicitly providing the literal value: {null}.
- Implicitly not providing a value at all.

For example, these two field calls are similar, but are not identical:

```graphql example
{
  field(arg: null)
  field
}
```

The first has explicitly provided {null} to the argument "arg", while the second
has implicitly not provided a value to the argument "arg". These two forms may
be interpreted differently. For example, a mutation representing deleting a
field vs not altering a field, respectively. Neither form may be used for an
input expecting a Non-Null type.

Note: The same two methods of representing the lack of a value are possible via
variables by either providing the variable value as {null} or not providing a
variable value at all.

### Enum Value

EnumValue : Name but not `true`, `false` or `null`

Enum values are represented as unquoted names (e.g. `MOBILE_WEB`). It is
recommended that Enum values be "all caps". Enum values are only used in
contexts where the precise enumeration type is known. Therefore it is not
necessary to supply an enumeration type name in the literal.

### List Value

ListValue[Const] :

- [ ]
- [ Value[?Const]+ ]

Lists are ordered sequences of values wrapped in square brackets `[ ]`. The
values of a List literal may be any value literal or variable (e.g.
`[1, 2, 3]`).

Commas are optional throughout GraphQL so trailing commas are allowed and
repeated commas do not represent missing values.

**Semantics**

ListValue : [ ]

- Return a new empty list value.

ListValue : [ Value+ ]

- Let {inputList} be a new empty list value.
- For each {Value+}:
  - Let {value} be the result of evaluating {Value}.
  - Append {value} to {inputList}.
- Return {inputList}.

### Input Object Values

ObjectValue[Const] :

- { }
- { ObjectField[?Const]+ }

ObjectField[Const] : Name : Value[?Const]

Input object literal values are unordered lists of keyed input values wrapped in
curly braces `{ }`. The values of an object literal may be any input value
literal or variable (e.g. `{ name: "Hello world", score: 1.0 }`). We refer to
literal representation of input objects as "object literals."

**Input Object Fields Are Unordered**

Input object fields may be provided in any syntactic order and maintain
identical semantic meaning.

These two operations are semantically identical:

```graphql example
{
  nearestThing(location: { lon: 12.43, lat: -53.211 })
}
```

```graphql example
{
  nearestThing(location: { lat: -53.211, lon: 12.43 })
}
```

**Semantics**

ObjectValue : { }

- Return a new input object value with no fields.

ObjectValue : { ObjectField+ }

- Let {inputObject} be a new input object value with no fields.
- For each {field} in {ObjectField+}:
  - Let {name} be {Name} in {field}.
  - Let {value} be the result of evaluating {Value} in {field}.
  - Add a field to {inputObject} of name {name} containing value {value}.
- Return {inputObject}.

## Variables

Variable : $ Name

VariablesDefinition : ( VariableDefinition+ )

VariableDefinition : Description? Variable : Type DefaultValue?
Directives[Const]?

DefaultValue : = Value[Const]

A GraphQL operation can be parameterized with variables, maximizing reuse, and
avoiding costly string building in clients at runtime.

If not defined as constant (for example, in {DefaultValue}), a {Variable} can be
supplied for an input value.

Variables must be defined at the top of an operation and are in scope throughout
the execution of that operation. Values for those variables are provided to a
GraphQL service as part of a request so they may be substituted in during
execution.

In this example, we want to fetch a profile picture size based on the size of a
particular device:

```graphql example
query getZuckProfile(
  "The size of the profile picture to fetch."
  $devicePicSize: Int
) {
  user(id: 4) {
    id
    name
    profilePic(size: $devicePicSize)
  }
}
```

If providing JSON for the variables' values, we could request a `profilePic` of
size `60`:

```json example
{
  "devicePicSize": 60
}
```

**Variable Use Within Fragments**

Variables can be used within fragments. Variables have global scope with a given
operation, so a variable used within a fragment must be declared in any
top-level operation that transitively consumes that fragment. If a variable is
referenced in a fragment and is included by an operation that does not define
that variable, that operation is invalid (see
[All Variable Uses Defined](#sec-All-Variable-Uses-Defined)).

## Type References

Type :

- NamedType
- ListType
- NonNullType

NamedType : Name

ListType : [ Type ]

NonNullType :

- NamedType !
- ListType !

GraphQL describes the types of data expected by arguments and variables. Input
types may be lists of another input type, or a non-null variant of any other
input type.

**Semantics**

Type : Name

- Let {name} be the string value of {Name}.
- Let {type} be the type defined in the Schema named {name}.
- {type} must exist.
- Return {type}.

Type : [ Type ]

- Let {itemType} be the result of evaluating {Type}.
- Let {type} be a List type where {itemType} is the contained type.
- Return {type}.

Type : Type !

- Let {nullableType} be the result of evaluating {Type}.
- Let {type} be a Non-Null type where {nullableType} is the contained type.
- Return {type}.

## Directives

Directives[Const] : Directive[?Const]+

Directive[Const] : @ Name Arguments[?Const]?

Directives provide a way to describe alternate runtime execution and type
validation behavior in a GraphQL document.

In some cases, you need to provide options to alter GraphQL's execution behavior
in ways field arguments will not suffice, such as conditionally including or
skipping a field. Directives provide this by describing additional information
to the executor.

Directives have a name along with a list of arguments which may accept values of
any input type.

Directives can be used to describe additional information for types, fields,
fragments and operations.

As future versions of GraphQL adopt new configurable execution capabilities,
they may be exposed via directives. GraphQL services and tools may also provide
any additional _custom directive_ beyond those described here.

**Directive Order Is Significant**

Directives may be provided in a specific syntactic order which may have semantic
interpretation.

These two type definitions may have different semantic meaning:

```graphql example
type Person
  @addExternalFields(source: "profiles")
  @excludeField(name: "photo") {
  name: String
}
```

```graphql example
type Person
  @excludeField(name: "photo")
  @addExternalFields(source: "profiles") {
  name: String
}
```

## Schema Coordinates

SchemaCoordinate ::

- TypeCoordinate
- MemberCoordinate
- ArgumentCoordinate
- DirectiveCoordinate
- DirectiveArgumentCoordinate

TypeCoordinate :: Name

MemberCoordinate :: Name . Name

ArgumentCoordinate :: Name . Name ( Name : )

DirectiveCoordinate :: @ Name

DirectiveArgumentCoordinate :: @ Name ( Name : )

:: A _schema coordinate_ is a human readable string that uniquely identifies a
_schema element_ within a GraphQL Schema, intended to be used by tools to
reference types, fields, and other _schema element_. Examples include:
references within documentation to refer to types and fields in a schema, a
lookup key that can be used in logging tools to track how often particular
fields are queried in production.

:: A _schema element_ can be a named type, a field, an input field, an enum
value, a field argument, a directive, or a directive argument defined within a
schema (including built-in types and directives).

Note: Meta-fields are not defined within a schema, and thus are not _schema
element_. By extension, an introspection type is not a _schema element_.

:: The _containing element_ of a _schema element_ is the schema element with one
fewer {Name} token that syntactically contains it. Specifically:

- The containing element of an {ArgumentCoordinate} is a {MemberCoordinate}.
- The containing element of a {MemberCoordinate} is a {TypeCoordinate}.
- The containing element of a {DirectiveArgumentCoordinate} is a
  {DirectiveCoordinate}.
- {TypeCoordinate} and {DirectiveCoordinate} have no containing element.

A _schema coordinate_ is always unique. Each _schema element_ can be referenced
by exactly one possible schema coordinate.

A _schema coordinate_ may refer to either a defined or built-in _schema
element_. For example, `String` and `@deprecated(reason:)` are both valid schema
coordinates which refer to built-in schema elements.

Note: A union member references a type in the schema. A type in the schema is
identified by a {TypeCoordinate}. There is no schema coordinate which indicates
a union member; this preserves the uniqueness property of a _schema coordinate_
as stated above.

**Parsing a Schema Coordinate**

SchemaCoordinateToken ::

- SchemaCoordinatePunctuator
- Name

SchemaCoordinatePunctuator :: one of ( ) . : @

A {SchemaCoordinate} is a self-contained grammar with its own set of lexical
tokens, it is not contained within a {Document}. The source text of a
SchemaCoordinate must be a sequence of {SourceCharacter}.

Unlike other [GraphQL documents](#sec-Language), {SchemaCoordinate} must not
contain {Whitespace} or other {Ignored} grammars within the character sequence.
This ensures that every schema coordinates has a single unambiguous and unique
lexical form.

**Resolving a Schema Coordinate**

To refer to a _schema element_, a _schema coordinate_ must be interpreted in the
context of a GraphQL {schema}.

If the _schema element_ cannot be found, the resolve function will not yield a
value (without raising an error). However, an error will be raised if any
non-leaf nodes within a _schema coordinate_ cannot be found in the {schema}.

Note: Although it is syntactically possible to describe a meta-field or element
of the introspection schema with a schema coordinate (e.g. `Business.__typename`
or `__Type.fields(includeDeprecated:)`), they are not _schema element_ and
therefore resolving such coordinates does not have a defined behavior.

TypeCoordinate :: Name

1. Let {typeName} be the value of {Name}.
2. Return the type in {schema} named {typeName} if it exists.

MemberCoordinate :: Name . Name

1. Let {typeName} be the value of the first {Name}.
2. Let {type} be the type in {schema} named {typeName}.
3. Assert: {type} must exist, and must be an Enum, Input Object, Object or
   Interface type.
4. If {type} is an Enum type:
   1. Let {enumValueName} be the value of the second {Name}.
   2. Return the enum value of {type} named {enumValueName} if it exists.
5. Otherwise, if {type} is an Input Object type:
   1. Let {inputFieldName} be the value of the second {Name}.
   2. Return the input field of {type} named {inputFieldName} if it exists.
6. Otherwise:
   1. Let {fieldName} be the value of the second {Name}.
   2. Return the field of {type} named {fieldName} if it exists.

ArgumentCoordinate :: Name . Name ( Name : )

1. Let {typeName} be the value of the first {Name}.
2. Let {type} be the type in {schema} named {typeName}.
3. Assert: {type} must exist, and be an Object or Interface type.
4. Let {fieldName} be the value of the second {Name}.
5. Let {field} be the field of {type} named {fieldName}.
6. Assert: {field} must exist.
7. Let {fieldArgumentName} be the value of the third {Name}.
8. Return the argument of {field} named {fieldArgumentName} if it exists.

DirectiveCoordinate :: @ Name

1. Let {directiveName} be the value of {Name}.
2. Return the directive in {schema} named {directiveName} if it exists.

DirectiveArgumentCoordinate :: @ Name ( Name : )

1. Let {directiveName} be the value of the first {Name}.
2. Let {directive} be the directive in {schema} named {directiveName}.
3. Assert: {directive} must exist.
4. Let {directiveArgumentName} be the value of the second {Name}.
5. Return the argument of {directive} named {directiveArgumentName} if it
   exists.

**Examples**

| Element Kind       | Schema Coordinate                 | Schema Element                                                        |
| ------------------ | --------------------------------- | --------------------------------------------------------------------- |
| Named Type         | `Business`                        | `Business` type                                                       |
| Field              | `Business.name`                   | `name` field on the `Business` type                                   |
| Input Field        | `SearchCriteria.filter`           | `filter` input field on the `SearchCriteria` input object type        |
| Enum Value         | `SearchFilter.OPEN_NOW`           | `OPEN_NOW` value of the `SearchFilter` enum                           |
| Field Argument     | `Query.searchBusiness(criteria:)` | `criteria` argument on the `searchBusiness` field on the `Query` type |
| Directive          | `@private`                        | `@private` directive                                                  |
| Directive Argument | `@private(scope:)`                | `scope` argument on the `@private` directive                          |

The table above shows an example of a _schema coordinate_ for every kind of
_schema element_ based on the schema below.

```graphql
type Query {
  searchBusiness(criteria: SearchCriteria!): [Business]
}

input SearchCriteria {
  name: String
  filter: SearchFilter
}

enum SearchFilter {
  OPEN_NOW
  DELIVERS_TAKEOUT
  VEGETARIAN_MENU
}

type Business {
  id: ID
  name: String
  email: String @private(scope: "loggedIn")
}

directive @private(scope: String!) on FIELD_DEFINITION
```
