# Language

(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.

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

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

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

- "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.

### Line Terminators

LineTerminator ::

- "New Line (U+000A)"

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

- "Carriage Return (U+000D)" "New Line (U+000A)"

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

offending syntax should use the preceding amount of {LineTerminator} to produce

the line number.

### Comments

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 :: ,

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

often desired for legibility and maintainability of source code.

### Lexical Tokens

Token ::

- Punctuator

- Name

- IntValue

- FloatValue

- StringValue

### Ignored Tokens

Ignored ::

- UnicodeBOM

- LineTerminator

- Comment

- Comma

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}.

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}.

### Names

- 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`

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

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 : Definition+

- ExecutableDefinition

- TypeSystemDefinitionOrExtension

ExecutableDocument : ExecutableDefinition+

ExecutableDefinition :

- OperationDefinition

- FragmentDefinition

executable or representative of a GraphQL type system.

{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

multiple operations to a GraphQL service, the name of the desired operation to

be executed must also be provided.

OperationDefinition :

- 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:

"""

Mark story 12345 as "liked"

and return the updated number of likes on the story

"""

mutation {

likeStory(storyID: 12345) {

story {

likeCount

}

}

}

```

{

field

}

```

Descriptions are not permitted on query shorthand.

SelectionSet : { Selection+ }

- Field

- FragmentSpread

- InlineFragment

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.

{

id

firstName

lastName

}

```

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

For example, this operation selects fields of complex data and relationships

down to scalar values.

{

me {

id

firstName

lastName

day

}

friends {

name

}

}

}

```

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.

# `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

}