[ { "path": ".github/ISSUE_TEMPLATE.md", "content": "!!! IMPORTANT !!!\n\nBefore creating your issue:\n\n- Have a question? Find community resources at https://graphql.org/community/\n\n- Find an editing mistake? Create a Pull Request with the edited fix! The Github\n UI allows you to edit files directly, find the source files at:\n https://github.com/graphql/graphql-spec/tree/master/spec\n\n- Improvements to documentation? Head over to\n https://github.com/graphql/graphql.github.io\n\n- Feature request? First read\n https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md and prefer\n creating a Pull Request!\n" }, { "path": ".github/PULL_REQUEST_TEMPLATE.md", "content": "!!! IMPORTANT !!!\n\nPlease Read https://github.com/graphql/graphql-spec/blob/master/CONTRIBUTING.md\nbefore creating a Pull Request.\n" }, { "path": ".github/algorithm-format-check.mjs", "content": "import { readFile, readdir } from \"node:fs/promises\";\n\nconst SPEC_DIR = new URL(\"../spec\", import.meta.url).pathname;\n\n/** @see {@link https://spec-md.com/#sec-Value-Literals} */\nconst valueLiteralsRegexp = /\\{((?:[^{}]|(?:\\{[^{}]*\\}))+)\\}/g;\n\nprocess.exitCode = 0;\nconst filenames = await readdir(SPEC_DIR);\nfor (const filename of filenames) {\n if (!filename.endsWith(\".md\")) {\n continue;\n }\n const markdown = await readFile(`${SPEC_DIR}/${filename}`, \"utf8\");\n\n /**\n * Not strictly 'lines' since we try and group indented things together as if\n * they were one line. Close enough though.\n */\n const lines = markdown.split(/\\n(?=[\\S\\n]|\\s*(?:-|[0-9]+\\.) )/);\n\n for (let i = 0, l = lines.length; i < l; i++) {\n const line = lines[i];\n\n // Check algorithm is consistently formatted\n {\n // Is it an algorithm definition?\n const matches = line.match(/^([a-z0-9A-Z]+)(\\s*)\\(([^)]*)\\)(\\s*):(\\s*)$/);\n const grammarMatches =\n filename === \"Section 2 -- Language.md\" &&\n line.match(/^([A-Za-z0-9]+) ::?\\s+((\\S).*)$/);\n if (matches) {\n const [, algorithmName, ns1, _args, ns2, ns3] = matches;\n if (ns1 || ns2 || ns3) {\n console.log(\n `Bad whitespace in definition of ${algorithmName} in '${filename}':`\n );\n console.dir(line);\n console.log();\n process.exitCode = 1;\n }\n if (lines[i + 1] !== \"\") {\n console.log(\n `No empty space after algorithm ${algorithmName} header in '${filename}'`\n );\n console.log();\n process.exitCode = 1;\n }\n for (let j = i + 2; j < l; j++) {\n const step = lines[j];\n if (!step.match(/^\\s*(-|[0-9]+\\.) /)) {\n if (step !== \"\") {\n console.log(\n `Bad algorithm ${algorithmName} step in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n break;\n }\n if (!step.match(/[.:]$/)) {\n console.log(\n `Bad formatting for '${algorithmName}' step (does not end in '.' or ':') in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n if (step.match(/^\\s*(-|[0-9]+\\.)\\s+[a-z]/)) {\n console.log(\n `Bad formatting of '${algorithmName}' step (should start with a capital) in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n const assertMatch = step.match(/^\\s*(-|[0-9]+\\.)\\s*Assert([^:])/);\n if (assertMatch) {\n console.log(\n `Bad formatting of '${algorithmName}' step (Assert should be immediately followed by ':'; found '${assertMatch[2]}') in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n\n const stepWithoutValueLiterals = step.replace(\n valueLiteralsRegexp,\n \"\"\n );\n if (stepWithoutValueLiterals.match(/\\b[A-Z][A-Za-z0-9]+\\(/)) {\n console.log(\n `Bad formatting of '${algorithmName}' step (algorithm call should be wrapped in braces: \\`{MyAlgorithm(a, b, c)}\\`) in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n\n const valueLiterals = step.matchAll(valueLiteralsRegexp, \"\");\n for (const lit of valueLiterals) {\n const inner = lit[1];\n if (inner.includes(\"{\")) {\n console.log(\n `Bad formatting of '${algorithmName}' step (algorithm call should not contain braces: \\`${lit}\\`) in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n }\n\n const trimmedInnerLine = step.replace(/\\s+/g, \" \");\n if (\n trimmedInnerLine.match(\n /(?:[rR]eturn|is (?:not )?)(true|false|null)\\b/\n ) &&\n !trimmedInnerLine.match(/null or empty/)\n ) {\n console.log(\n `Potential bad formatting of '${algorithmName}' step (true/false/null should be wrapped in curly braces, e.g. '{true}') in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n }\n } else if (grammarMatches) {\n // This is super loosey-goosey\n const [, grammarName, rest] = grammarMatches;\n if (rest.trim() === \"one of\") {\n // Still grammar, not algorithm\n continue;\n }\n if (rest.trim() === \"\" && lines[i + 1] !== \"\") {\n console.log(\n `No empty space after grammar ${grammarName} header in '${filename}'`\n );\n console.log();\n process.exitCode = 1;\n }\n while (lines[i + 1].trim() !== \"\") {\n // Continuation of definition\n i++;\n }\n if (!lines[i + 2].startsWith(\"- \")) {\n // Not an algorithm; probably more grammar\n continue;\n }\n for (let j = i + 2; j < l; j++) {\n const step = lines[j];\n if (!step.match(/^\\s*(-|[0-9]+\\.) /)) {\n if (step !== \"\") {\n console.log(`Bad grammar ${grammarName} step in '${filename}':`);\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n break;\n }\n if (!step.match(/[.:]$/)) {\n console.log(\n `Bad formatting for '${grammarName}' step (does not end in '.' or ':') in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n if (step.match(/^\\s*(-|[0-9]\\.)\\s+[a-z]/)) {\n console.log(\n `Bad formatting of '${grammarName}' step (should start with a capital) in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n const trimmedInnerLine = step.replace(/\\s+/g, \" \");\n if (\n trimmedInnerLine.match(\n /(?:[rR]eturn|is (?:not )?)(true|false|null)\\b/\n ) &&\n !trimmedInnerLine.match(/null or empty/)\n ) {\n console.log(\n `Potential bad formatting of '${grammarName}' step (true/false/null should be wrapped in curly braces, e.g. '{true}') in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n const assertMatch = step.match(/^\\s*(-|[0-9]+\\.)\\s*Assert([^:])/);\n if (assertMatch) {\n console.log(\n `Bad formatting of '${grammarName}' step (Assert should be immediately followed by ':'; found '${assertMatch[2]}') in '${filename}':`\n );\n console.dir(step);\n console.log();\n process.exitCode = 1;\n }\n }\n }\n }\n\n // Check `- ...:` step is followed by an indent\n {\n const matches = line.match(/^(\\s*)- .*:\\s*$/);\n if (matches) {\n const indent = matches[1];\n const nextLine = lines[i + 1];\n if (!nextLine.startsWith(`${indent} `)) {\n console.log(\n `Lacking indent in '${filename}' following ':' character:`\n );\n console.dir(line);\n console.dir(nextLine);\n console.log();\n // TODO: process.exitCode = 1;\n }\n }\n }\n }\n}\n\nif (process.exitCode === 0) {\n console.log(`Everything looks okay!`);\n} else {\n console.log(`Please resolve the errors detailed above.`);\n}\n" }, { "path": ".github/workflows/ci.yml", "content": "name: CI\n\non:\n push:\n branches:\n - main\n pull_request:\n\njobs:\n test-spelling:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n - run: npm ci\n - run: npm run test:spelling\n test-format:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n - run: npm ci\n - run: npm run test:format\n - run: npm run test:algorithm-format\n test-build:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-node@v3\n - run: npm ci\n - run: npm run test:build\n publish:\n if: github.ref == 'refs/heads/main'\n needs:\n - test-spelling\n - test-format\n - test-build\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n with:\n fetch-depth: 0\n - uses: actions/setup-node@v3\n - run: npm ci\n - run: npm run build\n - uses: peaceiris/actions-gh-pages@v3\n with:\n github_token: ${{ secrets.GITHUB_TOKEN }}\n keep_files: true\n cname: spec.graphql.org\n user_name: \"github-actions[bot]\"\n user_email: \"github-actions[bot]@users.noreply.github.com\"\n" }, { "path": ".gitignore", "content": "*.swp\n*~\n.*.haste_cache.*\n.DS_Store\nnpm-debug.log\n/build\n/public\n/gh-pages\n/node_modules\n" }, { "path": ".prettierignore", "content": "*.swp\n*~\n.*.haste_cache.*\n.DS_Store\nnpm-debug.log\n/build\n/changelogs\n/out\n/gh-pages\n/node_modules\n/package.json\n" }, { "path": "CONTRIBUTING.md", "content": "# GraphQL Specification Contribution Guide\n\nGraphQL is still an evolving language. This repository contains the\nspecification text as well as Pull Requests with suggested improvements and\ncontributions.\n\nContributions that do not change the interpretation of the spec but instead\nimprove legibility, fix editorial errors, clear up ambiguity and improve\nexamples are encouraged. These \"editorial changes\" will normally be given the\n[\"✏ Editorial\" label](https://github.com/graphql/graphql-spec/issues?q=sort%3Aupdated-desc+is%3Aopen+label%3A%22%E2%9C%8F%EF%B8%8F+Editorial%22)\nand are often merged by a spec editor with little process.\n\nHowever, contributions that _do_ meaningfully change the interpretation of the\nspec must follow an RFC (Request For Comments) process led by a _champion_\nthrough a series of _stages_ intended to improve _visibility_, allow for\n_discussion_ to reach the best solution, and arrive at _consensus_. This process\nbecomes ever more important as GraphQL's community broadens.\n\nWhen proposing or weighing-in on any issue or pull request, consider the\n[Code of Conduct](https://github.com/graphql/foundation/blob/main/CODE-OF-CONDUCT.md)\nto better understand expected and unacceptable behavior.\n\n## Contributing to GraphQL Libraries\n\nA common point of confusion for those who wish to contribute to GraphQL is where\nto start. In fact, you may have found yourself here after attempting to make an\nimprovement to a GraphQL library. Should a new addition be made to the GraphQL\nspec first or a GraphQL library first? Admittedly, this can become a bit of a\n[chicken-or-egg](https://en.wikipedia.org/wiki/Chicken_or_the_egg) dilemma.\n\nGraphQL libraries seek to be \"spec compliant\", which means they discourage\nchanges that cause them to behave differently from the spec as written. However,\nthey also encourage pull requests for changes that accompany an RFC _proposal_\nor RFC _draft_. In fact, a spec contribution RFC won't be _accepted_ until it\nhas experience being implemented in a GraphQL library.\n\nTo allow a library to remain spec compliant while also implementing _proposals_\nand _drafts_, the library's maintainers may request that these new features are\ndisabled by default with opt-in option flags or they may simply wait to merge a\nwell-tested pull request until the spec proposal is _accepted_.\n\n## Guiding Principles\n\nGraphQL's evolution is guided by a few principles. Suggested contributions\nshould use these principles to guide the details of an RFC and decisions to move\nforward. See editor Lee Byron talk about\n[guiding principles at GraphQL Europe 2017](https://youtu.be/mePT9MNTM98?t=17m9s).\n\n- **Backwards compatibility**\n\n Once a query is written, it should always mean the same thing and return the\n same shaped result. Future changes should not change the meaning of existing\n schema or requests or in any other way cause an existing compliant GraphQL\n service to become non-compliant for prior versions of the spec.\n\n- **Performance is a feature**\n\n GraphQL typically avoids syntax or behaviors that could jeopardize runtime\n efficiency, or that make demands of GraphQL services which cannot efficiently\n be fulfilled.\n\n- **Favor no change**\n\n As GraphQL is implemented in over a dozen languages under the collaboration of\n hundreds of individuals, incorporating any change has a high cost.\n Accordingly, proposed changes must meet a very high bar of added value. The\n burden of proof is on the contributor to illustrate this value.\n\n- **Enable new capabilities motivated by real use cases**\n\n Every change should intend on unlocking a real and reasonable use case. Real\n examples are always more compelling than theoretical ones, and common\n scenarios are more compelling than rare ones. RFCs should do more than offer a\n different way to reach an already achievable outcome.\n\n- **Simplicity and consistency over expressiveness and terseness**\n\n Plenty of behaviors and patterns found in other languages are intentionally\n absent from GraphQL. \"Possible but awkward\" is often favored over more complex\n alternatives. Simplicity (e.g. fewer concepts) is more important than\n expressing more sophisticated ideas or writing less.\n\n- **Preserve option value**\n\n It's hard to know what the future brings; whenever possible, decisions should\n be made that allow for more options in the future. Sometimes this is\n unintuitive: spec rules often begin more strict than necessary with a future\n option to loosen when motivated by a real use case.\n\n- **Understandability is just as important as correctness**\n\n The GraphQL spec, despite describing technical behavior, is intended to be\n read by people. Use natural tone and include motivation and examples.\n\n## RFC Contribution Champions\n\nContributing to GraphQL requires a lot of dedicated work. To set clear\nexpectations and provide accountability, each proposed RFC (request for\ncomments) must have a _champion_ who is responsible for addressing feedback and\ncompleting next steps. An RFC may have multiple _champions_. The spec editors\nare not responsible for completing RFCs which lack a _champion_ (though an\neditor may be a _champion_ for an RFC).\n\nAn RFC which does not have a _champion_ may not progress through stages, and can\nbecome stale. Stale proposals may be picked up by a new _champion_ or may be\n_rejected_.\n\n## RFC Contribution Stages\n\nRFCs are guided by a _champion_ through a series of stages: _strawman_,\n_proposal_, _draft_, and _accepted_ (or _rejected_), each of which has suggested\nentrance criteria and next steps detailed below. RFCs typically advance one\nstage at a time, but may advance multiple stages at a time. Stage advancements\ntypically occur during [Working Group](https://github.com/graphql/graphql-wg)\nmeetings, but may also occur on GitHub.\n\nIn general, it's preferable to start with a pull request so that we can best\nevaluate the RFC in detail. However, starting with an issue is also permitted if\nthe full details are not worked out.\n\nAll RFCs start as either a _strawman_ or _proposal_.\n\n## Stage 0: _Strawman_\n\nAn RFC at the _strawman_ stage captures a described problem or\npartially-considered solutions. A _strawman_ does not need to meet any entrance\ncriteria. A _strawman's_ goal is to prove or disprove a problem and guide\ndiscussion towards either rejection or a preferred solution. A _strawman_ may be\nan issue or a pull request (though an illustrative pull request is preferrable).\n\n_There is no entrance criteria for a Strawman_\n\nAs implied by the name\n[strawman](https://en.wikipedia.org/wiki/Straw_man_proposal), the goal at this\nstage is to knock it down (_reject_) by considering other possible related\nsolutions, showing that the motivating problem can be solved with no change to\nthe specification, or that it is not aligned with the _guiding principles_.\n\nOnce determined that the _strawman_ is compelling, it should seek the entrance\ncriteria for _proposal_.\n\n## Stage 1: _Proposal_\n\nAn RFC at the _proposal_ stage is a solution to a problem with enough fidelity\nto be discussed in detail. It must be backed by a willing _champion_. A\n_proposal_'s goal is to make a compelling case for acceptance by describing both\nthe problem and the solution via examples and spec edits. A _proposal_ should be\na pull request.\n\n_Entrance criteria:_\n\n- Identified _champion_\n- Clear explanation of problem and solution\n- Illustrative examples\n- Incomplete spec edits\n- Identification of potential concerns, challenges, and drawbacks\n\nA _proposal_ is subject to the same discussion as a _strawman_: ensuring that it\nis well aligned with the _guiding principles_, is a problem worth solving, and\nis the preferred solution to that problem. A _champion_ is not expected to have\nconfidence in every detail at this stage and should instead focus on identifying\nand resolving issues and edge-cases. To better understand the technical\nramifications of the _proposal_, a _champion_ is encouraged to implement it in a\nGraphQL library.\n\nMost _proposals_ are expected to evolve or change and may be rejected.\nTherefore, it is unwise to rely on a _proposal_ in a production GraphQL service.\nGraphQL libraries _may_ implement _proposals_, though are encouraged to not\nenable the _proposed_ feature without explicit opt-in.\n\n## Stage 2: _Draft_\n\nAn RFC at the _draft_ stage is a fully formed solution. There is working group\nconsensus the problem identified should be solved, and this particular solution\nis preferred. A _draft's_ goal is to precisely and completely describe the\nsolution and resolve any concerns through library implementations. A _draft_\nmust be a pull request.\n\n_Entrance criteria:_\n\n- Consensus the solution is preferred (typically via Working Group)\n- Resolution of identified concerns and challenges\n- Precisely described with spec edits\n- Compliant implementation in GraphQL.js (might not be merged)\n\nA _proposal_ becomes a _draft_ when the set of problems or drawbacks have been\nfully considered and accepted or resolved, and the solution is deemed desirable.\nA _draft_'s goal is to complete final spec edits that are ready to be merged and\nimplement the _draft_ in GraphQL libraries along with tests to gain confidence\nthat the spec text is sufficient.\n\n_Drafts_ may continue to evolve and change, occasionally dramatically, and are\nnot guaranteed to be accepted. Therefore, it is unwise to rely on a _draft_ in a\nproduction GraphQL Service. GraphQL libraries _should_ implement _drafts_ to\nprovide valuable feedback, though are encouraged not to enable the _draft_\nfeature without explicit opt-in when possible.\n\n## Stage 3: _Accepted_\n\nAn RFC at the _accepted_ stage is a completed solution. According to a spec\neditor it is ready to be merged as-is into the spec document. The RFC is ready\nto be deployed in GraphQL libraries. An _accepted_ RFC must be implemented in\nGraphQL.js.\n\n_Entrance criteria:_\n\n- Consensus the solution is complete (via editor or working group)\n- Complete spec edits, including examples and prose\n- Compliant implementation in GraphQL.js (fully tested and merged or ready to\n merge)\n\nA _draft_ is _accepted_ when the working group or editor has been convinced via\nimplementations and tests that it appropriately handles all edge cases; that the\nspec changes not only precisely describe the new syntax and semantics but\ninclude sufficient motivating prose and examples; and that the RFC includes\nedits to any other affected areas of the spec. Once _accepted_, its _champion_\nshould encourage adoption of the RFC by opening issues or pull requests on other\npopular GraphQL libraries.\n\nAn _accepted_ RFC is merged into the GraphQL spec's main branch by an editor and\nwill be included in the next released revision.\n\n## Stage X: _Rejected_\n\nAn RFC may be _rejected_ at any point and for any reason. Most rejections occur\nwhen a _strawman_ is proven to be unnecessary, is misaligned with the _guiding\nprinciples_, or fails to meet the entrance criteria to become a _proposal_. A\n_proposal_ may become _rejected_ for similar reasons as well as if it fails to\nreach consensus or loses the confidence of its _champion_. Likewise a _draft_\nmay encounter unforeseen issues during implementations which cause it to lose\nconsensus or the confidence of its _champion_.\n\nRFCs which have lost a _champion_ will not be _rejected_ immediately, but may\nbecome _rejected_ if they fail to attract a new _champion_.\n\nOnce _rejected_, an RFC will typically not be reconsidered. Reconsideration is\npossible if a _champion_ believes the original reason for rejection no longer\napplies due to new circumstances or new evidence.\n" }, { "path": "LICENSE.md", "content": "# Appendix: Copyright and Licensing\n\nThe GraphQL Specification Project is made available by the\n[Joint Development Foundation](https://www.jointdevelopment.org/) Projects, LLC,\nGraphQL Series. The current\n[Working Group](https://github.com/graphql/graphql-wg) charter, which includes\nthe IP policy governing all working group deliverables (including\nspecifications, source code, and datasets) may be found at\n[https://technical-charter.graphql.org](https://technical-charter.graphql.org).\n\n**Copyright Notice**\n\nCopyright © 2015-2018, Facebook, Inc.\n\nCopyright © 2019-present, GraphQL contributors\n\nTHESE MATERIALS ARE PROVIDED “AS IS”. The parties expressly disclaim any\nwarranties (express, implied, or otherwise), including implied warranties of\nmerchantability, non-infringement, fitness for a particular purpose, or title,\nrelated to the materials. The entire risk as to implementing or otherwise using\nthe materials is assumed by the implementer and user. IN NO EVENT WILL THE\nPARTIES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT,\nSPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES\nOF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING\nAGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR\nOTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE\nPOSSIBILITY OF SUCH DAMAGE.\n\n**Licensing**\n\nThe licenses for the GraphQL Specification Project are:\n\n| Deliverable | License |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Specifications | [Open Web Foundation Agreement 1.0 (Patent and Copyright Grants)](https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0) |\n| Source code | [MIT License](https://opensource.org/licenses/MIT) |\n| Data sets | [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) |\n" }, { "path": "README.md", "content": "[![The query language for modern APIs](./assets/banner.png)](https://graphql.org/)\n\n# GraphQL\n\n\"GraphQL\n\nThe GraphQL specification is edited in the markdown files found in\n[`/spec`](./spec) the latest release of which is published at\nhttps://graphql.github.io/graphql-spec/.\n\nThe latest draft specification can be found at\nhttps://graphql.github.io/graphql-spec/draft/ which tracks the latest commit to\nthe main branch in this repository.\n\nPrevious releases of the GraphQL specification can be found at permalinks that\nmatch their [release tag](https://github.com/graphql/graphql-spec/releases). For\nexample, https://graphql.github.io/graphql-spec/October2016/. If you are linking\ndirectly to the GraphQL specification, it's best to link to a tagged permalink\nfor the particular referenced version.\n\n## Overview\n\nThis is a Working Draft of the Specification for GraphQL, a query language for\nAPIs created by Facebook.\n\nThe target audience for this specification is not the client developer, but\nthose who have, or are actively interested in, building their own GraphQL\nimplementations and tools.\n\nIn order to be broadly adopted, GraphQL will have to target a wide variety of\nbackend environments, frameworks, and languages, which will necessitate a\ncollaborative effort across projects and organizations. This specification\nserves as a point of coordination for this effort.\n\nLooking for help? Find resources\n[from the community](https://graphql.org/community/).\n\n## Getting Started\n\nGraphQL consists of a type system, query language and execution semantics,\nstatic validation, and type introspection, each outlined below. To guide you\nthrough each of these components, we've written an example designed to\nillustrate the various pieces of GraphQL.\n\nThis example is not comprehensive, but it is designed to quickly introduce the\ncore concepts of GraphQL, to provide some context before diving into the more\ndetailed specification or the\n[GraphQL.js](https://github.com/graphql/graphql-js) reference implementation.\n\nThe premise of the example is that we want to use GraphQL to query for\ninformation about characters and locations in the original Star Wars trilogy.\n\n### Type System\n\nAt the heart of any GraphQL implementation is a description of what types of\nobjects it can return, described in a GraphQL type system and returned in the\nGraphQL Schema.\n\nFor our Star Wars example, the\n[starWarsSchema.ts](https://github.com/graphql/graphql-js/blob/main/src/__tests__/starWarsSchema.ts)\nfile in GraphQL.js defines this type system.\n\nThe most basic type in the system will be `Human`, representing characters like\nLuke, Leia, and Han. All humans in our type system will have a name, so we\ndefine the `Human` type to have a field called \"name\". This returns a String,\nand we know that it is not null (since all `Human`s have a name), so we will\ndefine the \"name\" field to be a non-nullable String. Using a shorthand notation\nthat we will use throughout the spec and documentation, we would describe the\nhuman type as:\n\n```graphql\ntype Human {\n name: String\n}\n```\n\nThis shorthand is convenient for describing the basic shape of a type system;\nthe JavaScript implementation is more full-featured, and allows types and fields\nto be documented. It also sets up the mapping between the type system and the\nunderlying data; for a test case in GraphQL.js, the underlying data is a\n[set of JavaScript objects](https://github.com/graphql/graphql-js/blob/main/src/__tests__/starWarsData.ts),\nbut in most cases the backing data will be accessed through some service, and\nthis type system layer will be responsible for mapping from types and fields to\nthat service.\n\nA common pattern in many APIs, and indeed in GraphQL is to give objects an ID\nthat can be used to refetch the object. So let's add that to our Human type.\nWe'll also add a string for their home planet.\n\n```graphql\ntype Human {\n id: String\n name: String\n homePlanet: String\n}\n```\n\nSince we're talking about the Star Wars trilogy, it would be useful to describe\nthe episodes in which each character appears. To do so, we'll first define an\nenum, which lists the three episodes in the trilogy:\n\n```graphql\nenum Episode {\n NEWHOPE\n EMPIRE\n JEDI\n}\n```\n\nNow we want to add a field to `Human` describing what episodes they were in.\nThis will return a list of `Episode`s:\n\n```graphql\ntype Human {\n id: String\n name: String\n appearsIn: [Episode]\n homePlanet: String\n}\n```\n\nNow, let's introduce another type, `Droid`:\n\n```graphql\ntype Droid {\n id: String\n name: String\n appearsIn: [Episode]\n primaryFunction: String\n}\n```\n\nNow we have two types! Let's add a way of going between them: humans and droids\nboth have friends. But humans can be friends with both humans and droids. How do\nwe refer to either a human or a droid?\n\nIf we look, we note that there's common functionality between humans and droids;\nthey both have IDs, names, and episodes in which they appear. So we'll add an\ninterface, `Character`, and make both `Human` and `Droid` implement it. Once we\nhave that, we can add the `friends` field, that returns a list of `Character`s.\n\nOur type system so far is:\n\n```graphql\nenum Episode {\n NEWHOPE\n EMPIRE\n JEDI\n}\n\ninterface Character {\n id: String\n name: String\n friends: [Character]\n appearsIn: [Episode]\n}\n\ntype Human implements Character {\n id: String\n name: String\n friends: [Character]\n appearsIn: [Episode]\n homePlanet: String\n}\n\ntype Droid implements Character {\n id: String\n name: String\n friends: [Character]\n appearsIn: [Episode]\n primaryFunction: String\n}\n```\n\nOne question we might ask, though, is whether any of those fields can return\n`null`. By default, `null` is a permitted value for any type in GraphQL, since\nfetching data to fulfill a GraphQL query often requires talking to different\nservices that may or may not be available. However, if the type system can\nguarantee that a type is never null, then we can mark it as Non Null in the type\nsystem. We indicate that in our shorthand by adding an \"!\" after the type. We\ncan update our type system to note that the `id` is never null.\n\nNote that while in our current implementation, we can guarantee that more fields\nare non-null (since our current implementation has hard-coded data), we didn't\nmark them as non-null. One can imagine we would eventually replace our hardcoded\ndata with a backend service, which might not be perfectly reliable; by leaving\nthese fields as nullable, we allow ourselves the flexibility to eventually\nreturn null to indicate a backend error, while also telling the client that the\nerror occurred.\n\n```graphql\nenum Episode {\n NEWHOPE\n EMPIRE\n JEDI\n}\n\ninterface Character {\n id: String!\n name: String\n friends: [Character]\n appearsIn: [Episode]\n}\n\ntype Human implements Character {\n id: String!\n name: String\n friends: [Character]\n appearsIn: [Episode]\n homePlanet: String\n}\n\ntype Droid implements Character {\n id: String!\n name: String\n friends: [Character]\n appearsIn: [Episode]\n primaryFunction: String\n}\n```\n\nWe're missing one last piece: an entry point into the type system.\n\nWhen we define a schema, we define an object type that is the basis for all\nquery operations. The name of this type is `Query` by convention, and it\ndescribes our public, top-level API. Our `Query` type for this example will look\nlike this:\n\n```graphql\ntype Query {\n hero(episode: Episode): Character\n human(id: String!): Human\n droid(id: String!): Droid\n}\n```\n\nIn this example, there are three top-level operations that can be done on our\nschema:\n\n- `hero` returns the `Character` who is the hero of the Star Wars trilogy; it\n takes an optional argument that allows us to fetch the hero of a specific\n episode instead.\n- `human` accepts a non-null string as a query argument, a human's ID, and\n returns the human with that ID.\n- `droid` does the same for droids.\n\nThese fields demonstrate another feature of the type system, the ability for a\nfield to specify arguments that configure their behavior.\n\nWhen we package the whole type system together, defining the `Query` type above\nas our entry point for queries, this creates a GraphQL Schema.\n\nThis example just scratched the surface of the type system. The specification\ngoes into more detail about this topic in the \"Type System\" section, and the\n[type](https://github.com/graphql/graphql-js/blob/main/src/type) directory in\nGraphQL.js contains code implementing a specification-compliant GraphQL type\nsystem.\n\n### Query Syntax\n\nGraphQL queries declaratively describe what data the issuer wishes to fetch from\nwhoever is fulfilling the GraphQL query.\n\nFor our Star Wars example, the\n[starWarsQueryTests.js](https://github.com/graphql/graphql-js/blob/main/src/__tests__/starWarsQuery-test.ts)\nfile in the GraphQL.js repository contains a number of queries and responses.\nThat file is a test file that uses the schema discussed above and a set of\nsample data, located in\n[starWarsData.js](https://github.com/graphql/graphql-js/blob/main/src/__tests__/starWarsData.ts).\nThis test file can be run to exercise the reference implementation.\n\nAn example query on the above schema would be:\n\n```graphql\nquery HeroNameQuery {\n hero {\n name\n }\n}\n```\n\nThe initial line, `query HeroNameQuery`, defines a query with the operation name\n`HeroNameQuery` that starts with the schema's root query type; in this case,\n`Query`. As defined above, `Query` has a `hero` field that returns a\n`Character`, so we'll query for that. `Character` then has a `name` field that\nreturns a `String`, so we query for that, completing our query. The result of\nthis query would then be:\n\n```json\n{\n \"hero\": {\n \"name\": \"R2-D2\"\n }\n}\n```\n\nSpecifying the `query` keyword and an operation name is only required when a\nGraphQL document defines multiple operations. We therefore could have written\nthe previous query with the query shorthand:\n\n```graphql\n{\n hero {\n name\n }\n}\n```\n\nAssuming that the backing data for the GraphQL server identified R2-D2 as the\nhero. The response continues to vary based on the request; if we asked for\nR2-D2's ID and friends with this query:\n\n```graphql\nquery HeroNameAndFriendsQuery {\n hero {\n id\n name\n friends {\n id\n name\n }\n }\n}\n```\n\nthen we'll get back a response like this:\n\n```json\n{\n \"hero\": {\n \"id\": \"2001\",\n \"name\": \"R2-D2\",\n \"friends\": [\n {\n \"id\": \"1000\",\n \"name\": \"Luke Skywalker\"\n },\n {\n \"id\": \"1002\",\n \"name\": \"Han Solo\"\n },\n {\n \"id\": \"1003\",\n \"name\": \"Leia Organa\"\n }\n ]\n }\n}\n```\n\nOne of the key aspects of GraphQL is its ability to nest queries. In the above\nquery, we asked for R2-D2's friends, but we can ask for more information about\neach of those objects. So let's construct a query that asks for R2-D2's friends,\ngets their name and episode appearances, then asks for each of _their_ friends.\n\n```graphql\nquery NestedQuery {\n hero {\n name\n friends {\n name\n appearsIn\n friends {\n name\n }\n }\n }\n}\n```\n\nwhich will give us the nested response\n\n```json\n{\n \"hero\": {\n \"name\": \"R2-D2\",\n \"friends\": [\n {\n \"name\": \"Luke Skywalker\",\n \"appearsIn\": [\"NEWHOPE\", \"EMPIRE\", \"JEDI\"],\n \"friends\": [\n { \"name\": \"Han Solo\" },\n { \"name\": \"Leia Organa\" },\n { \"name\": \"C-3PO\" },\n { \"name\": \"R2-D2\" }\n ]\n },\n {\n \"name\": \"Han Solo\",\n \"appearsIn\": [\"NEWHOPE\", \"EMPIRE\", \"JEDI\"],\n \"friends\": [\n { \"name\": \"Luke Skywalker\" },\n { \"name\": \"Leia Organa\" },\n { \"name\": \"R2-D2\" }\n ]\n },\n {\n \"name\": \"Leia Organa\",\n \"appearsIn\": [\"NEWHOPE\", \"EMPIRE\", \"JEDI\"],\n \"friends\": [\n { \"name\": \"Luke Skywalker\" },\n { \"name\": \"Han Solo\" },\n { \"name\": \"C-3PO\" },\n { \"name\": \"R2-D2\" }\n ]\n }\n ]\n }\n}\n```\n\nThe `Query` type above defined a way to fetch a human given their ID. We can use\nit by hard-coding the ID in the query:\n\n```graphql\nquery FetchLukeQuery {\n human(id: \"1000\") {\n name\n }\n}\n```\n\nto get\n\n```json\n{\n \"human\": {\n \"name\": \"Luke Skywalker\"\n }\n}\n```\n\nAlternately, we could have defined the query to have a query parameter:\n\n```graphql\nquery FetchSomeIDQuery($someId: String!) {\n human(id: $someId) {\n name\n }\n}\n```\n\nThis query is now parameterized by `$someId`; to run it, we must provide that\nID. If we ran it with `$someId` set to \"1000\", we would get Luke; set to \"1002\",\nwe would get Han. If we passed an invalid ID here, we would get `null` back for\nthe `human`, indicating that no such object exists.\n\nNotice that the key in the response is the name of the field, by default. It is\nsometimes useful to change this key, for clarity or to avoid key collisions when\nfetching the same field with different arguments.\n\nWe can do that with field aliases, as demonstrated in this query:\n\n```graphql\nquery FetchLukeAliased {\n luke: human(id: \"1000\") {\n name\n }\n}\n```\n\nWe aliased the result of the `human` field to the key `luke`. Now the response\nis:\n\n```json\n{\n \"luke\": {\n \"name\": \"Luke Skywalker\"\n }\n}\n```\n\nNotice the key is \"luke\" and not \"human\", as it was in our previous example\nwhere we did not use the alias.\n\nThis is particularly useful if we want to use the same field twice with\ndifferent arguments, as in the following query:\n\n```graphql\nquery FetchLukeAndLeiaAliased {\n luke: human(id: \"1000\") {\n name\n }\n leia: human(id: \"1003\") {\n name\n }\n}\n```\n\nWe aliased the result of the first `human` field to the key `luke`, and the\nsecond to `leia`. So the result will be:\n\n```json\n{\n \"luke\": {\n \"name\": \"Luke Skywalker\"\n },\n \"leia\": {\n \"name\": \"Leia Organa\"\n }\n}\n```\n\nNow imagine we wanted to ask for Luke and Leia's home planets. We could do so\nwith this query:\n\n```graphql\nquery DuplicateFields {\n luke: human(id: \"1000\") {\n name\n homePlanet\n }\n leia: human(id: \"1003\") {\n name\n homePlanet\n }\n}\n```\n\nbut we can already see that this could get unwieldy, since we have to add new\nfields to both parts of the query. Instead, we can extract out the common fields\ninto a fragment, and include the fragment in the query, like this:\n\n```graphql\nquery UseFragment {\n luke: human(id: \"1000\") {\n ...HumanFragment\n }\n leia: human(id: \"1003\") {\n ...HumanFragment\n }\n}\n\nfragment HumanFragment on Human {\n name\n homePlanet\n}\n```\n\nBoth of those queries give this result:\n\n```json\n{\n \"luke\": {\n \"name\": \"Luke Skywalker\",\n \"homePlanet\": \"Tatooine\"\n },\n \"leia\": {\n \"name\": \"Leia Organa\",\n \"homePlanet\": \"Alderaan\"\n }\n}\n```\n\nThe `UseFragment` and `DuplicateFields` queries will both get the same result,\nbut `UseFragment` is less verbose; if we wanted to add more fields, we could add\nit to the common fragment rather than copying it into multiple places.\n\nWe defined the type system above, so we know the type of each object in the\noutput; the query can ask for that type using the special field `__typename`,\ndefined on every object.\n\n```graphql\nquery CheckTypeOfR2 {\n hero {\n __typename\n name\n }\n}\n```\n\nSince R2-D2 is a droid, this will return\n\n```json\n{\n \"hero\": {\n \"__typename\": \"Droid\",\n \"name\": \"R2-D2\"\n }\n}\n```\n\nThis was particularly useful because `hero` was defined to return a `Character`,\nwhich is an interface; we might want to know what concrete type was actually\nreturned. If we instead asked for the hero of Episode V:\n\n```graphql\nquery CheckTypeOfLuke {\n hero(episode: EMPIRE) {\n __typename\n name\n }\n}\n```\n\nWe would find that it was Luke, who is a Human:\n\n```json\n{\n \"hero\": {\n \"__typename\": \"Human\",\n \"name\": \"Luke Skywalker\"\n }\n}\n```\n\nAs with the type system, this example just scratched the surface of the query\nlanguage. The specification goes into more detail about this topic in the\n\"Language\" section, and the\n[language](https://github.com/graphql/graphql-js/blob/main/src/language)\ndirectory in GraphQL.js contains code implementing a specification-compliant\nGraphQL query language parser and lexer.\n\n### Validation\n\nBy using the type system, it can be predetermined whether a GraphQL query is\nvalid or not. This allows servers and clients to effectively inform developers\nwhen an invalid query has been created, without having to rely on runtime\nchecks.\n\nFor our Star Wars example, the file\n[starWarsValidationTests.js](https://github.com/graphql/graphql-js/blob/main/src/__tests__/starWarsValidation-test.ts)\ncontains a number of demonstrations of invalid operations, and is a test file\nthat can be run to exercise the reference implementation's validator.\n\nTo start, let's take a complex valid query. This is the `NestedQuery` example\nfrom the above section, but with the duplicated fields factored out into a\nfragment:\n\n```graphql\nquery NestedQueryWithFragment {\n hero {\n ...NameAndAppearances\n friends {\n ...NameAndAppearances\n friends {\n ...NameAndAppearances\n }\n }\n }\n}\n\nfragment NameAndAppearances on Character {\n name\n appearsIn\n}\n```\n\nAnd this query is valid. Let's take a look at some invalid queries!\n\nWhen we query for fields, we have to query for a field that exists on the given\ntype. So as `hero` returns a `Character`, we have to query for a field on\n`Character`. That type does not have a `favoriteSpaceship` field, so this query:\n\n```graphql\n# INVALID: favoriteSpaceship does not exist on Character\nquery HeroSpaceshipQuery {\n hero {\n favoriteSpaceship\n }\n}\n```\n\nis invalid.\n\nWhenever we query for a field and it returns something other than a scalar or an\nenum, we need to specify what data we want to get back from the field. Hero\nreturns a `Character`, and we've been requesting fields like `name` and\n`appearsIn` on it; if we omit that, the query will not be valid:\n\n```graphql\n# INVALID: hero is not a scalar, so fields are needed\nquery HeroNoFieldsQuery {\n hero\n}\n```\n\nSimilarly, if a field is a scalar, it doesn't make sense to query for additional\nfields on it, and doing so will make the query invalid:\n\n```graphql\n# INVALID: name is a scalar, so fields are not permitted\nquery HeroFieldsOnScalarQuery {\n hero {\n name {\n firstCharacterOfName\n }\n }\n}\n```\n\nEarlier, it was noted that a query can only query for fields on the type in\nquestion; when we query for `hero` which returns a `Character`, we can only\nquery for fields that exist on `Character`. What happens if we want to query for\nR2-D2s primary function, though?\n\n```graphql\n# INVALID: primaryFunction does not exist on Character\nquery DroidFieldOnCharacter {\n hero {\n name\n primaryFunction\n }\n}\n```\n\nThat query is invalid, because `primaryFunction` is not a field on `Character`.\nWe want some way of indicating that we wish to fetch `primaryFunction` if the\n`Character` is a `Droid`, and to ignore that field otherwise. We can use the\nfragments we introduced earlier to do this. By setting up a fragment defined on\n`Droid` and including it, we ensure that we only query for `primaryFunction`\nwhere it is defined.\n\n```graphql\nquery DroidFieldInFragment {\n hero {\n name\n ...DroidFields\n }\n}\n\nfragment DroidFields on Droid {\n primaryFunction\n}\n```\n\nThis query is valid, but it's a bit verbose; named fragments were valuable above\nwhen we used them multiple times, but we're only using this one once. Instead of\nusing a named fragment, we can use an inline fragment; this still allows us to\nindicate the type we are querying on, but without naming a separate fragment:\n\n```graphql\nquery DroidFieldInInlineFragment {\n hero {\n name\n ... on Droid {\n primaryFunction\n }\n }\n}\n```\n\nThis has just scratched the surface of the validation system; there are a number\nof validation rules in place to ensure that a GraphQL query is semantically\nmeaningful. The specification goes into more detail about this topic in the\n\"Validation\" section, and the\n[validation](https://github.com/graphql/graphql-js/blob/main/src/validation)\ndirectory in GraphQL.js contains code implementing a specification-compliant\nGraphQL validator.\n\n### Introspection\n\nIt's often useful to ask a GraphQL schema for information about what queries it\nsupports. GraphQL allows us to do so using the introspection system!\n\nFor our Star Wars example, the file\n[starWarsIntrospectionTests.js](https://github.com/graphql/graphql-js/blob/main/src/__tests__/starWarsIntrospection-test.ts)\ncontains a number of queries demonstrating the introspection system, and is a\ntest file that can be run to exercise the reference implementation's\nintrospection system.\n\nWe designed the type system, so we know what types are available, but if we\ndidn't, we can ask GraphQL, by querying the `__schema` field, always available\non the root type of a Query. Let's do so now, and ask what types are available.\n\n```graphql\nquery IntrospectionTypeQuery {\n __schema {\n types {\n name\n }\n }\n}\n```\n\nand we get back:\n\n```json\n{\n \"__schema\": {\n \"types\": [\n {\n \"name\": \"Query\"\n },\n {\n \"name\": \"Character\"\n },\n {\n \"name\": \"Human\"\n },\n {\n \"name\": \"String\"\n },\n {\n \"name\": \"Episode\"\n },\n {\n \"name\": \"Droid\"\n },\n {\n \"name\": \"__Schema\"\n },\n {\n \"name\": \"__Type\"\n },\n {\n \"name\": \"__TypeKind\"\n },\n {\n \"name\": \"Boolean\"\n },\n {\n \"name\": \"__Field\"\n },\n {\n \"name\": \"__InputValue\"\n },\n {\n \"name\": \"__EnumValue\"\n },\n {\n \"name\": \"__Directive\"\n }\n ]\n }\n}\n```\n\nWow, that's a lot of types! What are they? Let's group them:\n\n- **Query, Character, Human, Episode, Droid** - These are the ones that we\n defined in our type system.\n- **String, Boolean** - These are built-in scalars that the type system\n provided.\n- **`__Schema`, `__Type`, `__TypeKind`, `__Field`, `__InputValue`,\n `__EnumValue`, `__Directive`** - These all are preceded with a double\n underscore, indicating that they are part of the introspection system.\n\nNow, let's try and figure out a good place to start exploring what queries are\navailable. When we designed our type system, we specified what type all queries\nwould start at; let's ask the introspection system about that!\n\n```graphql\nquery IntrospectionQueryTypeQuery {\n __schema {\n queryType {\n name\n }\n }\n}\n```\n\nand we get back:\n\n```json\n{\n \"__schema\": {\n \"queryType\": {\n \"name\": \"Query\"\n }\n }\n}\n```\n\nAnd that matches what we said in the type system section, that the `Query` type\nis where we will start! Note that the naming here was just by convention; we\ncould have named our `Query` type anything else, and it still would have been\nreturned here if we had specified it as the starting type for queries. Naming it\n`Query`, though, is a useful convention.\n\nIt is often useful to examine one specific type. Let's take a look at the\n`Droid` type:\n\n```graphql\nquery IntrospectionDroidTypeQuery {\n __type(name: \"Droid\") {\n name\n }\n}\n```\n\nand we get back:\n\n```json\n{\n \"__type\": {\n \"name\": \"Droid\"\n }\n}\n```\n\nWhat if we want to know more about Droid, though? For example, is it an\ninterface or an object?\n\n```graphql\nquery IntrospectionDroidKindQuery {\n __type(name: \"Droid\") {\n name\n kind\n }\n}\n```\n\nand we get back:\n\n```json\n{\n \"__type\": {\n \"name\": \"Droid\",\n \"kind\": \"OBJECT\"\n }\n}\n```\n\n`kind` returns a `__TypeKind` enum, one of whose values is `OBJECT`. If we asked\nabout `Character` instead:\n\n```graphql\nquery IntrospectionCharacterKindQuery {\n __type(name: \"Character\") {\n name\n kind\n }\n}\n```\n\nand we get back:\n\n```json\n{\n \"__type\": {\n \"name\": \"Character\",\n \"kind\": \"INTERFACE\"\n }\n}\n```\n\nWe'd find that it is an interface.\n\nIt's useful for an object to know what fields are available, so let's ask the\nintrospection system about `Droid`:\n\n```graphql\nquery IntrospectionDroidFieldsQuery {\n __type(name: \"Droid\") {\n name\n fields {\n name\n type {\n name\n kind\n }\n }\n }\n}\n```\n\nand we get back:\n\n```json\n{\n \"__type\": {\n \"name\": \"Droid\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": {\n \"name\": null,\n \"kind\": \"NON_NULL\"\n }\n },\n {\n \"name\": \"name\",\n \"type\": {\n \"name\": \"String\",\n \"kind\": \"SCALAR\"\n }\n },\n {\n \"name\": \"friends\",\n \"type\": {\n \"name\": null,\n \"kind\": \"LIST\"\n }\n },\n {\n \"name\": \"appearsIn\",\n \"type\": {\n \"name\": null,\n \"kind\": \"LIST\"\n }\n },\n {\n \"name\": \"primaryFunction\",\n \"type\": {\n \"name\": \"String\",\n \"kind\": \"SCALAR\"\n }\n }\n ]\n }\n}\n```\n\nThose are our fields that we defined on `Droid`!\n\n`id` looks a bit weird there, it has no name for the type. That's because it's a\n\"wrapper\" type of kind `NON_NULL`. If we queried for `ofType` on that field's\ntype, we would find the `String` type there, telling us that this is a non-null\nString.\n\nSimilarly, both `friends` and `appearsIn` have no name, since they are the\n`LIST` wrapper type. We can query for `ofType` on those types, which will tell\nus what these are lists of.\n\n```graphql\nquery IntrospectionDroidWrappedFieldsQuery {\n __type(name: \"Droid\") {\n name\n fields {\n name\n type {\n name\n kind\n ofType {\n name\n kind\n }\n }\n }\n }\n}\n```\n\nand we get back:\n\n```json\n{\n \"__type\": {\n \"name\": \"Droid\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": {\n \"name\": null,\n \"kind\": \"NON_NULL\",\n \"ofType\": {\n \"name\": \"String\",\n \"kind\": \"SCALAR\"\n }\n }\n },\n {\n \"name\": \"name\",\n \"type\": {\n \"name\": \"String\",\n \"kind\": \"SCALAR\",\n \"ofType\": null\n }\n },\n {\n \"name\": \"friends\",\n \"type\": {\n \"name\": null,\n \"kind\": \"LIST\",\n \"ofType\": {\n \"name\": \"Character\",\n \"kind\": \"INTERFACE\"\n }\n }\n },\n {\n \"name\": \"appearsIn\",\n \"type\": {\n \"name\": null,\n \"kind\": \"LIST\",\n \"ofType\": {\n \"name\": \"Episode\",\n \"kind\": \"ENUM\"\n }\n }\n },\n {\n \"name\": \"primaryFunction\",\n \"type\": {\n \"name\": \"String\",\n \"kind\": \"SCALAR\",\n \"ofType\": null\n }\n }\n ]\n }\n}\n```\n\nLet's end with a feature of the introspection system particularly useful for\ntooling; let's ask the system for documentation!\n\n```graphql\nquery IntrospectionDroidDescriptionQuery {\n __type(name: \"Droid\") {\n name\n description\n }\n}\n```\n\nyields\n\n```json\n{\n \"__type\": {\n \"name\": \"Droid\",\n \"description\": \"A mechanical creature in the Star Wars universe.\"\n }\n}\n```\n\nSo we can access the documentation about the type system using introspection,\nand create documentation browsers, or rich IDE experiences.\n\nThis has just scratched the surface of the introspection system; we can query\nfor enum values, what interfaces a type implements, and more. We can even\nintrospect on the introspection system itself. The specification goes into more\ndetail about this topic in the \"Introspection\" section, and the\n[introspection](https://github.com/graphql/graphql-js/blob/main/src/type/introspection.ts)\nfile in GraphQL.js contains code implementing a specification-compliant GraphQL\nquery introspection system.\n\n### Additional Content\n\nThis README walked through the GraphQL.js reference implementation's type\nsystem, query execution, validation, and introspection systems. There's more in\nboth [GraphQL.js](https://github.com/graphql/graphql-js/) and specification,\nincluding a description and implementation for executing queries, how to format\na response, explaining how a type system maps to an underlying implementation,\nand how to format a GraphQL response, as well as the grammar for GraphQL.\n\n### Contributing to this repo\n\nThis repository is managed by EasyCLA. Project participants must sign the free\n([GraphQL Specification Membership agreement](https://preview-spec-membership.graphql.org)\nbefore making a contribution. You only need to do this one time, and it can be\nsigned by\n[individual contributors](https://individual-spec-membership.graphql.org/) or\ntheir [employers](https://corporate-spec-membership.graphql.org/).\n\nTo initiate the signature process please open a PR against this repo. The\nEasyCLA bot will block the merge if we still need a membership agreement from\nyou.\n\nYou can find\n[detailed information here](https://github.com/graphql/graphql-wg/tree/main/membership).\nIf you have issues, please email\n[operations@graphql.org](mailto:operations@graphql.org).\n\nIf your company benefits from GraphQL and you would like to provide essential\nfinancial support for the systems and people that power our community, please\nalso consider membership in the\n[GraphQL Foundation](https://foundation.graphql.org/join).\n" }, { "path": "STYLE_GUIDE.md", "content": "**This document is a work in progress.**\n\n# GraphQL Specification Style Guide\n\nThis document outlines the styles used in the GraphQL spec to aid editorial and\nconsistency. The writing style portions are inspired by the AP style guide. When\nmaking changes to the GraphQL specification, please aim to be consistent with\nthis style guide.\n\n## Auto-Formatting\n\nThe GraphQL specification is formatted using the `prettier` tool, so you should\nnot need to think about gaps between paragraphs and titles, nor about word\nwrapping - this is handled for you.\n\n## Headings\n\nThe GraphQL specification uses two types of headings: numbered headings and\nunnumbered headings. All headings should be written in Title Case (see below).\n\n### Numbered Headings\n\nLines beginning with a `#` will become numbered headings in the spec-md output.\n\n```\n# H1\n## H2\n### H3\n#### H4\n##### H5\n```\n\n### Unnumbered Headings\n\nUnnumbered headings are added to split large blocks of text up without impacting\nthe spec numbering system. In the output are styled similarly to an H4. An\nunnumbered heading is a line on its own that is bolded:\n\n```md\n\\*\\*This Is an Example of an Unnumbered Heading\\*\\*\n```\n\n### Title Case\n\nTitle case is used for headings. Every word in a heading (including words after\nhyphens) should be capitalized, with the following exceptions:\n\n- articles: a, an, the\n- conjunctions under 4 letters in length: for, and, nor, but, or, yet, so, as,\n if\n- prepositions under 4 letters in length: in, at, to, on, off, of, for, vs., per\n- directive names and type names are unchanged: @include, @specifiedBy,\n \\_\\_EnumValue, \\_\\_Schema\n\nAll elements in hyphenated words follow the same rules, e.g. headings may\ncontain `Non-Null`, `Context-Free`, `Built-in` (`in` is a preposition, so is not\ncapitalized).\n\n## Algorithms\n\nA named algorithm definition starts with the name of the algorithm in\n`PascalCase`, an open parenthesis, a comma-and-space separated list of\narguments, a close parenthesis and then a colon. It is followed by a blank\nnewline and a list of steps in the algorithm which may be numbered or bulleted.\n\nEach step in an algorithm should either end in a colon (`:`) with an indented\nstep on the next line, or a fullstop (`.`). (A step after a step ending in a\nfull stop may or may not be indented, use your discretion.)\n\nIndentation in algorithms is significant.\n\nEvery step in an algorithm should start with a capital letter.\n\n```\nMyAlgorithm(argOne, argTwo):\n\n- Let {something} be {true}.\n- For each {arg} in {argOne}:\n - If {arg} is greater than {argTwo}:\n - Let {something} be {false}.\n - Otherwise if {arg} is less than {argTwo}:\n - Let {something} be {true}.\n- Return {something}.\n```\n\n## Definitions\n\nFor important terms, use\n[Spec Markdown definition paragraphs](https://spec-md.com/#sec-Definition-Paragraph).\n\nDefinition paragraphs start with `::` and add the matching italicized term to\nthe [specification index](https://spec.graphql.org/draft/#index), making it easy\nto reference them.\n\n## Tone of Voice\n\nThe GraphQL specification is a reference document and should use neutral and\ndescriptive tone of voice.\n\n**Favor the present tense**\n\nThe present tense is usually clearer and shorter:\n\n✅ Present: The client then sends a request to the server.\n\n❌ Future: The client will then send a request to the server.\n\n**Write in the third person**\n\nThe specification should avoid the first person (“we,” “our”) and instead use\nthe third person or passive constructions when necessary. For example:\n\n✅ “The server validates the request against the schema.”\n\n❌ “We validate the request against the schema.”\n\n**Use RFC 2119 keywords**\n\nThe specification should use the normative keywords defined in\n[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) (**MUST**, **MUST NOT**,\n**SHOULD**, **SHOULD NOT**, **MAY**). However, in the context of a sentence\nthese words should be lower-cased (e.g., “must,” “should,” “may”) in context of\na sentence. This avoids unnecessary visual emphasis while preserving normative\nmeaning.\n\n✅ “A query must contain a single root operation type.”\n\n❌ “A query MUST contain a single root operation type.”\n\n**Avoid unnecessary hyphenation**\n\nOnly use hypenated compound words when either commonly used elsewhere in english\nor technical writing. Otherwise prefer separate words or a non-hyphenated\ncompound word, whichever is most commonly accepted.\n\n✅ User defined shorthand words are separated by whitespace\n\n❌ User-defined short-hand words are separated by white-space\n" }, { "path": "build.sh", "content": "#!/bin/bash -e\n# This script publishes the GraphQL specification document to the web.\n\n# Determine if this is a tagged release\nGITTAG=$(git tag --points-at HEAD)\n\n# Build the specification draft document\necho \"Building spec draft\"\nmkdir -p public/draft\nspec-md --metadata spec/metadata.json --githubSource \"https://github.com/graphql/graphql-spec/blame/main/\" spec/GraphQL.md > public/draft/index.html\n\n# If this is a tagged commit, also build the release document\nif [ -n \"$GITTAG\" ]; then\n echo \"Building spec release $GITTAG\"\n mkdir -p \"public/$GITTAG\"\n spec-md --metadata spec/metadata.json --githubSource \"https://github.com/graphql/graphql-spec/blame/$GITTAG/\" spec/GraphQL.md > \"public/$GITTAG/index.html\"\nfi\n\n# Create the index file\necho \"Rebuilding: / (index)\"\nHTML=\"\n \n GraphQL Specification Versions\n \n \n \n

GraphQL

\n \"\n\n# Include latest draft\nGITDATE=$(git show -s --format=%cd --date=format:\"%a, %b %-d, %Y\" HEAD)\nHTML=\"$HTML\n \n \n \n \n \n \"\n\nGITHUB_RELEASES=\"https://github.com/graphql/graphql-spec/releases/tag\"\nfor GITTAG in $(git tag -l --sort='-*committerdate') ; do\n VERSIONYEAR=${GITTAG: -4}\n TAGTITLE=\"${GITTAG%$VERSIONYEAR} $VERSIONYEAR\"\n TAGGEDCOMMIT=$(git rev-list -1 \"$GITTAG\")\n GITDATE=$(git show -s --format=%cd --date=format:\"%a, %b %-d, %Y\" $TAGGEDCOMMIT)\n\n HTML=\"$HTML\n \"\n\n [ -z $HAS_LATEST_RELEASE ] && HTML=\"$HTML\n \" || HTML=\"$HTML\n \"\n HAS_LATEST_RELEASE=1\n\n HTML=\"$HTML\n \n \n \n \"\ndone\n\nHTML=\"$HTML\n
PrereleaseWorking Draft$GITDATE
Latest Release$TAGTITLE$GITDATERelease Notes
\n \n \n\"\n\necho $HTML > \"public/index.html\"\n" }, { "path": "changelogs/October2021.md", "content": "# October2021 Changelog\n\nThis describes the set of changes since the last edition of the GraphQL\nspecification, [June2018](https://spec.graphql.org/June2018/). It's intended to\nease the review of changes since the last edition for reviewers or curious\nreaders, but is not normative. Please read the\n[specification document](https://spec.graphql.org/October2021/) itself for full detail\nand context.\n\n## Authors\n\nWhile many have participated in the design and review RFC process, this is the\nset of authors and RFC champions who have committed directly to the\nspecification text in this edition:\n\n| Author |\n| ------------------------------- |\n| [ab-pm] |\n| [Andreas Marek] |\n| [Antoine Boyer] |\n| [António Nuno Monteiro] |\n| [Arun Ponniah Sethuramalingam] |\n| [Benedikt Franke] |\n| [Benjie Gillam] |\n| [Brian Warner] |\n| [Chris Brown] |\n| [David Glasser] |\n| [dugenkui] |\n| [Edwin Shin] |\n| [Evan Huus] |\n| [Grant Wu] |\n| [Görcsös Zoltán] |\n| [Ivan Goncharov] |\n| [Ivan Maximov] |\n| [James Scott] |\n| [Jamie Schouten] |\n| [Joe Duarte] |\n| [Kei Kamikawa] |\n| [Lee Byron] |\n| [Loren Sands-Ramshaw] |\n| [Marais Rossouw] |\n| [Marc Knaup] |\n| [Martin Bonnin] |\n| [Matt Farmer] |\n| [Matt Mahoney] |\n| [Michael Joseph Rosenthal] |\n| [Mike Marcacci] |\n| [Matthias Prechtl] |\n| [Pascal Senn] |\n| [Sebastian Redl] |\n| [Tejas Kumar] |\n| [Oleg Ilyenko] |\n\n[ab-pm]: https://github.com/ab-pm\n[Andreas Marek]: https://github.com/andimarek\n[Antoine Boyer]: https://github.com/tinnou\n[António Nuno Monteiro]: https://github.com/anmonteiro\n[Arun Ponniah Sethuramalingam]: https://github.com/saponniah\n[Benedikt Franke]: https://github.com/spawnia\n[Benjie Gillam]: https://github.com/benjie\n[Brian Warner]: https://github.com/brianwarner\n[Chris Brown]: https://github.com/ccbrown\n[David Glasser]: https://github.com/glasser\n[dugenkui]: https://github.com/dugenkui03\n[Edwin Shin]: https://github.com/eddies\n[Evan Huus]: https://github.com/eapache\n[Grant Wu]: https://github.com/grantwwu\n[Görcsös Zoltán]: https://github.com/zgorcsos\n[Ivan Goncharov]: https://github.com/IvanGoncharov\n[Ivan Maximov]: https://github.com/sungam3r\n[James Scott]: https://github.com/scottydocs\n[Jamie Schouten]: https://github.com/maantje\n[Joe Duarte]: https://github.com/JoeUX\n[Kei Kamikawa]: https://github.com/Code-Hex\n[Lee Byron]: https://github.com/leebyron\n[Loren Sands-Ramshaw]: https://github.com/lorensr\n[Marais Rossouw]: https://github.com/maraisr\n[Marc Knaup]: https://github.com/fluidsonic\n[Martin Bonnin]: https://github.com/martinbonnin\n[Matt Farmer]: https://github.com/m14t\n[Matt Mahoney]: https://github.com/mjmahone\n[Michael Joseph Rosenthal]: https://github.com/micimize\n[Mike Marcacci]: https://github.com/mike-marcacci\n[Matthias Prechtl]: https://github.com/matprec\n[Pascal Senn]: https://github.com/PascalSenn\n[Sebastian Redl]: https://github.com/CornedBee\n[Tejas Kumar]: https://github.com/TejasQ\n[Oleg Ilyenko]: https://github.com/OlegIlyenko\n\nGenerated with:\n\n```sh\ngit log June2018..HEAD --format=\"%an <%ae>%x0A%(trailers:key=Co-authored-by,valueonly)\" -- spec | sort -uf\n```\n\n## Changes\n\nListed in reverse-chronological order (latest commit on top).\n\n| Hash | Change | Authors |\n| ---- | ------ | ------- |\n| [ae1bab6](https://github.com/graphql/graphql-spec/commit/ae1bab6ff27cc331fc17c10af14ddd6b01512bf9) | Fix typo in Handling Field Errors (#876) | Antoine Boyer \n| [fdeb37d](https://github.com/graphql/graphql-spec/commit/fdeb37d4c9528c44c3834913944880dce9f4e8bd) | Updated legal copy (#869) | [Lee Byron], [Brian Warner]\n| [50bbaa8](https://github.com/graphql/graphql-spec/commit/50bbaa8bb2503ef9b3c3477d53b266c9e8205a31) | Editorial: Improve Introspection section (#857) | [Lee Byron], [Ivan Maximov], [Benjie Gillam]\n| [debcdc3](https://github.com/graphql/graphql-spec/commit/debcdc381b6173adbb89a800fd2a0009a3df8568) | Improve clarity of built-in directives (#633) | [Ivan Maximov], [Lee Byron]\n| [5b7b9f6](https://github.com/graphql/graphql-spec/commit/5b7b9f6415ec9861032ced3f061d6fab1406f376) | Add spellcheck to test suite (#858) | [Lee Byron]\n| [086bb1f](https://github.com/graphql/graphql-spec/commit/086bb1f1a7f273b6d0787de525f1c23742374ae0) | Editorial: Define 'Schema Specification URL' (#856) | [Lee Byron]\n| [40d025c](https://github.com/graphql/graphql-spec/commit/40d025ce5cb681454c0f6455c4d97e38313616d2) | fixed introspection field \"specifiedBy\" to \"specifiedByURL\" (#848) | [Kei Kamikawa], [Lee Byron]\n| [61c50f2](https://github.com/graphql/graphql-spec/commit/61c50f28cb247539e4da930b5553d25ac3d8c792) | clarify that utf-8 is just a possible encoding of strings (#684) | [Andreas Marek], [Lee Byron]\n| [d4777b4](https://github.com/graphql/graphql-spec/commit/d4777b428030347300f98873b5a760b5e29ae726) | Editorial: StringValue (#854) | [Lee Byron]\n| [413b689](https://github.com/graphql/graphql-spec/commit/413b68974ef86b6cc8a9272bbc8360762eee3479) | RFC: __typename is not valid at subscription root (#776) | [Benjie Gillam], [Lee Byron]\n| [9bb7b77](https://github.com/graphql/graphql-spec/commit/9bb7b777d0a5de26d94bb0e2993fdd4e22c13443) | Fix: Syntax highlighting in example (#851) | [Lee Byron]\n| [c6eb911](https://github.com/graphql/graphql-spec/commit/c6eb91110f6f80550f8cac1c69de1c7808b93a21) | make clear that some String escape sequences are optional (#686) | [Andreas Marek], [Lee Byron]\n| [044d1d4](https://github.com/graphql/graphql-spec/commit/044d1d459d5ed289a66422cc3a996a9265fe8efa) | Clarity in Section 3 (#847) | [Ivan Maximov]\n| [a16d249](https://github.com/graphql/graphql-spec/commit/a16d2493f72020f63f3e689d61420c35944c953c) | State that built-in mandatory directives must be omitted (#816) | [Marais Rossouw], [Lee Byron]\n| [d4a865a](https://github.com/graphql/graphql-spec/commit/d4a865adada9c78924cf29e1bc86d6ff6bcc5f15) | [RFC] Custom Scalar Specification URLs (#649) | [Evan Huus], [Matt Farmer], [Lee Byron]\n| [9ec15e3](https://github.com/graphql/graphql-spec/commit/9ec15e365933caff4894aa640ac4c55f9f78e2de) | Spec edits to reduce \"query ambiguity\" (#777) | [Benjie Gillam], [Lee Byron]\n| [f474e66](https://github.com/graphql/graphql-spec/commit/f474e666d6698f6fd061fafad862b977834a3d5b) | Editorial: Clarify meta-fields in introspection (#844) | [Lee Byron], [Benjie Gillam]\n| [f8b75d3](https://github.com/graphql/graphql-spec/commit/f8b75d30970c75007f4418bf3e79112d65c2f187) | Editorial: Clarify document grammar rules (#840) | [Lee Byron]\n| [0062610](https://github.com/graphql/graphql-spec/commit/0062610494be356b033b933023829fdbc7149a96) | Add CoerceResult() (#836) | [Lee Byron]\n| [792671b](https://github.com/graphql/graphql-spec/commit/792671bcfc3d451514213b5f57d0f3dbe9068a9b) | __Type represents all types in the system (#775) | [Benjie Gillam], [Lee Byron]\n| [d616285](https://github.com/graphql/graphql-spec/commit/d616285dad370ca4cf126482052e313a24249e1e) | Avoid parse ambiguity on type extensions (#598) | [Lee Byron]\n| [adee896](https://github.com/graphql/graphql-spec/commit/adee896e83a01ba065e13df360d61eea225f2b8b) | Update 'Field Collection' explanation (#765) | [dugenkui]\n| [c43d2f7](https://github.com/graphql/graphql-spec/commit/c43d2f7c8e706442662ccf95e6b7eaaeeab4b878) | Editorial: Clarify field aliases (#843) | [Lee Byron]\n| [29bcc26](https://github.com/graphql/graphql-spec/commit/29bcc26766d7f62560bb5d760b39b14bc80063c4) | Editorial: Refine design principles (#839) | [Lee Byron]\n| [567e05c](https://github.com/graphql/graphql-spec/commit/567e05cfa5fbe1405c652c5db0b4b65eca431cb1) | Editorial: Query shorthand (#841) | [Lee Byron]\n| [2c2cea7](https://github.com/graphql/graphql-spec/commit/2c2cea7327fe8c01a819f7bf9ea9c9454e4946af) | Editorial: root types (#842) | [Lee Byron]\n| [080c8b6](https://github.com/graphql/graphql-spec/commit/080c8b669967ccaa5021b9b5b1278807cbfe9c7a) | Editorial: clarify input object introspection (#838) | [Lee Byron]\n| [9cb9a4b](https://github.com/graphql/graphql-spec/commit/9cb9a4b25ea975b4affbea6676cf857f8eb43967) | Replace 'query error' with 'request error' (#803) | [Benjie Gillam], [Lee Byron]\n| [6dbef35](https://github.com/graphql/graphql-spec/commit/6dbef35869abbc10d7b3e3aef073ed0ebd1bf52c) | Clarify that Float does not include NaN or infinity (#780) | [David Glasser], [Lee Byron]\n| [b47598f](https://github.com/graphql/graphql-spec/commit/b47598f49264d7018ef2c07e2dfc21b3e0503420) | Prettier pre-work: formatting tweaks (#832) | [Benjie Gillam], [Lee Byron]\n| [d716d84](https://github.com/graphql/graphql-spec/commit/d716d84263a428c3e7f45962a2ed66a5e063d5d9) | Rename references from master to main (#835) | [Lee Byron]\n| [f331650](https://github.com/graphql/graphql-spec/commit/f3316502285e46d7b9bea17e895ce79bfcb771e9) | Clarify how lexical tokens are separated (#748) | [Joe Duarte]\n| [7546566](https://github.com/graphql/graphql-spec/commit/7546566bc8a9b3992e87c0a2656dab85319b3264) | fix spelling (#834) | [Lee Byron]\n| [bed0a19](https://github.com/graphql/graphql-spec/commit/bed0a193436af5e3fc89b9a21a90debf7f5663a7) | Formatting: use markdown lists in 'one of' lists (#726) | [Benjie Gillam]\n| [d24252b](https://github.com/graphql/graphql-spec/commit/d24252b82637a1deab3c3b8b07ce6bb3b3fda331) | Add definition of selectionSet to CreateSourceEventStream (#828) | [Benjie Gillam]\n| [83b638f](https://github.com/graphql/graphql-spec/commit/83b638f0ec93cebf4d85997e3b49479a56aa051a) | Renumber list items (#824) | [Benjie Gillam]\n| [d248f55](https://github.com/graphql/graphql-spec/commit/d248f551bd84042cfba1b48b95848f06dee36ea8) | Editorial: Clean trailing whitespace (#813) | [Lee Byron]\n| [eb86ed9](https://github.com/graphql/graphql-spec/commit/eb86ed92bd89b6d58f25d39e6c6e8cb82620b8c9) | Disallow non-breakable chains of circular references in Input Objects (#701) | [Benedikt Franke], [Lee Byron]\n| [c83baf6](https://github.com/graphql/graphql-spec/commit/c83baf6efb3abb0faeb55d118324704f3ce2c1f2) | Editorial: s/server/service (#811) | [Lee Byron]\n| [d3ea511](https://github.com/graphql/graphql-spec/commit/d3ea51147c2c00c4da21cf0b624bf055dd45a02d) | Add missing VARIABLE DEFINITION (#761) | [dugenkui]\n| [39caf61](https://github.com/graphql/graphql-spec/commit/39caf613baab565d42385a7ba2e643eaaa275e9b) | Clarify that __typename may be queried on unions (#756) | [David Glasser]\n| [657bc69](https://github.com/graphql/graphql-spec/commit/657bc69cc834a66350ebaaa68263d6fad716f1b5) | Minor grammar fixes (#728) | [Loren Sands-Ramshaw]\n| [41dc593](https://github.com/graphql/graphql-spec/commit/41dc593687768af447b70ee82bd7d92f5f7d7e82) | Add explicit example to allow nesting lists within lists (#755) | [Benedikt Franke]\n| [73fc593](https://github.com/graphql/graphql-spec/commit/73fc59385f5bcbc6bec4c011eedf18aff1e127b7) | Make 'Field Selections' header stable (#773) | [Benjie Gillam]\n| [abed779](https://github.com/graphql/graphql-spec/commit/abed7797820657f0ecc75e04418115ff5bd33561) | Small grammar fix (#762) | [Martin Bonnin]\n| [2e5aa78](https://github.com/graphql/graphql-spec/commit/2e5aa786d30fb13f2992d71d154b4320cbcec114) | fix typo (#747) | [Andreas Marek]\n| [2d67b69](https://github.com/graphql/graphql-spec/commit/2d67b696256c90e0772823f73ae9e8fd60aa4e7c) | Fix typo in Input Objects (#741) | [dugenkui]\n| [05d4a3b](https://github.com/graphql/graphql-spec/commit/05d4a3be4ed8bad274209c6f855d895f824949c2) | fix __Type explanation (#737) | [dugenkui]\n| [c976d31](https://github.com/graphql/graphql-spec/commit/c976d31311bdcc0590c930a3da45b9b78201fb68) | Fix typo in CollectFields (#732) | [Benjie Gillam]\n| [6c9e13b](https://github.com/graphql/graphql-spec/commit/6c9e13b2281b6e30a630d334fea90d389e9099cb) | [Variables] Generalize description | [Michael Joseph Rosenthal]\n| [e5c31c9](https://github.com/graphql/graphql-spec/commit/e5c31c9d8c4439d06c858ec22fde7158509283bb) | Fix 'Format' / 'Formal' typo; fix another header | [Benjie Gillam]\n| [0b3c0fa](https://github.com/graphql/graphql-spec/commit/0b3c0fa7b57dd6087cc7b2b31fe7af8be54d3b23) | Section headers for formal specifications | [Benjie Gillam]\n| [a0de4c5](https://github.com/graphql/graphql-spec/commit/a0de4c5cc158083b98f5002d6016118c28f42557) | [Editorial] Fix example for Variable Uniqueness (#703) | [Pascal Senn]\n| [2bd2d01](https://github.com/graphql/graphql-spec/commit/2bd2d0197ee2780aa7f5895a1d06f8d64f9e83dd) | [grammar] add \"the \" to Type Condition section (#712) | [Michael Joseph Rosenthal]\n| [ef4bbca](https://github.com/graphql/graphql-spec/commit/ef4bbca9a49999947b6d3b319addc422d47fc18e) | [Editorial]: Use non-null for if variable in @skip and @include (#722) | [Loren Sands-Ramshaw]\n| [02fd71f](https://github.com/graphql/graphql-spec/commit/02fd71f816139b7e040f969860778d23df288d32) | Add description to Schema (#466) | [Ivan Goncharov]\n| [3b001da](https://github.com/graphql/graphql-spec/commit/3b001da015a4b55331b534327a9ad74eb2e6d744) | Grammar: Add missing ImplementsInterface to Interface rules | [Ivan Maximov]\n| [8ac091a](https://github.com/graphql/graphql-spec/commit/8ac091a4e0232def801dd8dfc6da208c3e7e347f) | Update draft URL | [Lee Byron]\n| [e297e92](https://github.com/graphql/graphql-spec/commit/e297e9254bc7649ee0063164d7f3395425159e26) | RFC: Allow interfaces to implement other interfaces (#373) | [Mike Marcacci], [Lee Byron]\n| [97db7cd](https://github.com/graphql/graphql-spec/commit/97db7cd2bdff15c4d195141065fa2bfb41816f60) | [editorial] Fix formatting of algorithms in Validation section (#671) | [Lee Byron]\n| [4d55742](https://github.com/graphql/graphql-spec/commit/4d55742ff4f9d18a722d31846bea3ea63cf7971f) | [editorial] Localized note about order of skip and include directives (#669) | [Lee Byron]\n| [be33a64](https://github.com/graphql/graphql-spec/commit/be33a640a8d12eb177f7cce0c61a1fad770a3430) | [RFC] Repeatable directives (#472) | [Oleg Ilyenko], [Lee Byron], [Benedikt Franke]\n| [39f7a34](https://github.com/graphql/graphql-spec/commit/39f7a34e7af99de345ca344f9e6645ed8a6bc3f7) | Improve clarity of scalar types (#597) | [Lee Byron]\n| [8ada467](https://github.com/graphql/graphql-spec/commit/8ada467ed5bc3b72ccd42508f5bb56a7ef3b1328) | Fixed that `CoerceArgumentValues` refers to `variableType` (#659) | [Marc Knaup]\n| [09cdaec](https://github.com/graphql/graphql-spec/commit/09cdaecf3a4d08c9c53092ce83b0dede40adcba6) | RFC: Number value literal lookahead restrictions (#601) | [Lee Byron]\n| [a73cd6f](https://github.com/graphql/graphql-spec/commit/a73cd6fef02d16483cb5f9c1f7f6d81db3c46584) | Clarify lexing is greedy with lookahead restrictions. (#599) | [Lee Byron]\n| [e491220](https://github.com/graphql/graphql-spec/commit/e49122000599567bea17ad6eecf50ad17fa60693) | Added missing parameter in call to CollectFields() (#658) | [Marc Knaup]\n| [bce8020](https://github.com/graphql/graphql-spec/commit/bce80208054cb1aaf7b9f9f513270ba413054da3) | [RFC] Add note recommending directive names to be namespaced (#657) | [Antoine Boyer], [Lee Byron]\n| [43a5826](https://github.com/graphql/graphql-spec/commit/43a58263fe69e6c016964848a8cf6eab3c69faaf) | Update copyright and URLs from Facebook to GraphQL Foundation (#637) | [Lee Byron]\n| [bb95aa5](https://github.com/graphql/graphql-spec/commit/bb95aa5c4023cc3cf04fb3450f894300db77d846) | fixed #613 (#614) | [Ivan Maximov]\n| [b967f46](https://github.com/graphql/graphql-spec/commit/b967f46a6d34c8ea45b85ff6b7c97cbcfdcf02c9) | remove redundant step from SameResponseShape (#602) | [Chris Brown]\n| [7ca239c](https://github.com/graphql/graphql-spec/commit/7ca239c01eb7cb950d36eebc3f341fa9a9deeb4b) | \"Directive order is significant\" section (#470) | [Oleg Ilyenko]\n| [7237443](https://github.com/graphql/graphql-spec/commit/72374434452fc05ace73d5c5d4287e047e939ae0) | Editorial: Fix reference to StringValue from Ignored (#608) | [Lee Byron]\n| [5cc1424](https://github.com/graphql/graphql-spec/commit/5cc14241511d193d2ba2c7dc95b7808e088b0caa) | values of correct type grammar fix (#603) | [Chris Brown]\n| [663a18b](https://github.com/graphql/graphql-spec/commit/663a18bbcda0a8686a7bb51b1699aa997a488cb1) | Grammar fix in section 3 (#605) | [ab-pm]\n| [6de9b65](https://github.com/graphql/graphql-spec/commit/6de9b654e8cd559978f8cdf5dee64a06cb054e28) | fix ExecuteField usage arguments (#607) | [Chris Brown]\n| [dfd7571](https://github.com/graphql/graphql-spec/commit/dfd75718042806733e779930fbcebd6b02bb2106) | Editorial: Make grammar recursion more clear (#593) | [Lee Byron]\n| [a3087c2](https://github.com/graphql/graphql-spec/commit/a3087c262022adf6a767d1cf644bc5594eb4eb14) | Remove contradictory language (#535) | [Grant Wu]\n| [6b19129](https://github.com/graphql/graphql-spec/commit/6b19129b984faccf97b31356c3ebdc0d16c8e6d4) | Synchronise grammar rules across the spec (#538) | [Ivan Goncharov]\n| [c7bface](https://github.com/graphql/graphql-spec/commit/c7bface58bf6f58cc809f279cba1b6245de914b4) | Update spec/Section 4 -- Introspection.md (#524) | [Görcsös Zoltán]\n| [69f2bd4](https://github.com/graphql/graphql-spec/commit/69f2bd4740191b1917296d55fe08e07922123c57) | Fix grammar in Section 3 -- Type System.md (#546) | [Edwin Shin]\n| [a9b186a](https://github.com/graphql/graphql-spec/commit/a9b186adf178fde9eaba0db2c2abfe05bd3caad5) | Introspection: Clarify nullability of fields in `__Type` type (#536) | [Ivan Goncharov]\n| [f18c922](https://github.com/graphql/graphql-spec/commit/f18c92232e7c7a17402abc8e427ab77ec7901eaa) | Fix ambiguity about optional variables in non-null args (#520) | [Lee Byron]\n| [51337d6](https://github.com/graphql/graphql-spec/commit/51337d6d038b094bc9598e15674d91b80ceca315) | Add missing '&' to Punctuator production (graphql#573) (#574) | [Sebastian Redl]\n| [b79c7f7](https://github.com/graphql/graphql-spec/commit/b79c7f760b039f5c924da2a40107b70ee08fc1dd) | Added missing 'a' to section on 'Descriptions' (#527) | [James Scott]\n| [7133b59](https://github.com/graphql/graphql-spec/commit/7133b599a42507734ea0e983e2aa59003951a583) | Add example of negative integer coercion to ID (#480) | [Ivan Goncharov]\n| [760753e](https://github.com/graphql/graphql-spec/commit/760753edc3588923b8ee8e9885dadc22e478b911) | [RFC] Allow directives on variable definitions (#510) | [Matt Mahoney]\n| [1278654](https://github.com/graphql/graphql-spec/commit/1278654d9bef295c56c08c1c0f63d4056b611e89) | Editorial changes on the spec document. (#493) | [Arun Ponniah Sethuramalingam]\n| [b83ca98](https://github.com/graphql/graphql-spec/commit/b83ca9802f2d23a23d4cf2385d05b12cfd83896c) | Change scheme for URLs from http to https where https is available. (#504) | [Jamie Schouten]\n| [4efbbc0](https://github.com/graphql/graphql-spec/commit/4efbbc0a091448ab2914dc6e255e0f4d5026f5dd) | Correct description of directive example (#506) | [António Nuno Monteiro]\n| [1884f41](https://github.com/graphql/graphql-spec/commit/1884f4140c012063c1367edce466d5d7dbf187c1) | Fix grammar (#514) | [Ivan Goncharov]\n| [4a70722](https://github.com/graphql/graphql-spec/commit/4a707222431fb68bbf649aaf7350c4dcca7c9c4d) | Revert \"[RFC] Allow directives on variable definitions\" (#492) | [Lee Byron]\n| [b7b6a0b](https://github.com/graphql/graphql-spec/commit/b7b6a0b3c898b20395d58dd6414465a208fca440) | Move to after DefaultValue, and make [Const] | [Matt Mahoney]\n| [98ffe21](https://github.com/graphql/graphql-spec/commit/98ffe217ff4fef3a6d20159ac3d96820915fa955) | [RFC] Allow directives on variable definitions | [Matt Mahoney]\n| [1ee42ce](https://github.com/graphql/graphql-spec/commit/1ee42ceb453c124173615f98d0c90506f2345f9d) | Change values of x, y in example 121 (#468) | [Matthias Prechtl]\n| [8ee3cc7](https://github.com/graphql/graphql-spec/commit/8ee3cc72c3141568f612dac3b66b3881f023b5ef) | Update Section 6 -- Execution.md (#469) | [Tejas Kumar]\n| [b095b18](https://github.com/graphql/graphql-spec/commit/b095b18ff8c2f0f11b9fd33a8fdf2d95241fff28) | Start next working draft for future release | Travis CI\n\nGenerated with:\n\n```sh\ngit log June2018..HEAD --format=\"| [%h](https://github.com/graphql/graphql-spec/commit/%H) | %s | %an <%ae> %(trailers:key=Co-authored-by,valueonly,separator=%x20)\" -- spec\n```\n\n## Diff\n\n### spec/GraphQL.md\n\n
\nspec/GraphQL.md\n\n~~~diff\n@@ -1,51 +1,72 @@\n-GraphQL\n--------\n+# GraphQL\n\n-*June 2018 Edition*\n+*October 2021 Edition*\n\n **Introduction**\n\n This is the specification for GraphQL, a query language and execution engine\n originally created at Facebook in 2012 for describing the capabilities and\n requirements of data models for client-server applications. The development of\n-this open standard started in 2015.\n+this open standard started in 2015. This specification was licensed under OWFa\n+1.0 in 2017. The [GraphQL Foundation](https://graphql.org/foundation/) was\n+formed in 2019 as a neutral focal point for organizations who support the\n+GraphQL ecosystem, and the\n+[GraphQL Specification Project](https://graphql.org/community/) was established\n+also in 2019 as the Joint Development Foundation Projects, LLC, GraphQL Series.\n+\n+If your organization benefits from GraphQL, please consider\n+[becoming a member](https://graphql.org/foundation/join/#graphql-foundation)\n+and helping us to sustain the activities that support the health of our neutral\n+ecosystem.\n+\n+The GraphQL Specification Project has evolved and may continue to evolve in\n+future editions of this specification. Previous editions of the GraphQL\n+specification can be found at permalinks that match their\n+[release tag](https://github.com/graphql/graphql-spec/releases). The latest\n+working draft release can be found at\n+[https://spec.graphql.org/draft](https://spec.graphql.org/draft).\n\n-GraphQL has evolved and may continue to evolve in future editions of this\n-specification. Previous editions of the GraphQL specification can be found at\n-permalinks that match their [release tag](https://github.com/facebook/graphql/releases).\n-The latest working draft release can be found at [facebook.github.io/graphql/draft/](http://facebook.github.io/graphql/draft/).\n\n **Copyright notice**\n\n-Copyright © 2015-present, Facebook, Inc.\n+Copyright © 2015-2018, Facebook, Inc.\n\n-As of September 26, 2017, the following persons or entities have made this\n-Specification available under the Open Web Foundation Final Specification\n-Agreement (OWFa 1.0), which is available at [openwebfoundation.org](http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0).\n+Copyright © 2019-present, GraphQL contributors\n\n-* Facebook, Inc.\n-\n-You can review the signed copies of the Open Web Foundation Final Specification\n-Agreement Version 1.0 for this specification at [github.com/facebook/graphql](https://github.com/facebook/graphql/tree/master/signed-agreements),\n-which may also include additional parties to those listed above.\n-\n-Your use of this Specification may be subject to other third party rights.\n-THIS SPECIFICATION IS PROVIDED “AS IS.” The contributors expressly disclaim any\n+THESE MATERIALS ARE PROVIDED “AS IS.” The parties expressly disclaim any\n warranties (express, implied, or otherwise), including implied warranties of\n merchantability, non-infringement, fitness for a particular purpose, or title,\n-related to the Specification. The entire risk as to implementing or otherwise\n-using the Specification is assumed by the Specification implementer and user.\n-IN NO EVENT WILL ANY PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY\n-FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER\n-FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS SPECIFICATION OR ITS\n-GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING\n-NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED\n-OF THE POSSIBILITY OF SUCH DAMAGE.\n+related to the materials. The entire risk as to implementing or otherwise using\n+the materials is assumed by the implementer and user. IN NO EVENT WILL THE\n+PARTIES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT,\n+SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES\n+OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING\n+AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR\n+OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE\n+POSSIBILITY OF SUCH DAMAGE.\n+\n+\n+**Licensing**\n+\n+The GraphQL Specification Project is made available by the\n+[Joint Development Foundation](https://www.jointdevelopment.org/). The current\n+[Working Group](https://github.com/graphql/graphql-wg) charter, which includes\n+the IP policy governing all working group deliverables (including specifications,\n+source code, and datasets) may be found at\n+[https://technical-charter.graphql.org](https://technical-charter.graphql.org).\n+\n+Currently, the licenses governing GraphQL Specification Project deliverables are:\n+\n+| Deliverable | License |\n+| -------------- | ------------------------------------------------------- |\n+| Specifications | [Open Web Foundation Agreement 1.0 Mode](http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0) (Patent and Copyright)\n+| Source code | [MIT License](https://opensource.org/licenses/MIT)\n+| Data sets | [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)\n\n\n **Conformance**\n\n A conforming implementation of GraphQL must fulfill all normative requirements.\n Conformance requirements are described in this document via both\n descriptive assertions and key words with clearly defined meanings.\n\n~~~\n
\n\n
\nspec/Section 1 -- Overview.md\n\n~~~diff\n@@ -21,65 +21,65 @@ Which produces the resulting data (in JSON):\n {\n \"user\": {\n \"name\": \"Mark Zuckerberg\"\n }\n }\n ```\n\n GraphQL is not a programming language capable of arbitrary computation, but is\n-instead a language used to query application servers that have\n+instead a language used to make requests to application services that have\n capabilities defined in this specification. GraphQL does not mandate a\n-particular programming language or storage system for application servers that\n-implement it. Instead, application servers take their capabilities and map them\n+particular programming language or storage system for application services that\n+implement it. Instead, application services take their capabilities and map them\n to a uniform language, type system, and philosophy that GraphQL encodes.\n This provides a unified interface friendly to product development and a powerful\n platform for tool-building.\n\n GraphQL has a number of design principles:\n\n- * **Hierarchical**: Most product development today involves the creation and\n- manipulation of view hierarchies. To achieve congruence with the structure\n- of these applications, a GraphQL query itself is structured hierarchically.\n- The query is shaped just like the data it returns. It is a natural\n- way for clients to describe data requirements.\n-\n * **Product-centric**: GraphQL is unapologetically driven by the requirements\n of views and the front-end engineers that write them. GraphQL starts with\n their way of thinking and requirements and builds the language and runtime\n necessary to enable that.\n\n- * **Strong-typing**: Every GraphQL server defines an application-specific\n- type system. Queries are executed within the context of that type system.\n- Given a query, tools can ensure that the query is both syntactically\n- correct and valid within the GraphQL type system before execution, i.e. at\n- development time, and the server can make certain guarantees about the shape\n+ * **Hierarchical**: Most product development today involves the creation and\n+ manipulation of view hierarchies. To achieve congruence with the structure\n+ of these applications, a GraphQL request itself is structured hierarchically.\n+ The request is shaped just like the data in its response. It is a natural way\n+ for clients to describe data requirements.\n+\n+ * **Strong-typing**: Every GraphQL service defines an application-specific\n+ type system. Requests are executed within the context of that type system.\n+ Given a GraphQL operation, tools can ensure that it is both syntactically\n+ correct and valid within that type system before execution, i.e. at\n+ development time, and the service can make certain guarantees about the shape\n and nature of the response.\n\n- * **Client-specified queries**: Through its type system, a GraphQL server\n+ * **Client-specified response**: Through its type system, a GraphQL service\n publishes the capabilities that its clients are allowed to consume. It is\n the client that is responsible for specifying exactly how it will consume\n- those published capabilities. These queries are specified at field-level\n- granularity. In the majority of client-server applications written\n- without GraphQL, the server determines the data returned in its various\n- scripted endpoints. A GraphQL query, on the other hand, returns exactly what\n- a client asks for and no more.\n+ those published capabilities. These requests are specified at field-level\n+ granularity. In the majority of client-server applications written without\n+ GraphQL, the service determines the shape of data returned from its various\n+ endpoints. A GraphQL response, on the other hand, contains exactly what a\n+ client asks for and no more.\n\n- * **Introspective**: GraphQL is introspective. A GraphQL server's type system\n- must be queryable by the GraphQL language itself, as will be described in this\n+ * **Introspective**: GraphQL is introspective. A GraphQL service's type system\n+ can be queryable by the GraphQL language itself, as will be described in this\n specification. GraphQL introspection serves as a powerful platform for\n building common tools and client software libraries.\n\n Because of these principles, GraphQL is a powerful and productive environment\n for building client applications. Product developers and designers building\n-applications against working GraphQL servers -- supported with quality tools --\n-can quickly become productive without reading extensive documentation and with\n+applications against working GraphQL services—supported with quality tools—can\n+quickly become productive without reading extensive documentation and with\n little or no formal training. To enable that experience, there must be those\n-that build those servers and tools.\n+that build those services and tools.\n\n The following formal specification serves as a reference for those builders.\n It describes the language and its grammar, the type system and the\n introspection system used to query it, and the execution and validation engines\n with the algorithms to power them. The goal of this specification is to provide\n a foundation and framework for an ecosystem of GraphQL tools, client libraries,\n-and server implementations -- spanning both organizations and platforms -- that\n+and service implementations—spanning both organizations and platforms—that\n has yet to be built. We look forward to working with the community\n in order to do that.\n~~~\n
\n\n
\nspec/Section 2 -- Language.md\n\n~~~diff\n@@ -1,43 +1,78 @@\n # Language\n\n Clients use the GraphQL query language to make requests to a GraphQL service.\n We refer to these request sources as documents. A document may contain\n operations (queries, mutations, and subscriptions) as well as fragments, a\n-common unit of composition allowing for query reuse.\n+common unit of composition allowing for data requirement reuse.\n\n A GraphQL document is defined as a syntactic grammar where terminal symbols are\n tokens (indivisible lexical units). These tokens are defined in a lexical\n-grammar which matches patterns of source characters (defined by a\n-double-colon `::`).\n+grammar which matches patterns of source characters. In this document, syntactic\n+grammar productions are distinguished with a colon `:` while lexical grammar\n+productions are distinguished with a double-colon `::`.\n\n-Note: See [Appendix A](#sec-Appendix-Notation-Conventions) for more details about the definition of lexical and syntactic grammar and other notational conventions\n-used in this document.\n+The source text of a GraphQL document must be a sequence of {SourceCharacter}.\n+The character sequence must be described by a sequence of {Token} and {Ignored}\n+lexical grammars. The lexical token sequence, omitting {Ignored}, must be\n+described by a single {Document} syntactic grammar.\n+\n+Note: See [Appendix A](#sec-Appendix-Notation-Conventions) for more information\n+about the lexical and syntactic grammar and other notational conventions used\n+throughout this document.\n+\n+**Lexical Analysis & Syntactic Parse**\n+\n+The source text of a GraphQL document is first converted into a sequence of\n+lexical tokens, {Token}, and ignored tokens, {Ignored}. The source text is\n+scanned from left to right, repeatedly taking the next possible sequence of\n+code-points allowed by the lexical grammar productions as the next token. This\n+sequence of lexical tokens are then scanned from left to right to produce an\n+abstract syntax tree (AST) according to the {Document} syntactical grammar.\n+\n+Lexical grammar productions in this document use *lookahead restrictions* to\n+remove ambiguity and ensure a single valid lexical analysis. A lexical token is\n+only valid if not followed by a character in its lookahead restriction.\n+\n+For example, an {IntValue} has the restriction {[lookahead != Digit]}, so cannot\n+be followed by a {Digit}. Because of this, the sequence {`123`} cannot represent\n+the tokens ({`12`}, {`3`}) since {`12`} is followed by the {Digit} {`3`} and\n+so must only represent a single token. Use {WhiteSpace} or other {Ignored}\n+between characters to represent multiple tokens.\n+\n+Note: This typically has the same behavior as a\n+\"[maximal munch](https://en.wikipedia.org/wiki/Maximal_munch)\" longest possible\n+match, however some lookahead restrictions include additional constraints.\n\n\n ## Source Text\n\n-SourceCharacter :: /[\\u0009\\u000A\\u000D\\u0020-\\uFFFF]/\n+SourceCharacter ::\n+ - \"U+0009\"\n+ - \"U+000A\"\n+ - \"U+000D\"\n+ - \"U+0020–U+FFFF\"\n\n GraphQL documents are expressed as a sequence of\n-[Unicode](http://unicode.org/standard/standard.html) characters. However, with\n+[Unicode](https://unicode.org/standard/standard.html) code points (informally\n+referred to as *\"characters\"* through most of this specification). However, with\n few exceptions, most of GraphQL is expressed only in the original non-control\n ASCII range so as to be as widely compatible with as many existing tools,\n languages, and serialization formats as possible and avoid display issues in\n text editors and source control.\n\n+Note: Non-ASCII Unicode characters may appear freely within {StringValue} and\n+{Comment} portions of GraphQL.\n+\n\n ### Unicode\n\n UnicodeBOM :: \"Byte Order Mark (U+FEFF)\"\n\n-Non-ASCII Unicode characters may freely appear within {StringValue} and\n-{Comment} portions of GraphQL.\n-\n The \"Byte Order Mark\" is a special Unicode character which\n may appear at the beginning of a file containing Unicode which programs may use\n to determine the fact that the text stream is Unicode, what endianness the text\n stream is in, and which of several Unicode encodings to interpret.\n\n\n ### White Space\n\n@@ -55,158 +90,195 @@ Note: GraphQL intentionally does not consider Unicode \"Zs\" category characters\n as white-space, avoiding misinterpretation by text editors and source\n control tools.\n\n\n ### Line Terminators\n\n LineTerminator ::\n - \"New Line (U+000A)\"\n- - \"Carriage Return (U+000D)\" [ lookahead ! \"New Line (U+000A)\" ]\n+ - \"Carriage Return (U+000D)\" [lookahead != \"New Line (U+000A)\"]\n - \"Carriage Return (U+000D)\" \"New Line (U+000A)\"\n\n Like white space, line terminators are used to improve the legibility of source\n-text, any amount may appear before or after any other token and have no\n-significance to the semantic meaning of a GraphQL Document. Line\n-terminators are not found within any other token.\n+text and separate lexical tokens, any amount may appear before or after any\n+other token and have no significance to the semantic meaning of a GraphQL\n+Document. Line terminators are not found within any other token.\n\n-Note: Any error reporting which provide the line number in the source of the\n+Note: Any error reporting which provides the line number in the source of the\n offending syntax should use the preceding amount of {LineTerminator} to produce\n the line number.\n\n\n ### Comments\n\n-Comment :: `#` CommentChar*\n+Comment :: `#` CommentChar* [lookahead != CommentChar]\n\n CommentChar :: SourceCharacter but not LineTerminator\n\n GraphQL source documents may contain single-line comments, starting with the\n {`#`} marker.\n\n-A comment can contain any Unicode code point except {LineTerminator} so a\n-comment always consists of all code points starting with the {`#`} character up\n-to but not including the line terminator.\n+A comment can contain any Unicode code point in {SourceCharacter} except\n+{LineTerminator} so a comment always consists of all code points starting with\n+the {`#`} character up to but not including the {LineTerminator} (or end of\n+the source).\n\n-Comments behave like white space and may appear after any token, or before a\n-line terminator, and have no significance to the semantic meaning of a\n+Comments are {Ignored} like white space and may appear after any token, or\n+before a {LineTerminator}, and have no significance to the semantic meaning of a\n GraphQL Document.\n\n\n ### Insignificant Commas\n\n Comma :: ,\n\n Similar to white space and line terminators, commas ({`,`}) are used to improve\n the legibility of source text and separate lexical tokens but are otherwise\n syntactically and semantically insignificant within GraphQL Documents.\n\n Non-significant comma characters ensure that the absence or presence of a comma\n does not meaningfully alter the interpreted syntax of the document, as this can\n be a common user-error in other languages. It also allows for the stylistic use\n-of either trailing commas or line-terminators as list delimiters which are both\n+of either trailing commas or line terminators as list delimiters which are both\n often desired for legibility and maintainability of source code.\n\n\n ### Lexical Tokens\n\n Token ::\n - Punctuator\n - Name\n - IntValue\n - FloatValue\n - StringValue\n\n A GraphQL document is comprised of several kinds of indivisible lexical tokens\n defined here in a lexical grammar by patterns of source Unicode characters.\n+Lexical tokens may be separated by {Ignored} tokens.\n\n-Tokens are later used as terminal symbols in a GraphQL Document\n-syntactic grammars.\n+Tokens are later used as terminal symbols in GraphQL syntactic grammar rules.\n\n\n ### Ignored Tokens\n\n Ignored ::\n - UnicodeBOM\n - WhiteSpace\n - LineTerminator\n - Comment\n - Comma\n\n-Before and after every lexical token may be any amount of ignored tokens\n-including {WhiteSpace} and {Comment}. No ignored regions of a source\n-document are significant, however ignored source characters may appear within\n-a lexical token in a significant way, for example a {String} may contain white\n-space characters.\n+{Ignored} tokens are used to improve readability and provide separation between\n+lexical tokens, but are otherwise insignificant and not referenced in\n+syntactical grammar productions.\n\n-No characters are ignored while parsing a given token, as an example no\n-white space characters are permitted between the characters defining a\n-{FloatValue}.\n+Any amount of {Ignored} may appear before and after every lexical token. No\n+ignored regions of a source document are significant, however {SourceCharacter}\n+which appear in {Ignored} may also appear within a lexical {Token} in a\n+significant way, for example a {StringValue} may contain white space characters.\n+No {Ignored} may appear *within* a {Token}, for example no white space\n+characters are permitted between the characters defining a {FloatValue}.\n\n\n ### Punctuators\n\n-Punctuator :: one of ! $ ( ) ... : = @ [ ] { | }\n+Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | }\n\n GraphQL documents include punctuation in order to describe structure. GraphQL\n is a data description language and not a programming language, therefore GraphQL\n lacks the punctuation often used to describe mathematical expressions.\n\n\n ### Names\n\n-Name :: /[_A-Za-z][_0-9A-Za-z]*/\n+Name ::\n+ - NameStart NameContinue* [lookahead != NameContinue]\n+\n+NameStart ::\n+ - Letter\n+ - `_`\n+\n+NameContinue ::\n+ - Letter\n+ - Digit\n+ - `_`\n+\n+Letter :: one of\n+ - `A` `B` `C` `D` `E` `F` `G` `H` `I` `J` `K` `L` `M`\n+ - `N` `O` `P` `Q` `R` `S` `T` `U` `V` `W` `X` `Y` `Z`\n+ - `a` `b` `c` `d` `e` `f` `g` `h` `i` `j` `k` `l` `m`\n+ - `n` `o` `p` `q` `r` `s` `t` `u` `v` `w` `x` `y` `z`\n+\n+Digit :: one of\n+ - `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`\n\n GraphQL Documents are full of named things: operations, fields, arguments,\n types, directives, fragments, and variables. All names must follow the same\n grammatical form.\n\n Names in GraphQL are case-sensitive. That is to say `name`, `Name`, and `NAME`\n all refer to different names. Underscores are significant, which means\n `other_name` and `othername` are two different names.\n\n-Names in GraphQL are limited to this ASCII subset of possible\n-characters to support interoperation with as many other systems as possible.\n+A {Name} must not be followed by a {NameContinue}. In other words, a {Name}\n+token is always the longest possible valid sequence. The source characters\n+{`a1`} cannot be interpreted as two tokens since {`a`} is followed by the {NameContinue} {`1`}.\n+\n+Note: Names in GraphQL are limited to the Latin ASCII subset\n+of {SourceCharacter} in order to support interoperation with as many other\n+systems as possible.\n+\n+**Reserved Names**\n+\n+Any {Name} within a GraphQL type system must not start with two underscores\n+{\"__\"} unless it is part of the [introspection system](#sec-Introspection) as\n+defined by this specification.\n\n\n ## Document\n\n Document : Definition+\n\n Definition :\n - ExecutableDefinition\n- - TypeSystemDefinition\n- - TypeSystemExtension\n+ - TypeSystemDefinitionOrExtension\n+\n+ExecutableDocument : ExecutableDefinition+\n\n ExecutableDefinition :\n - OperationDefinition\n - FragmentDefinition\n\n A GraphQL Document describes a complete file or request string operated on\n by a GraphQL service or client. A document contains multiple definitions, either\n executable or representative of a GraphQL type system.\n\n-Documents are only executable by a GraphQL service if they contain an\n-{OperationDefinition} and otherwise only contain {ExecutableDefinition}.\n-However documents which do not contain {OperationDefinition} or do contain\n-{TypeSystemDefinition} or {TypeSystemExtension} may still be parsed\n-and validated to allow client tools to represent many GraphQL uses which may\n-appear across many individual files.\n+Documents are only executable by a GraphQL service if they are\n+{ExecutableDocument} and contain at least one {OperationDefinition}. A\n+Document which contains {TypeSystemDefinitionOrExtension} must not be executed;\n+GraphQL execution services which receive a Document containing these should\n+return a descriptive error.\n\n-If a Document contains only one operation, that operation may be unnamed or\n-represented in the shorthand form, which omits both the query keyword and\n-operation name. Otherwise, if a GraphQL Document contains multiple\n+GraphQL services which only seek to execute GraphQL requests and not construct\n+a new GraphQL schema may choose to only permit {ExecutableDocument}.\n+\n+Documents which do not contain {OperationDefinition} or do contain\n+{TypeSystemDefinitionOrExtension} may still be parsed and validated to allow\n+client tools to represent many GraphQL uses which may appear across many\n+individual files.\n+\n+If a Document contains only one operation, that operation may be unnamed. If\n+that operation is a query without variables or directives then it may also be\n+represented in the shorthand form, omitting both the {`query`} keyword as well\n+as the operation name. Otherwise, if a GraphQL Document contains multiple\n operations, each operation must be named. When submitting a Document with\n multiple operations to a GraphQL service, the name of the desired operation to\n be executed must also be provided.\n\n-GraphQL services which only seek to provide GraphQL query execution may choose\n-to only include {ExecutableDefinition} and omit the {TypeSystemDefinition} and\n-{TypeSystemExtension} rules from {Definition}.\n-\n\n ## Operations\n\n OperationDefinition :\n - OperationType Name? VariableDefinitions? Directives? SelectionSet\n - SelectionSet\n\n OperationType : one of `query` `mutation` `subscription`\n@@ -230,19 +302,20 @@ mutation {\n likeCount\n }\n }\n }\n ```\n\n **Query shorthand**\n\n-If a document contains only one query operation, and that query defines no\n-variables and contains no directives, that operation may be represented in a\n-short-hand form which omits the query keyword and query name.\n+If a document contains only one operation and that operation is a query which\n+defines no variables and contains no directives then that operation may be\n+represented in a short-hand form which omits the {`query`} keyword and operation\n+name.\n\n For example, this unnamed query operation is written via query shorthand.\n\n ```graphql example\n {\n field\n }\n ```\n@@ -266,18 +339,18 @@ under-fetching data.\n ```graphql example\n {\n id\n firstName\n lastName\n }\n ```\n\n-In this query, the `id`, `firstName`, and `lastName` fields form a selection\n-set. Selection sets may also contain fragment references.\n+In this query operation, the `id`, `firstName`, and `lastName` fields form a\n+selection set. Selection sets may also contain fragment references.\n\n\n ## Fields\n\n Field : Alias? Name Arguments? Directives? SelectionSet?\n\n A selection set is primarily composed of fields. A field describes one discrete\n piece of information available to request within a selection set.\n@@ -335,17 +408,17 @@ unique identifier.\n ## Arguments\n\n Arguments[Const] : ( Argument[?Const]+ )\n\n Argument[Const] : Name : Value[?Const]\n\n Fields are conceptually functions which return values, and occasionally accept\n arguments which alter their behavior. These arguments often map directly to\n-function arguments within a GraphQL server's implementation.\n+function arguments within a GraphQL service's implementation.\n\n In this example, we want to query a specific user (requested via the `id`\n argument) and their profile picture of a specific `size`:\n\n ```graphql example\n {\n user(id: 4) {\n id\n@@ -367,17 +440,17 @@ Many arguments can exist for a given field:\n }\n ```\n\n **Arguments are unordered**\n\n Arguments may be provided in any syntactic order and maintain identical\n semantic meaning.\n\n-These two queries are semantically identical:\n+These two operations are semantically identical:\n\n ```graphql example\n {\n picture(width: 200, height: 100)\n }\n ```\n\n ```graphql example\n@@ -386,71 +459,68 @@ These two queries are semantically identical:\n }\n ```\n\n\n ## Field Alias\n\n Alias : Name :\n\n-By default, the key in the response object will use the field name\n-queried. However, you can define a different name by specifying an alias.\n+By default a field's response key in the response object will use that field's\n+name. However, you can define a different response key by specifying an alias.\n\n In this example, we can fetch two profile pictures of different sizes and ensure\n-the resulting object will not have duplicate keys:\n+the resulting response object will not have duplicate keys:\n\n ```graphql example\n {\n user(id: 4) {\n id\n name\n smallPic: profilePic(size: 64)\n bigPic: profilePic(size: 1024)\n }\n }\n ```\n\n-Which returns the result:\n+which returns the result:\n\n ```json example\n {\n \"user\": {\n \"id\": 4,\n \"name\": \"Mark Zuckerberg\",\n \"smallPic\": \"https://cdn.site.io/pic-4-64.jpg\",\n \"bigPic\": \"https://cdn.site.io/pic-4-1024.jpg\"\n }\n }\n ```\n\n-Since the top level of a query is a field, it also can be given an alias:\n+The fields at the top level of an operation can also be given an alias:\n\n ```graphql example\n {\n zuck: user(id: 4) {\n id\n name\n }\n }\n ```\n\n-Returns the result:\n+which returns the result:\n\n ```json example\n {\n \"zuck\": {\n \"id\": 4,\n \"name\": \"Mark Zuckerberg\"\n }\n }\n ```\n\n-A field's response key is its alias if an alias is provided, and it is\n-otherwise the field's name.\n-\n\n ## Fragments\n\n FragmentSpread : ... FragmentName Directives?\n\n FragmentDefinition : fragment FragmentName TypeCondition Directives? SelectionSet\n\n FragmentName : Name but not `on`\n@@ -478,17 +548,17 @@ query noFragments {\n name\n profilePic(size: 50)\n }\n }\n }\n ```\n\n The repeated fields could be extracted into a fragment and composed by\n-a parent fragment or query.\n+a parent fragment or operation.\n\n ```graphql example\n query withFragments {\n user(id: 4) {\n friends(first: 10) {\n ...friendFields\n }\n mutualFriends(first: 10) {\n@@ -499,18 +569,18 @@ query withFragments {\n\n fragment friendFields on User {\n id\n name\n profilePic(size: 50)\n }\n ```\n\n-Fragments are consumed by using the spread operator (`...`). All fields selected\n-by the fragment will be added to the query field selection at the same level\n+Fragments are consumed by using the spread operator (`...`). All fields\n+selected by the fragment will be added to the field selection at the same level\n as the fragment invocation. This happens through multiple levels of fragment\n spreads.\n\n For example:\n\n ```graphql example\n query withNestedFragments {\n user(id: 4) {\n@@ -529,40 +599,40 @@ fragment friendFields on User {\n ...standardProfilePic\n }\n\n fragment standardProfilePic on User {\n profilePic(size: 50)\n }\n ```\n\n-The queries `noFragments`, `withFragments`, and `withNestedFragments` all\n+The operations `noFragments`, `withFragments`, and `withNestedFragments` all\n produce the same response object.\n\n\n ### Type Conditions\n\n TypeCondition : on NamedType\n\n Fragments must specify the type they apply to. In this example, `friendFields`\n can be used in the context of querying a `User`.\n\n Fragments cannot be specified on any input value (scalar, enumeration, or input\n object).\n\n Fragments can be specified on object types, interfaces, and unions.\n\n-Selections within fragments only return values when concrete type of the object\n+Selections within fragments only return values when the concrete type of the object\n it is operating on matches the type of the fragment.\n\n-For example in this query on the Facebook data model:\n+For example in this operation using the Facebook data model:\n\n ```graphql example\n query FragmentTyping {\n- profiles(handles: [\"zuck\", \"cocacola\"]) {\n+ profiles(handles: [\"zuck\", \"coca-cola\"]) {\n handle\n ...userFragment\n ...pageFragment\n }\n }\n\n fragment userFragment on User {\n friends {\n@@ -582,21 +652,21 @@ The `profiles` root field returns a list where each element could be a `Page` or\n present and `likers` will not. Conversely when the result is a `Page`, `likers`\n will be present and `friends` will not.\n\n ```json example\n {\n \"profiles\": [\n {\n \"handle\": \"zuck\",\n- \"friends\": { \"count\" : 1234 }\n+ \"friends\": { \"count\": 1234 }\n },\n {\n- \"handle\": \"cocacola\",\n- \"likers\": { \"count\" : 90234512 }\n+ \"handle\": \"coca-cola\",\n+ \"likers\": { \"count\": 90234512 }\n }\n ]\n }\n ```\n\n\n ### Inline Fragments\n\n@@ -604,17 +674,17 @@ InlineFragment : ... TypeCondition? Directives? SelectionSet\n\n Fragments can be defined inline within a selection set. This is done to\n conditionally include fields based on their runtime type. This feature of\n standard fragment inclusion was demonstrated in the `query FragmentTyping`\n example. We could accomplish the same thing using inline fragments.\n\n ```graphql example\n query inlineFragmentTyping {\n- profiles(handles: [\"zuck\", \"cocacola\"]) {\n+ profiles(handles: [\"zuck\", \"coca-cola\"]) {\n handle\n ... on User {\n friends {\n count\n }\n }\n ... on Page {\n likers {\n@@ -661,98 +731,131 @@ Field and directive arguments accept input values of various literal primitives;\n input values can be scalars, enumeration values, lists, or input objects.\n\n If not defined as constant (for example, in {DefaultValue}), input values can be\n specified as a variable. List and inputs objects may also contain variables (unless defined to be constant).\n\n\n ### Int Value\n\n-IntValue :: IntegerPart\n+IntValue :: IntegerPart [lookahead != {Digit, `.`, NameStart}]\n\n IntegerPart ::\n - NegativeSign? 0\n - NegativeSign? NonZeroDigit Digit*\n\n NegativeSign :: -\n\n-Digit :: one of 0 1 2 3 4 5 6 7 8 9\n-\n NonZeroDigit :: Digit but not `0`\n\n-An Int number is specified without a decimal point or exponent (ex. `1`).\n+An {IntValue} is specified without a decimal point or exponent but may be\n+negative (ex. {-123}). It must not have any leading {0}.\n+\n+An {IntValue} must not be followed by a {Digit}. In other words, an {IntValue}\n+token is always the longest possible valid sequence. The source characters\n+{12} cannot be interpreted as two tokens since {1} is followed by the {Digit}\n+{2}. This also means the source {00} is invalid since it can neither be\n+interpreted as a single token nor two {0} tokens.\n+\n+An {IntValue} must not be followed by a {`.`} or {NameStart}. If either {`.`} or\n+{ExponentIndicator} follows then the token must only be interpreted as a\n+possible {FloatValue}. No other {NameStart} character can follow. For example\n+the sequences `0x123` and `123L` have no valid lexical representations.\n\n\n ### Float Value\n\n FloatValue ::\n- - IntegerPart FractionalPart\n- - IntegerPart ExponentPart\n- - IntegerPart FractionalPart ExponentPart\n+ - IntegerPart FractionalPart ExponentPart [lookahead != {Digit, `.`, NameStart}]\n+ - IntegerPart FractionalPart [lookahead != {Digit, `.`, NameStart}]\n+ - IntegerPart ExponentPart [lookahead != {Digit, `.`, NameStart}]\n\n FractionalPart :: . Digit+\n\n ExponentPart :: ExponentIndicator Sign? Digit+\n\n ExponentIndicator :: one of `e` `E`\n\n Sign :: one of + -\n\n-A Float number includes either a decimal point (ex. `1.0`) or an exponent\n-(ex. `1e50`) or both (ex. `6.0221413e23`).\n+A {FloatValue} includes either a decimal point (ex. {1.0}) or an exponent\n+(ex. {1e50}) or both (ex. {6.0221413e23}) and may be negative. Like {IntValue},\n+it also must not have any leading {0}.\n+\n+A {FloatValue} must not be followed by a {Digit}. In other words, a {FloatValue}\n+token is always the longest possible valid sequence. The source characters\n+{1.23} cannot be interpreted as two tokens since {1.2} is followed by the\n+{Digit} {3}.\n+\n+A {FloatValue} must not be followed by a {.}. For example, the sequence {1.23.4}\n+cannot be interpreted as two tokens ({1.2}, {3.4}).\n+\n+A {FloatValue} must not be followed by a {NameStart}. For example the sequence\n+`0x1.2p3` has no valid lexical representation.\n+\n+Note: The numeric literals {IntValue} and {FloatValue} both restrict being\n+immediately followed by a letter (or other {NameStart}) to reduce confusion\n+or unexpected behavior since GraphQL only supports decimal numbers.\n\n\n ### Boolean Value\n\n BooleanValue : one of `true` `false`\n\n The two keywords `true` and `false` represent the two boolean values.\n\n\n ### String Value\n\n StringValue ::\n- - `\"` StringCharacter* `\"`\n+ - `\"\"` [lookahead != `\"`]\n+ - `\"` StringCharacter+ `\"`\n - `\"\"\"` BlockStringCharacter* `\"\"\"`\n\n StringCharacter ::\n- - SourceCharacter but not `\"` or \\ or LineTerminator\n- - \\u EscapedUnicode\n- - \\ EscapedCharacter\n+ - SourceCharacter but not `\"` or `\\` or LineTerminator\n+ - `\\u` EscapedUnicode\n+ - `\\` EscapedCharacter\n\n EscapedUnicode :: /[0-9A-Fa-f]{4}/\n\n-EscapedCharacter :: one of `\"` \\ `/` b f n r t\n+EscapedCharacter :: one of `\"` `\\` `/` `b` `f` `n` `r` `t`\n\n BlockStringCharacter ::\n - SourceCharacter but not `\"\"\"` or `\\\"\"\"`\n - `\\\"\"\"`\n\n-Strings are sequences of characters wrapped in double-quotes (`\"`). (ex.\n-`\"Hello World\"`). White space and other otherwise-ignored characters are\n+Strings are sequences of characters wrapped in quotation marks (U+0022).\n+(ex. {`\"Hello World\"`}). White space and other otherwise-ignored characters are\n significant within a string value.\n\n-Note: Unicode characters are allowed within String value literals, however\n-{SourceCharacter} must not contain some ASCII control characters so escape\n-sequences must be used to represent these characters.\n+The empty string {`\"\"`} must not be followed by another {`\"`} otherwise it would\n+be interpreted as the beginning of a block string. As an example, the source\n+{`\"\"\"\"\"\"`} can only be interpreted as a single empty block string and not three\n+empty strings.\n+\n+Non-ASCII Unicode characters are allowed within single-quoted strings.\n+Since {SourceCharacter} must not contain some ASCII control characters, escape\n+sequences must be used to represent these characters. The {`\\`}, {`\"`}\n+characters also must be escaped. All other escape sequences are optional.\n\n **Block Strings**\n\n Block strings are sequences of characters wrapped in triple-quotes (`\"\"\"`).\n White space, line terminators, quote, and backslash characters may all be\n used unescaped to enable verbatim text. Characters must all be valid\n {SourceCharacter}.\n\n Since block strings represent freeform text often used in indented\n positions, the string value semantics of a block string excludes uniform\n indentation and blank initial and trailing lines via {BlockStringValue()}.\n\n For example, the following operation containing a block string:\n\n-```graphql example\n+```raw graphql example\n mutation {\n sendEmail(message: \"\"\"\n Hello,\n World!\n\n Yours,\n GraphQL.\n \"\"\")\n@@ -785,44 +888,49 @@ which makes it a little harder to read.\"\"\"\n ```\n\n Note: If non-printable ASCII characters are needed in a string value, a standard\n quoted string with appropriate escape sequences must be used instead of a\n block string.\n\n **Semantics**\n\n-StringValue :: `\"` StringCharacter* `\"`\n+StringValue :: `\"\"`\n\n- * Return the Unicode character sequence of all {StringCharacter}\n- Unicode character values (which may be an empty sequence).\n+ * Return an empty sequence.\n\n-StringCharacter :: SourceCharacter but not `\"` or \\ or LineTerminator\n+StringValue :: `\"` StringCharacter+ `\"`\n\n- * Return the character value of {SourceCharacter}.\n+ * Return the sequence of all {StringCharacter} code points.\n+\n+StringCharacter :: SourceCharacter but not `\"` or `\\` or LineTerminator\n+\n+ * Return the code point {SourceCharacter}.\n\n-StringCharacter :: \\u EscapedUnicode\n+StringCharacter :: `\\u` EscapedUnicode\n\n- * Return the character whose code unit value in the Unicode Basic Multilingual\n- Plane is the 16-bit hexadecimal value {EscapedUnicode}.\n+ * Let {value} be the 16-bit hexadecimal value represented by the sequence of\n+ hexadecimal digits within {EscapedUnicode}.\n+ * Return the code point {value}.\n\n-StringCharacter :: \\ EscapedCharacter\n+StringCharacter :: `\\` EscapedCharacter\n\n- * Return the character value of {EscapedCharacter} according to the table below.\n+ * Return the code point represented by {EscapedCharacter} according to the\n+ table below.\n\n-| Escaped Character | Code Unit Value | Character Name |\n-| ----------------- | --------------- | ---------------------------- |\n-| `\"` | U+0022 | double quote |\n-| `\\` | U+005C | reverse solidus (back slash) |\n-| `/` | U+002F | solidus (forward slash) |\n-| `b` | U+0008 | backspace |\n-| `f` | U+000C | form feed |\n-| `n` | U+000A | line feed (new line) |\n-| `r` | U+000D | carriage return |\n-| `t` | U+0009 | horizontal tab |\n+| Escaped Character | Code Point | Character Name |\n+| ----------------- | ---------- | ---------------------------- |\n+| {`\"`} | U+0022 | double quote |\n+| {`\\`} | U+005C | reverse solidus (back slash) |\n+| {`/`} | U+002F | solidus (forward slash) |\n+| {`b`} | U+0008 | backspace |\n+| {`f`} | U+000C | form feed |\n+| {`n`} | U+000A | line feed (new line) |\n+| {`r`} | U+000D | carriage return |\n+| {`t`} | U+0009 | horizontal tab |\n\n StringValue :: `\"\"\"` BlockStringCharacter* `\"\"\"`\n\n * Let {rawValue} be the Unicode character sequence of all\n {BlockStringCharacter} Unicode character values (which may be an empty\n sequence).\n * Return the result of {BlockStringValue(rawValue)}.\n\n@@ -879,24 +987,24 @@ For example, these two field calls are similar, but are not identical:\n\n ```graphql example\n {\n field(arg: null)\n field\n }\n ```\n\n-The first has explictly provided {null} to the argument \"arg\", while the second\n+The first has explicitly provided {null} to the argument \"arg\", while the second\n has implicitly not provided a value to the argument \"arg\". These two forms may\n be interpreted differently. For example, a mutation representing deleting a\n field vs not altering a field, respectively. Neither form may be used for an\n input expecting a Non-Null type.\n\n Note: The same two methods of representing the lack of a value are possible via\n-variables by either providing the a variable value as {null} and not providing\n+variables by either providing the variable value as {null} or not providing\n a variable value at all.\n\n\n ### Enum Value\n\n EnumValue : Name but not `true`, `false` or `null`\n\n Enum values are represented as unquoted names (ex. `MOBILE_WEB`). It is\n@@ -945,17 +1053,17 @@ curly-braces `{ }`. The values of an object literal may be any input value\n literal or variable (ex. `{ name: \"Hello world\", score: 1.0 }`). We refer to\n literal representation of input objects as \"object literals.\"\n\n **Input object fields are unordered**\n\n Input object fields may be provided in any syntactic order and maintain\n identical semantic meaning.\n\n-These two queries are semantically identical:\n+These two operations are semantically identical:\n\n ```graphql example\n {\n nearestThing(location: { lon: 12.43, lat: -53.211 })\n }\n ```\n\n ```graphql example\n@@ -981,60 +1089,59 @@ ObjectValue : { ObjectField+ }\n\n\n ## Variables\n\n Variable : $ Name\n\n VariableDefinitions : ( VariableDefinition+ )\n\n-VariableDefinition : Variable : Type DefaultValue?\n+VariableDefinition : Variable : Type DefaultValue? Directives[Const]?\n\n DefaultValue : = Value[Const]\n\n-A GraphQL query can be parameterized with variables, maximizing query reuse,\n+A GraphQL operation can be parameterized with variables, maximizing reuse,\n and avoiding costly string building in clients at runtime.\n\n If not defined as constant (for example, in {DefaultValue}), a {Variable} can be\n supplied for an input value.\n\n Variables must be defined at the top of an operation and are in scope\n-throughout the execution of that operation.\n+throughout the execution of that operation. Values for those variables are\n+provided to a GraphQL service as part of a request so they may be substituted\n+in during execution.\n\n In this example, we want to fetch a profile picture size based on the size\n of a particular device:\n\n ```graphql example\n query getZuckProfile($devicePicSize: Int) {\n user(id: 4) {\n id\n name\n profilePic(size: $devicePicSize)\n }\n }\n ```\n\n-Values for those variables are provided to a GraphQL service along with a\n-request so they may be substituted during execution. If providing JSON for the\n-variables' values, we could run this query and request profilePic of\n-size `60` width:\n+If providing JSON for the variables' values, we could request a `profilePic` of\n+size `60`:\n\n ```json example\n {\n \"devicePicSize\": 60\n }\n ```\n\n **Variable use within Fragments**\n\n-Query variables can be used within fragments. Query variables have global scope\n-with a given operation, so a variable used within a fragment must be declared\n-in any top-level operation that transitively consumes that fragment. If\n-a variable is referenced in a fragment and is included by an operation that does\n-not define that variable, the operation cannot be executed.\n+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\n+top-level operation that transitively consumes that fragment. If a variable is\n+referenced in a fragment and is included by an operation that does not define\n+that variable, that operation is invalid (see [All Variable Uses Defined](#sec-All-Variable-Uses-Defined)).\n\n\n ## Type References\n\n Type :\n - NamedType\n - ListType\n - NonNullType\n@@ -1042,19 +1149,19 @@ Type :\n NamedType : Name\n\n ListType : [ Type ]\n\n NonNullType :\n - NamedType !\n - ListType !\n\n-GraphQL describes the types of data expected by query variables. Input types\n-may be lists of another input type, or a non-null variant of any other\n-input type.\n+GraphQL describes the types of data expected by arguments and variables.\n+Input types may be lists of another input type, or a non-null variant of any\n+other input type.\n\n **Semantics**\n\n Type : Name\n\n * Let {name} be the string value of {Name}\n * Let {type} be the type defined in the Schema named {name}\n * {type} must not be {null}\n@@ -1084,13 +1191,36 @@ validation behavior in a GraphQL document.\n\n In some cases, you need to provide options to alter GraphQL's execution\n behavior in ways field arguments will not suffice, such as conditionally\n including or skipping a field. Directives provide this by describing additional information to the executor.\n\n Directives have a name along with a list of arguments which may accept values\n of any input type.\n\n-Directives can be used to describe additional information for types, fields, fragments\n-and operations.\n+Directives can be used to describe additional information for types, fields,\n+fragments and operations.\n\n As future versions of GraphQL adopt new configurable execution capabilities,\n-they may be exposed via directives.\n+they may be exposed via directives. GraphQL services and tools may also provide\n+any additional *custom directive* beyond those described here.\n+\n+**Directive order is significant**\n+\n+Directives may be provided in a specific syntactic order which may have semantic interpretation.\n+\n+These two type definitions may have different semantic meaning:\n+\n+```graphql example\n+type Person\n+ @addExternalFields(source: \"profiles\")\n+ @excludeField(name: \"photo\") {\n+ name: String\n+}\n+```\n+\n+```graphql example\n+type Person\n+ @excludeField(name: \"photo\")\n+ @addExternalFields(source: \"profiles\") {\n+ name: String\n+}\n+```\n~~~\n
\n\n
\nspec/Section 3 -- Type System.md\n\n~~~diff\n@@ -1,51 +1,126 @@\n # Type System\n\n-The GraphQL Type system describes the capabilities of a GraphQL server and is\n-used to determine if a query is valid. The type system also describes the\n-input types of query variables to determine if values provided at runtime\n-are valid.\n+The GraphQL Type system describes the capabilities of a GraphQL service and is\n+used to determine if a requested operation is valid, to guarantee the type of\n+response results, and describes the input types of variables to determine if\n+values provided at request time are valid.\n+\n+TypeSystemDocument : TypeSystemDefinition+\n\n TypeSystemDefinition :\n - SchemaDefinition\n - TypeDefinition\n - DirectiveDefinition\n\n The GraphQL language includes an\n [IDL](https://en.wikipedia.org/wiki/Interface_description_language) used to\n describe a GraphQL service's type system. Tools may use this definition language\n to provide utilities such as client code generation or service boot-strapping.\n\n-GraphQL tools which only seek to provide GraphQL query execution may choose not\n-to parse {TypeSystemDefinition}.\n-\n-A GraphQL Document which contains {TypeSystemDefinition} must not be executed;\n-GraphQL execution services which receive a GraphQL Document containing type\n-system definitions should return a descriptive error.\n+GraphQL tools or services which only seek to execute GraphQL requests and not\n+construct a new GraphQL schema may choose not to allow {TypeSystemDefinition}.\n+Tools which only seek to produce schema and not execute requests may choose to\n+only allow {TypeSystemDocument} and not allow {ExecutableDefinition} or\n+{TypeSystemExtension} but should provide a descriptive error if present.\n\n Note: The type system definition language is used throughout the remainder of\n this specification document when illustrating example type systems.\n\n\n ## Type System Extensions\n\n+TypeSystemExtensionDocument : TypeSystemDefinitionOrExtension+\n+\n+TypeSystemDefinitionOrExtension :\n+ - TypeSystemDefinition\n+ - TypeSystemExtension\n+\n TypeSystemExtension :\n - SchemaExtension\n - TypeExtension\n\n-Type system extensions are used to represent a GraphQL type system which has been\n-extended from some original type system. For example, this might be used by a\n-local service to represent data a GraphQL client only accesses locally, or by a\n-GraphQL service which is itself an extension of another GraphQL service.\n+Type system extensions are used to represent a GraphQL type system which has\n+been extended from some original type system. For example, this might be used by\n+a local service to represent data a GraphQL client only accesses locally, or by\n+a GraphQL service which is itself an extension of another GraphQL service.\n+\n+Tools which only seek to produce and extend schema and not execute requests may\n+choose to only allow {TypeSystemExtensionDocument} and not allow\n+{ExecutableDefinition} but should provide a descriptive error if present.\n+\n+\n+## Descriptions\n+\n+Description : StringValue\n+\n+Documentation is a first-class feature of GraphQL type systems. To ensure\n+the documentation of a GraphQL service remains consistent with its capabilities,\n+descriptions of GraphQL definitions are provided alongside their definitions and\n+made available via introspection.\n+\n+To allow GraphQL service designers to easily publish documentation alongside the\n+capabilities of a GraphQL service, GraphQL descriptions are defined using the\n+Markdown syntax (as specified by [CommonMark](https://commonmark.org/)). In the\n+type system definition language, these description strings (often {BlockString})\n+occur immediately before the definition they describe.\n+\n+GraphQL schema and all other definitions (e.g. types, fields, arguments, etc.)\n+which can be described should provide a {Description} unless they are considered\n+self descriptive.\n+\n+As an example, this simple GraphQL schema is well described:\n+\n+```raw graphql example\n+\"\"\"\n+A simple GraphQL schema which is well described.\n+\"\"\"\n+schema {\n+ query: Query\n+}\n+\n+\"\"\"\n+Root type for all your query operations\n+\"\"\"\n+type Query {\n+ \"\"\"\n+ Translates a string from a given language into a different language.\n+ \"\"\"\n+ translate(\n+ \"The original language that `text` is provided in.\"\n+ fromLanguage: Language\n+\n+ \"The translated language to be returned.\"\n+ toLanguage: Language\n+\n+ \"The text to be translated.\"\n+ text: String\n+ ): String\n+}\n+\n+\"\"\"\n+The set of languages supported by `translate`.\n+\"\"\"\n+enum Language {\n+ \"English\"\n+ EN\n+\n+ \"French\"\n+ FR\n+\n+ \"Chinese\"\n+ CH\n+}\n+```\n\n\n ## Schema\n\n-SchemaDefinition : schema Directives[Const]? { RootOperationTypeDefinition+ }\n+SchemaDefinition : Description? schema Directives[Const]? { RootOperationTypeDefinition+ }\n\n RootOperationTypeDefinition : OperationType : NamedType\n\n A GraphQL service's collective type system capabilities are referred to as that\n service's \"schema\". A schema is defined in terms of the types and directives it\n supports as well as the root operation types for each kind of operation:\n query, mutation, and subscription; this determines the place in the type system\n where those operations begin.\n@@ -64,60 +139,64 @@ begins with {\"__\"} (two underscores), as this is used exclusively by GraphQL's\n introspection system.\n\n ### Root Operation Types\n\n A schema defines the initial root operation type for each kind of operation it\n supports: query, mutation, and subscription; this determines the place in the\n type system where those operations begin.\n\n-The `query` root operation type must be provided and must be an Object type.\n+The {`query`} root operation type must be provided and must be an Object type.\n\n-The `mutation` root operation type is optional; if it is not provided, the\n+The {`mutation`} root operation type is optional; if it is not provided, the\n service does not support mutations. If it is provided, it must be an\n Object type.\n\n-Similarly, the `subscription` root operation type is also optional; if it is not\n-provided, the service does not support subscriptions. If it is provided, it must\n-be an Object type.\n+Similarly, the {`subscription`} root operation type is also optional; if it is\n+not provided, the service does not support subscriptions. If it is provided, it\n+must be an Object type.\n\n-The fields on the `query` root operation type indicate what fields are available\n-at the top level of a GraphQL query. For example, a basic GraphQL query like:\n+The {`query`}, {`mutation`}, and {`subscription`} root types must all be\n+different types if provided.\n+\n+The fields on the {`query`} root operation type indicate what fields are\n+available at the top level of a GraphQL query operation.\n+\n+For example, this example operation:\n\n ```graphql example\n query {\n myName\n }\n ```\n\n-Is valid when the `query` root operation type has a field named \"myName\".\n+is only valid when the {`query`} root operation type has a field named \"myName\":\n\n ```graphql example\n type Query {\n myName: String\n }\n ```\n\n-Similarly, the following mutation is valid if a `mutation` root operation type\n-has a field named \"setName\". Note that the `query` and `mutation` root types\n-must be different types.\n+Similarly, the following mutation is only valid if the {`mutation`} root\n+operation type has a field named \"setName\".\n\n ```graphql example\n mutation {\n setName(name: \"Zuck\") {\n newName\n }\n }\n ```\n\n When using the type system definition language, a document must include at most\n-one `schema` definition.\n+one {`schema`} definition.\n\n In this example, a GraphQL schema is defined with both query and mutation\n-root types:\n+root operation types:\n\n ```graphql example\n schema {\n query: MyQueryRootType\n mutation: MyMutationRootType\n }\n\n type MyQueryRootType {\n@@ -127,107 +206,55 @@ type MyQueryRootType {\n type MyMutationRootType {\n setSomeField(to: String): String\n }\n ```\n\n **Default Root Operation Type Names**\n\n While any type can be the root operation type for a GraphQL operation, the type\n-system definition language can omit the schema definition when the `query`,\n-`mutation`, and `subscription` root types are named `Query`, `Mutation`, and\n-`Subscription` respectively.\n+system definition language can omit the schema definition when the {`query`},\n+{`mutation`}, and {`subscription`} root types are named {\"Query\"}, {\"Mutation\"},\n+and {\"Subscription\"} respectively.\n\n Likewise, when representing a GraphQL schema using the type system definition\n language, a schema definition should be omitted if it only uses the default root\n operation type names.\n\n This example describes a valid complete GraphQL schema, despite not explicitly\n-including a `schema` definition. The `Query` type is presumed to be the `query`\n-root operation type of the schema.\n+including a {`schema`} definition. The {\"Query\"} type is presumed to be the\n+{`query`} root operation type of the schema.\n\n ```graphql example\n type Query {\n someField: String\n }\n ```\n\n ### Schema Extension\n\n SchemaExtension :\n- - extend schema Directives[Const]? { OperationTypeDefinition+ }\n- - extend schema Directives[Const]\n+ - extend schema Directives[Const]? { RootOperationTypeDefinition+ }\n+ - extend schema Directives[Const] [lookahead != `{`]\n\n Schema extensions are used to represent a schema which has been extended from\n an original schema. For example, this might be used by a GraphQL service which\n adds additional operation types, or additional directives to an existing schema.\n\n+Note: Schema extensions without additional operation type definitions must not\n+be followed by a {`{`} (such as a query shorthand) to avoid parsing ambiguity.\n+The same limitation applies to the type definitions and extensions below.\n+\n **Schema Validation**\n\n Schema extensions have the potential to be invalid if incorrectly defined.\n\n 1. The Schema must already be defined.\n-2. Any directives provided must not already apply to the original Schema.\n-\n-\n-## Descriptions\n-\n-Description : StringValue\n-\n-Documentation is first-class feature of GraphQL type systems. To ensure\n-the documentation of a GraphQL service remains consistent with its capabilities,\n-descriptions of GraphQL definitions are provided alongside their definitions and\n-made available via introspection.\n-\n-To allow GraphQL service designers to easily publish documentation alongside the\n-capabilities of a GraphQL service, GraphQL descriptions are defined using the\n-Markdown syntax (as specified by [CommonMark](http://commonmark.org/)). In the\n-type system definition language, these description strings (often {BlockString})\n-occur immediately before the definition they describe.\n-\n-All GraphQL types, fields, arguments and other definitions which can be\n-described should provide a {Description} unless they are considered self\n-descriptive.\n-\n-As an example, this simple GraphQL schema is well described:\n-\n-```graphql example\n-\"\"\"\n-A simple GraphQL schema which is well described.\n-\"\"\"\n-type Query {\n- \"\"\"\n- Translates a string from a given language into a different language.\n- \"\"\"\n- translate(\n- \"The original language that `text` is provided in.\"\n- fromLanguage: Language\n-\n- \"The translated language to be returned.\"\n- toLanguage: Language\n-\n- \"The text to be translated.\"\n- text: String\n- ): String\n-}\n-\n-\"\"\"\n-The set of languages supported by `translate`.\n-\"\"\"\n-enum Language {\n- \"English\"\n- EN\n-\n- \"French\"\n- FR\n-\n- \"Chinese\"\n- CH\n-}\n-```\n+2. Any non-repeatable directives provided must not already apply to the\n+ original Schema.\n\n\n ## Types\n\n TypeDefinition :\n - ScalarTypeDefinition\n - ObjectTypeDefinition\n - InterfaceTypeDefinition\n@@ -244,53 +271,54 @@ are enumerable. GraphQL offers an `Enum` type in those cases, where the type\n specifies the space of valid responses.\n\n Scalars and Enums form the leaves in response trees; the intermediate levels are\n `Object` types, which define a set of fields, where each field is another\n type in the system, allowing the definition of arbitrary type hierarchies.\n\n GraphQL supports two abstract types: interfaces and unions.\n\n-An `Interface` defines a list of fields; `Object` types that implement that\n-interface are guaranteed to implement those fields. Whenever the type system\n-claims it will return an interface, it will return a valid implementing type.\n+An `Interface` defines a list of fields; `Object` types and other Interface\n+types which implement this Interface are guaranteed to implement those fields.\n+Whenever a field claims it will return an Interface type, it will return a\n+valid implementing Object type during execution.\n\n A `Union` defines a list of possible types; similar to interfaces, whenever the\n type system claims a union will be returned, one of the possible types will be\n returned.\n\n Finally, oftentimes it is useful to provide complex structs as inputs to\n GraphQL field arguments or variables; the `Input Object` type allows the schema\n to define exactly what data is expected.\n\n\n ### Wrapping Types\n\n All of the types so far are assumed to be both nullable and singular: e.g. a\n scalar string returns either null or a singular string.\n\n-A GraphQL schema may describe that a field represents list of another types;\n+A GraphQL schema may describe that a field represents a list of another type;\n the `List` type is provided for this reason, and wraps another type.\n\n Similarly, the `Non-Null` type wraps another type, and denotes that the\n-resulting value will never be {null} (and that an error cannot result in a\n+resulting value will never be {null} (and that a field error cannot result in a\n {null} value).\n\n These two types are referred to as \"wrapping types\"; non-wrapping types are\n referred to as \"named types\". A wrapping type has an underlying named type,\n found by continually unwrapping the type until a named type is found.\n\n\n ### Input and Output Types\n\n Types are used throughout GraphQL to describe both the values accepted as input\n to arguments and variables as well as the values output by fields. These two\n uses categorize types as *input types* and *output types*. Some kinds of types,\n like Scalar and Enum types, can be used as both input types and output types;\n-other kinds types can only be used in one or the other. Input Object types can\n+other kinds of types can only be used in one or the other. Input Object types can\n only be used as input types. Object, Interface, and Union types can only be used\n as output types. Lists and Non-Null types may be used as input types or output\n types depending on how the wrapped type may be used.\n\n IsInputType(type) :\n * If {type} is a List type or Non-Null type:\n * Let {unwrappedType} be the unwrapped type of {type}.\n * Return IsInputType({unwrappedType})\n@@ -322,273 +350,319 @@ from some original type. For example, this might be used by a local service to\n represent additional fields a GraphQL client only accesses locally.\n\n\n ## Scalars\n\n ScalarTypeDefinition : Description? scalar Name Directives[Const]?\n\n Scalar types represent primitive leaf values in a GraphQL type system. GraphQL\n-responses take the form of a hierarchical tree; the leaves on these trees are\n-GraphQL scalars.\n-\n-All GraphQL scalars are representable as strings, though depending on the\n-response format being used, there may be a more appropriate primitive for the\n-given scalar type, and server should use those types when appropriate.\n-\n-GraphQL provides a number of built-in scalars, but type systems can add\n-additional scalars with semantic meaning. For example, a GraphQL system could\n-define a scalar called `Time` which, while serialized as a string, promises to\n-conform to ISO-8601. When querying a field of type `Time`, you can then rely on\n-the ability to parse the result with an ISO-8601 parser and use a\n-client-specific primitive for time. Another example of a potentially useful\n-custom scalar is `Url`, which serializes as a string, but is guaranteed by\n-the server to be a valid URL.\n+responses take the form of a hierarchical tree; the leaves of this tree are\n+typically GraphQL Scalar types (but may also be Enum types or {null} values).\n+\n+GraphQL provides a number of built-in scalars which are fully defined in the\n+sections below, however type systems may also add additional custom scalars to\n+introduce additional semantic meaning.\n+\n+**Built-in Scalars**\n+\n+GraphQL specifies a basic set of well-defined Scalar types: {Int}, {Float},\n+{String}, {Boolean}, and {ID}. A GraphQL framework should support all of these\n+types, and a GraphQL service which provides a type by these names must adhere to\n+the behavior described for them in this document. As an example, a service must\n+not include a type called {Int} and use it to represent 64-bit numbers,\n+internationalization information, or anything other than what is defined in\n+this document.\n+\n+When returning the set of types from the `__Schema` introspection type, all\n+referenced built-in scalars must be included. If a built-in scalar type is not\n+referenced anywhere in a schema (there is no field, argument, or input field of\n+that type) then it must not be included.\n+\n+When representing a GraphQL schema using the type system definition language,\n+all built-in scalars must be omitted for brevity.\n+\n+**Custom Scalars**\n+\n+GraphQL services may use custom scalar types in addition to the built-in\n+scalars. For example, a GraphQL service could define a scalar called `UUID`\n+which, while serialized as a string, conforms to [RFC 4122](https://tools.ietf.org/html/rfc4122).\n+When querying a field of type `UUID`, you can then rely on the ability to parse\n+the result with a RFC 4122 compliant parser. Another example of a potentially\n+useful custom scalar is `URL`, which serializes as a string, but is guaranteed\n+by the server to be a valid URL.\n+\n+:: When defining a custom scalar, GraphQL services should provide a *scalar\n+specification URL* via the `@specifiedBy` directive or the `specifiedByURL`\n+introspection field. This URL must link to a human-readable specification of the\n+data format, serialization, and coercion rules for the scalar.\n+\n+For example, a GraphQL service providing a `UUID` scalar may link to RFC 4122,\n+or some custom document defining a reasonable subset of that RFC. If a *scalar\n+specification URL* is present, systems and tools that are aware of it should\n+conform to its described rules.\n\n ```graphql example\n-scalar Time\n-scalar Url\n+scalar UUID @specifiedBy(url: \"https://tools.ietf.org/html/rfc4122\")\n+scalar URL @specifiedBy(url: \"https://tools.ietf.org/html/rfc3986\")\n ```\n\n-A server may omit any of the built-in scalars from its schema, for example if a\n-schema does not refer to a floating-point number, then it must not include the\n-`Float` type. However, if a schema includes a type with the name of one of the\n-types described here, it must adhere to the behavior described. As an example,\n-a server must not include a type called `Int` and use it to represent\n-128-bit numbers, internationalization information, or anything other than what\n-is defined in this document.\n+Custom *scalar specification URL*s should provide a single, stable format to\n+avoid ambiguity. If the linked specification is in flux, the service should link\n+to a fixed version rather than to a resource which might change.\n\n-When representing a GraphQL schema using the type system definition language,\n-the built-in scalar types should be omitted for brevity.\n+Custom *scalar specification URL*s should not be changed once defined. Doing so\n+would likely disrupt tooling or could introduce breaking changes within the\n+linked specification's contents.\n\n-**Result Coercion**\n+Built-in scalar types must not provide a *scalar specification URL* as they are\n+specified by this document.\n+\n+Note: Custom scalars should also summarize the specified format and provide\n+examples in their description.\n\n-A GraphQL server, when preparing a field of a given scalar type, must uphold the\n+**Result Coercion and Serialization**\n+\n+A GraphQL service, when preparing a field of a given scalar type, must uphold the\n contract the scalar type describes, either by coercing the value or producing a\n-field error if a value cannot be coerced or if coercion may result in data loss.\n+[field error](#sec-Errors.Field-errors) if a value cannot be coerced or if\n+coercion may result in data loss.\n\n A GraphQL service may decide to allow coercing different internal types to the\n-expected return type. For example when coercing a field of type `Int` a boolean\n-`true` value may produce `1` or a string value `\"123\"` may be parsed as base-10\n-`123`. However if internal type coercion cannot be reasonably performed without\n+expected return type. For example when coercing a field of type {Int} a boolean\n+{true} value may produce {1} or a string value {\"123\"} may be parsed as base-10\n+{123}. However if internal type coercion cannot be reasonably performed without\n losing information, then it must raise a field error.\n\n-Since this coercion behavior is not observable to clients of the GraphQL server,\n+Since this coercion behavior is not observable to clients of the GraphQL service,\n the precise rules of coercion are left to the implementation. The only\n-requirement is that the server must yield values which adhere to the expected\n+requirement is that the service must yield values which adhere to the expected\n Scalar type.\n\n+GraphQL scalars are serialized according to the serialization format being used.\n+There may be a most appropriate serialized primitive for each given scalar type,\n+and the service should produce each primitive where appropriate.\n+\n+See [Serialization Format](#sec-Serialization-Format) for more detailed\n+information on the serialization of scalars in common JSON and other formats.\n+\n **Input Coercion**\n\n-If a GraphQL server expects a scalar type as input to an argument, coercion\n+If a GraphQL service expects a scalar type as input to an argument, coercion\n is observable and the rules must be well defined. If an input value does not\n-match a coercion rule, a query error must be raised.\n+match a coercion rule, a [request error](#sec-Errors.Request-errors) must be\n+raised (input values are validated before execution begins).\n\n GraphQL has different constant literals to represent integer and floating-point\n input values, and coercion rules may apply differently depending on which type\n-of input value is encountered. GraphQL may be parameterized by query variables,\n-the values of which are often serialized when sent over a transport like HTTP. Since\n+of input value is encountered. GraphQL may be parameterized by variables, the\n+values of which are often serialized when sent over a transport like HTTP. Since\n some common serializations (ex. JSON) do not discriminate between integer\n and floating-point values, they are interpreted as an integer input value if\n they have an empty fractional part (ex. `1.0`) and otherwise as floating-point\n input value.\n\n For all types below, with the exception of Non-Null, if the explicit value\n {null} is provided, then the result of input coercion is {null}.\n\n-**Built-in Scalars**\n-\n-GraphQL provides a basic set of well-defined Scalar types. A GraphQL server\n-should support all of these types, and a GraphQL server which provide a type by\n-these names must adhere to the behavior described below.\n-\n\n ### Int\n\n The Int scalar type represents a signed 32-bit numeric non-fractional value.\n Response formats that support a 32-bit integer or a number type should use\n that type to represent this scalar.\n\n **Result Coercion**\n\n-Fields returning the type `Int` expect to encounter 32-bit integer\n+Fields returning the type {Int} expect to encounter 32-bit integer\n internal values.\n\n-GraphQL servers may coerce non-integer internal values to integers when\n+GraphQL services may coerce non-integer internal values to integers when\n reasonable without losing information, otherwise they must raise a field error.\n Examples of this may include returning `1` for the floating-point number `1.0`,\n or returning `123` for the string `\"123\"`. In scenarios where coercion may lose\n data, raising a field error is more appropriate. For example, a floating-point\n number `1.2` should raise a field error instead of being truncated to `1`.\n\n If the integer internal value represents a value less than -231 or\n greater than or equal to 231, a field error should be raised.\n\n **Input Coercion**\n\n When expected as an input type, only integer input values are accepted. All\n-other input values, including strings with numeric content, must raise a query\n+other input values, including strings with numeric content, must raise a request\n error indicating an incorrect type. If the integer input value represents a\n value less than -231 or greater than or equal to 231, a\n-query error should be raised.\n+request error should be raised.\n\n Note: Numeric integer values larger than 32-bit should either use String or a\n custom-defined Scalar type, as not all platforms and transports support\n encoding integer numbers larger than 32-bit.\n\n\n ### Float\n\n-The Float scalar type represents signed double-precision fractional values\n-as specified by [IEEE 754](http://en.wikipedia.org/wiki/IEEE_floating_point).\n-Response formats that support an appropriate double-precision number type\n-should use that type to represent this scalar.\n+The Float scalar type represents signed double-precision finite values as\n+specified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point).\n+Response formats that support an appropriate double-precision number type should\n+use that type to represent this scalar.\n\n **Result Coercion**\n\n-Fields returning the type `Float` expect to encounter double-precision\n+Fields returning the type {Float} expect to encounter double-precision\n floating-point internal values.\n\n-GraphQL servers may coerce non-floating-point internal values to `Float` when\n+GraphQL services may coerce non-floating-point internal values to {Float} when\n reasonable without losing information, otherwise they must raise a field error.\n Examples of this may include returning `1.0` for the integer number `1`, or\n `123.0` for the string `\"123\"`.\n\n+Non-finite floating-point internal values ({NaN} and {Infinity}) cannot be\n+coerced to {Float} and must raise a field error.\n+\n **Input Coercion**\n\n When expected as an input type, both integer and float input values are\n accepted. Integer input values are coerced to Float by adding an empty\n fractional part, for example `1.0` for the integer input value `1`. All\n-other input values, including strings with numeric content, must raise a query\n-error indicating an incorrect type. If the integer input value represents a\n-value not representable by IEEE 754, a query error should be raised.\n+other input values, including strings with numeric content, must raise a request\n+error indicating an incorrect type. If the input value otherwise represents a\n+value not representable by finite IEEE 754 (e.g. {NaN}, {Infinity}, or a value\n+outside the available precision), a request error must be raised.\n\n\n ### String\n\n-The String scalar type represents textual data, represented as UTF-8 character\n-sequences. The String type is most often used by GraphQL to represent free-form\n-human-readable text. All response formats must support string representations,\n-and that representation must be used here.\n+The String scalar type represents textual data, represented as a sequence of\n+Unicode code points. The String type is most often used by GraphQL to\n+represent free-form human-readable text. How the String is encoded internally\n+(for example UTF-8) is left to the service implementation. All response\n+serialization formats must support a string representation (for example, JSON\n+Unicode strings), and that representation must be used to serialize this type.\n\n **Result Coercion**\n\n-Fields returning the type `String` expect to encounter UTF-8 string internal values.\n+Fields returning the type {String} expect to encounter Unicode string values.\n\n-GraphQL servers may coerce non-string raw values to `String` when reasonable\n+GraphQL services may coerce non-string raw values to {String} when reasonable\n without losing information, otherwise they must raise a field error. Examples of\n this may include returning the string `\"true\"` for a boolean true value, or the\n string `\"1\"` for the integer `1`.\n\n **Input Coercion**\n\n-When expected as an input type, only valid UTF-8 string input values are\n-accepted. All other input values must raise a query error indicating an\n+When expected as an input type, only valid Unicode string input values are\n+accepted. All other input values must raise a request error indicating an\n incorrect type.\n\n\n ### Boolean\n\n The Boolean scalar type represents `true` or `false`. Response formats should\n use a built-in boolean type if supported; otherwise, they should use their\n representation of the integers `1` and `0`.\n\n **Result Coercion**\n\n-Fields returning the type `Boolean` expect to encounter boolean internal values.\n+Fields returning the type {Boolean} expect to encounter boolean internal values.\n\n-GraphQL servers may coerce non-boolean raw values to `Boolean` when reasonable\n+GraphQL services may coerce non-boolean raw values to {Boolean} when reasonable\n without losing information, otherwise they must raise a field error. Examples of\n this may include returning `true` for non-zero numbers.\n\n **Input Coercion**\n\n When expected as an input type, only boolean input values are accepted. All\n-other input values must raise a query error indicating an incorrect type.\n+other input values must raise a request error indicating an incorrect type.\n\n\n ### ID\n\n The ID scalar type represents a unique identifier, often used to refetch an\n object or as the key for a cache. The ID type is serialized in the same way as\n-a `String`; however, it is not intended to be human-readable. While it is\n-often numeric, it should always serialize as a `String`.\n+a {String}; however, it is not intended to be human-readable. While it is\n+often numeric, it should always serialize as a {String}.\n\n **Result Coercion**\n\n GraphQL is agnostic to ID format, and serializes to string to ensure consistency\n across many formats ID could represent, from small auto-increment numbers, to\n large 128-bit random numbers, to base64 encoded values, or string values of a\n-format like [GUID](http://en.wikipedia.org/wiki/Globally_unique_identifier).\n+format like [GUID](https://en.wikipedia.org/wiki/Globally_unique_identifier).\n\n-GraphQL servers should coerce as appropriate given the ID formats they expect.\n+GraphQL services should coerce as appropriate given the ID formats they expect.\n When coercion is not possible they must raise a field error.\n\n **Input Coercion**\n\n-When expected as an input type, any string (such as `\"4\"`) or integer (such\n-as `4`) input value should be coerced to ID as appropriate for the ID formats\n-a given GraphQL server expects. Any other input value, including float input\n-values (such as `4.0`), must raise a query error indicating an incorrect type.\n+When expected as an input type, any string (such as `\"4\"`) or integer (such as\n+`4` or `-4`) input value should be coerced to ID as appropriate for the ID\n+formats a given GraphQL service expects. Any other input value, including float\n+input values (such as `4.0`), must raise a request error indicating an incorrect\n+type.\n\n\n ### Scalar Extensions\n\n ScalarTypeExtension :\n - extend scalar Name Directives[Const]\n\n Scalar type extensions are used to represent a scalar type which has been\n extended from some original scalar type. For example, this might be used by a\n GraphQL tool or service which adds directives to an existing scalar.\n\n **Type Validation**\n\n Scalar type extensions have the potential to be invalid if incorrectly defined.\n\n 1. The named type must already be defined and must be a Scalar type.\n-2. Any directives provided must not already apply to the original Scalar type.\n+2. Any non-repeatable directives provided must not already apply to the\n+ original Scalar type.\n\n\n ## Objects\n\n-ObjectTypeDefinition : Description? type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition?\n+ObjectTypeDefinition :\n+ - Description? type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition\n+ - Description? type Name ImplementsInterfaces? Directives[Const]? [lookahead != `{`]\n\n ImplementsInterfaces :\n- - implements `&`? NamedType\n - ImplementsInterfaces & NamedType\n+ - implements `&`? NamedType\n\n FieldsDefinition : { FieldDefinition+ }\n\n FieldDefinition : Description? Name ArgumentsDefinition? : Type Directives[Const]?\n\n-GraphQL queries are hierarchical and composed, describing a tree of information.\n-While Scalar types describe the leaf values of these hierarchical queries, Objects\n-describe the intermediate levels.\n+GraphQL operations are hierarchical and composed, describing a tree of\n+information. While Scalar types describe the leaf values of these hierarchical\n+operations, Objects describe the intermediate levels.\n\n GraphQL Objects represent a list of named fields, each of which yield a value of\n a specific type. Object values should be serialized as ordered maps, where the\n-queried field names (or aliases) are the keys and the result of evaluating\n-the field is the value, ordered by the order in which they appear in the query.\n+selected field names (or aliases) are the keys and the result of evaluating\n+the field is the value, ordered by the order in which they appear in\n+the selection set.\n\n All fields defined within an Object type must not have a name which begins with\n {\"__\"} (two underscores), as this is used exclusively by GraphQL's\n introspection system.\n\n For example, a type `Person` could be described as:\n\n ```graphql example\n type Person {\n name: String\n age: Int\n picture: Url\n }\n ```\n\n-Where `name` is a field that will yield a `String` value, and `age` is a field\n-that will yield an `Int` value, and `picture` is a field that will yield a\n+Where `name` is a field that will yield a {String} value, and `age` is a field\n+that will yield an {Int} value, and `picture` is a field that will yield a\n `Url` value.\n\n A query of an object value must select at least one field. This selection of\n fields will yield an ordered map containing exactly the subset of the object\n queried, which should be represented in the order in which they were queried.\n Only fields that are declared on the object type may validly be queried on\n that object.\n\n@@ -640,18 +714,18 @@ For example, the `Person` type might include a `relationship`:\n type Person {\n name: String\n age: Int\n picture: Url\n relationship: Person\n }\n ```\n\n-Valid queries must supply a nested field set for a field that returns\n-an object, so this query is not valid:\n+Valid operations must supply a nested field set for any field that returns an\n+object, so this operation is not valid:\n\n ```graphql counter-example\n {\n name\n relationship\n }\n ```\n\n@@ -675,17 +749,17 @@ And will yield the subset of each object type queried:\n \"name\": \"Priscilla Chan\"\n }\n }\n ```\n\n **Field Ordering**\n\n When querying an Object, the resulting mapping of fields are conceptually\n-ordered in the same order in which they were encountered during query execution,\n+ordered in the same order in which they were encountered during execution,\n excluding fragments for which the type does not apply and fields or\n fragments that are skipped via `@skip` or `@include` directives. This ordering\n is correctly produced when using the {CollectFields()} algorithm.\n\n Response serialization formats capable of representing ordered maps should\n maintain this ordering. Serialization formats which can only represent unordered\n maps (such as JSON) should retain this order textually. That is, if two fields\n `{foo, bar}` were queried in that order, the resulting JSON serialization\n@@ -798,41 +872,64 @@ of rules must be adhered to by every Object type in a GraphQL schema.\n 2. The field must not have a name which begins with the\n characters {\"__\"} (two underscores).\n 3. The field must return a type where {IsOutputType(fieldType)} returns {true}.\n 4. For each argument of the field:\n 1. The argument must not have a name which begins with the\n characters {\"__\"} (two underscores).\n 2. The argument must accept a type where {IsInputType(argumentType)}\n returns {true}.\n-4. An object type may declare that it implements one or more unique interfaces.\n-5. An object type must be a super-set of all interfaces it implements:\n- 1. The object type must include a field of the same name for every field\n- defined in an interface.\n- 1. The object field must be of a type which is equal to or a sub-type of\n- the interface field (covariant).\n- 1. An object field type is a valid sub-type if it is equal to (the same\n- type as) the interface field type.\n- 2. An object field type is a valid sub-type if it is an Object type and\n- the interface field type is either an Interface type or a Union type\n- and the object field type is a possible type of the interface field\n- type.\n- 3. An object field type is a valid sub-type if it is a List type and\n- the interface field type is also a List type and the list-item type\n- of the object field type is a valid sub-type of the list-item type\n- of the interface field type.\n- 4. An object field type is a valid sub-type if it is a Non-Null variant\n- of a valid sub-type of the interface field type.\n- 2. The object field must include an argument of the same name for every\n- argument defined in the interface field.\n- 1. The object field argument must accept the same type (invariant) as\n- the interface field argument.\n- 3. The object field may include additional arguments not defined in the\n- interface field, but any additional argument must not be required, e.g.\n- must not be of a non-nullable type.\n+3. An object type may declare that it implements one or more unique interfaces.\n+4. An object type must be a super-set of all interfaces it implements:\n+ 1. Let this object type be {objectType}.\n+ 2. For each interface declared implemented as {interfaceType},\n+ {IsValidImplementation(objectType, interfaceType)} must be {true}.\n+\n+IsValidImplementation(type, implementedType):\n+\n+ 1. If {implementedType} declares it implements any interfaces,\n+ {type} must also declare it implements those interfaces.\n+ 2. {type} must include a field of the same name for every field\n+ defined in {implementedType}.\n+ 1. Let {field} be that named field on {type}.\n+ 2. Let {implementedField} be that named field on {implementedType}.\n+ 3. {field} must include an argument of the same name for every argument\n+ defined in {implementedField}.\n+ 1. That named argument on {field} must accept the same type\n+ (invariant) as that named argument on {implementedField}.\n+ 4. {field} may include additional arguments not defined in\n+ {implementedField}, but any additional argument must not be required,\n+ e.g. must not be of a non-nullable type.\n+ 5. {field} must return a type which is equal to or a sub-type of\n+ (covariant) the return type of {implementedField} field's return type:\n+ 1. Let {fieldType} be the return type of {field}.\n+ 2. Let {implementedFieldType} be the return type of {implementedField}.\n+ 3. {IsValidImplementationFieldType(fieldType, implementedFieldType)}\n+ must be {true}.\n+\n+IsValidImplementationFieldType(fieldType, implementedFieldType):\n+ 1. If {fieldType} is a Non-Null type:\n+ 1. Let {nullableType} be the unwrapped nullable type of {fieldType}.\n+ 2. Let {implementedNullableType} be the unwrapped nullable type\n+ of {implementedFieldType} if it is a Non-Null type, otherwise let it be\n+ {implementedFieldType} directly.\n+ 3. Return {IsValidImplementationFieldType(nullableType, implementedNullableType)}.\n+ 2. If {fieldType} is a List type and {implementedFieldType} is also a List type:\n+ 1. Let {itemType} be the unwrapped item type of {fieldType}.\n+ 2. Let {implementedItemType} be the unwrapped item type\n+ of {implementedFieldType}.\n+ 3. Return {IsValidImplementationFieldType(itemType, implementedItemType)}.\n+ 3. If {fieldType} is the same type as {implementedFieldType} then return {true}.\n+ 4. If {fieldType} is an Object type and {implementedFieldType} is\n+ a Union type and {fieldType} is a possible type of {implementedFieldType}\n+ then return {true}.\n+ 5. If {fieldType} is an Object or Interface type and {implementedFieldType}\n+ is an Interface type and {fieldType} declares it implements\n+ {implementedFieldType} then return {true}.\n+ 6. Otherwise return {false}.\n\n\n ### Field Arguments\n\n ArgumentsDefinition : ( InputValueDefinition+ )\n\n InputValueDefinition : Description? Name : Type DefaultValue? Directives[Const]?\n\n@@ -850,64 +947,64 @@ determine what size of an image to return.\n\n ```graphql example\n type Person {\n name: String\n picture(size: Int): Url\n }\n ```\n\n-GraphQL queries can optionally specify arguments to their fields to provide\n+Operations can optionally specify arguments to their fields to provide\n these arguments.\n\n-This example query:\n+This example operation:\n\n ```graphql example\n {\n name\n picture(size: 600)\n }\n ```\n\n-May yield the result:\n+May return the result:\n\n ```json example\n {\n \"name\": \"Mark Zuckerberg\",\n \"picture\": \"http://some.cdn/picture_600.jpg\"\n }\n ```\n\n The type of an object field argument must be an input type (any type except an\n Object, Interface, or Union type).\n\n\n ### Field Deprecation\n\n Fields in an object may be marked as deprecated as deemed necessary by the\n-application. It is still legal to query for these fields (to ensure existing\n-clients are not broken by the change), but the fields should be appropriately\n-treated in documentation and tooling.\n+application. It is still legal to include these fields in a selection set\n+(to ensure existing clients are not broken by the change), but the fields should\n+be appropriately treated in documentation and tooling.\n\n When using the type system definition language, `@deprecated` directives are\n used to indicate that a field is deprecated:\n\n ```graphql example\n type ExampleType {\n oldField: String @deprecated\n }\n ```\n\n\n ### Object Extensions\n\n ObjectTypeExtension :\n - extend type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition\n- - extend type Name ImplementsInterfaces? Directives[Const]\n- - extend type Name ImplementsInterfaces\n+ - extend type Name ImplementsInterfaces? Directives[Const] [lookahead != `{`]\n+ - extend type Name ImplementsInterfaces [lookahead != `{`]\n\n Object type extensions are used to represent a type which has been extended from\n some original type. For example, this might be used to represent local data, or\n by a GraphQL service which is itself an extension of another GraphQL service.\n\n In this example, a local data field is added to a `Story` type:\n\n ```graphql example\n@@ -929,30 +1026,33 @@ extend type User @addedDirective\n\n Object type extensions have the potential to be invalid if incorrectly defined.\n\n 1. The named type must already be defined and must be an Object type.\n 2. The fields of an Object type extension must have unique names; no two fields\n may share the same name.\n 3. Any fields of an Object type extension must not be already defined on the\n original Object type.\n-4. Any directives provided must not already apply to the original Object type.\n+4. Any non-repeatable directives provided must not already apply to the\n+ original Object type.\n 5. Any interfaces provided must not be already implemented by the original\n Object type.\n 6. The resulting extended object type must be a super-set of all interfaces it\n implements.\n\n\n ## Interfaces\n\n-InterfaceTypeDefinition : Description? interface Name Directives[Const]? FieldsDefinition?\n+InterfaceTypeDefinition :\n+ - Description? interface Name ImplementsInterfaces? Directives[Const]? FieldsDefinition\n+ - Description? interface Name ImplementsInterfaces? Directives[Const]? [lookahead != `{`]\n\n GraphQL interfaces represent a list of named fields and their arguments. GraphQL\n-objects can then implement these interfaces which requires that the object type\n-will define all fields defined by those interfaces.\n+objects and interfaces can then implement these interfaces which requires that\n+the implementing type will define all fields defined by those interfaces.\n\n Fields on a GraphQL interface have the same rules as fields on a GraphQL object;\n their type can be Scalar, Object, Enum, Interface, or Union, or any wrapping\n type whose base type is one of those five.\n\n For example, an interface `NamedEntity` may describe a required field and types\n such as `Person` or `Business` may then implement this interface to guarantee\n this field will always exist.\n@@ -989,59 +1089,116 @@ To continue the example, a `Contact` might refer to `NamedEntity`.\n ```graphql example\n type Contact {\n entity: NamedEntity\n phoneNumber: String\n address: String\n }\n ```\n\n-This allows us to write a query for a `Contact` that can select the\n+This allows us to write a selection set for a `Contact` that can select the\n common fields.\n\n ```graphql example\n {\n entity {\n name\n }\n phoneNumber\n }\n ```\n\n-When querying for fields on an interface type, only those fields declared on\n+When selecting fields on an interface type, only those fields declared on\n the interface may be queried. In the above example, `entity` returns a\n `NamedEntity`, and `name` is defined on `NamedEntity`, so it is valid. However,\n-the following would not be a valid query:\n+the following would not be a valid selection set against `Contact`:\n\n ```graphql counter-example\n {\n entity {\n name\n age\n }\n phoneNumber\n }\n ```\n\n because `entity` refers to a `NamedEntity`, and `age` is not defined on that\n interface. Querying for `age` is only valid when the result of `entity` is a\n-`Person`; the query can express this using a fragment or an inline fragment:\n+`Person`; this can be expressed using a fragment or an inline fragment:\n\n ```graphql example\n {\n entity {\n name\n ... on Person {\n age\n }\n- },\n+ }\n phoneNumber\n }\n ```\n\n+**Interfaces Implementing Interfaces**\n+\n+When defining an interface that implements another interface, the implementing\n+interface must define each field that is specified by the implemented interface.\n+For example, the interface Resource must define the field id to implement the\n+Node interface:\n+\n+```raw graphql example\n+interface Node {\n+ id: ID!\n+}\n+\n+interface Resource implements Node {\n+ id: ID!\n+ url: String\n+}\n+```\n+\n+Transitively implemented interfaces (interfaces implemented by the interface\n+that is being implemented) must also be defined on an implementing type or\n+interface. For example, `Image` cannot implement `Resource` without also\n+implementing `Node`:\n+\n+```raw graphql example\n+interface Node {\n+ id: ID!\n+}\n+\n+interface Resource implements Node {\n+ id: ID!\n+ url: String\n+}\n+\n+interface Image implements Resource & Node {\n+ id: ID!\n+ url: String\n+ thumbnail: String\n+}\n+```\n+\n+Interface definitions must not contain cyclic references nor implement\n+themselves. This example is invalid because `Node` and `Named` implement\n+themselves and each other:\n+\n+```graphql counter-example\n+interface Node implements Named & Node {\n+ id: ID!\n+ name: String\n+}\n+\n+interface Named implements Node & Named {\n+ id: ID!\n+ name: String\n+}\n+```\n+\n+\n **Result Coercion**\n\n The interface type should have some way of determining which object a given\n result corresponds to. Once it has done so, the result coercion of the interface\n is the same as the result coercion of the object.\n\n **Input Coercion**\n\n@@ -1059,23 +1216,30 @@ Interface types have the potential to be invalid if incorrectly defined.\n characters {\"__\"} (two underscores).\n 3. The field must return a type where {IsOutputType(fieldType)}\n returns {true}.\n 4. For each argument of the field:\n 1. The argument must not have a name which begins with the\n characters {\"__\"} (two underscores).\n 2. The argument must accept a type where {IsInputType(argumentType)}\n returns {true}.\n+3. An interface type may declare that it implements one or more unique\n+ interfaces, but may not implement itself.\n+4. An interface type must be a super-set of all interfaces it implements:\n+ 1. Let this interface type be {implementingType}.\n+ 2. For each interface declared implemented as {implementedType},\n+ {IsValidImplementation(implementingType, implementedType)} must be {true}.\n\n\n ### Interface Extensions\n\n InterfaceTypeExtension :\n- - extend interface Name Directives[Const]? FieldsDefinition\n- - extend interface Name Directives[Const]\n+ - extend interface Name ImplementsInterfaces? Directives[Const]? FieldsDefinition\n+ - extend interface Name ImplementsInterfaces? Directives[Const] [lookahead != `{`]\n+ - extend interface Name ImplementsInterfaces [lookahead != `{`]\n\n Interface type extensions are used to represent an interface which has been\n extended from some original interface. For example, this might be used to\n represent common local data on many types, or by a GraphQL service which is\n itself an extension of another GraphQL service.\n\n In this example, an extended data field is added to a `NamedEntity` type along\n with the types which implement it:\n@@ -1108,40 +1272,44 @@ extend interface NamedEntity @addedDirective\n\n Interface type extensions have the potential to be invalid if incorrectly defined.\n\n 1. The named type must already be defined and must be an Interface type.\n 2. The fields of an Interface type extension must have unique names; no two\n fields may share the same name.\n 3. Any fields of an Interface type extension must not be already defined on the\n original Interface type.\n-4. Any Object type which implemented the original Interface type must also be a\n- super-set of the fields of the Interface type extension (which may be due to\n- Object type extension).\n-5. Any directives provided must not already apply to the original Interface type.\n+4. Any Object or Interface type which implemented the original Interface type\n+ must also be a super-set of the fields of the Interface type extension (which\n+ may be due to Object type extension).\n+5. Any non-repeatable directives provided must not already apply to the\n+ original Interface type.\n+6. The resulting extended Interface type must be a super-set of all Interfaces\n+ it implements.\n\n\n ## Unions\n\n UnionTypeDefinition : Description? union Name Directives[Const]? UnionMemberTypes?\n\n UnionMemberTypes :\n- - = `|`? NamedType\n - UnionMemberTypes | NamedType\n+ - = `|`? NamedType\n\n GraphQL Unions represent an object that could be one of a list of GraphQL\n Object types, but provides for no guaranteed fields between those types.\n They also differ from interfaces in that Object types declare what interfaces\n they implement, but are not aware of what unions contain them.\n\n With interfaces and objects, only those fields defined on the type can be\n queried directly; to query other fields on an interface, typed fragments\n must be used. This is the same as for unions, but unions do not define any\n fields, so **no** fields may be queried on this type without the use of\n-type refining fragments or inline fragments.\n+type refining fragments or inline fragments (with the exception of the\n+meta-field {__typename}).\n\n For example, we might define the following types:\n\n ```graphql example\n union SearchResult = Photo | Person\n\n type Person {\n name: String\n@@ -1153,32 +1321,30 @@ type Photo {\n width: Int\n }\n\n type SearchQuery {\n firstSearchResult: SearchResult\n }\n ```\n\n-When querying the `firstSearchResult` field of type `SearchQuery`, the\n-query would ask for all fields inside of a fragment indicating the appropriate\n-type. If the query wanted the name if the result was a Person, and the height if\n-it was a photo, the following query is invalid, because the union itself\n-defines no fields:\n+In this example, a query operation wants the name if the result was a Person,\n+and the height if it was a photo. However because a union itself defines no\n+fields, this could be ambiguous and is invalid.\n\n ```graphql counter-example\n {\n firstSearchResult {\n name\n height\n }\n }\n ```\n\n-Instead, the query would be:\n+A valid operation includes typed fragments (in this example, inline fragments):\n\n ```graphql example\n {\n firstSearchResult {\n ... on Person {\n name\n }\n ... on Photo {\n@@ -1186,17 +1352,17 @@ Instead, the query would be:\n }\n }\n }\n ```\n\n Union members may be defined with an optional leading `|` character to aid\n formatting when representing a longer list of possible types:\n\n-```graphql example\n+```raw graphql example\n union SearchResult =\n | Photo\n | Person\n ```\n\n **Result Coercion**\n\n The union type should have some way of determining which object a given result\n@@ -1234,27 +1400,30 @@ Union type extensions have the potential to be invalid if incorrectly defined.\n\n 1. The named type must already be defined and must be a Union type.\n 2. The member types of a Union type extension must all be Object base types;\n Scalar, Interface and Union types must not be member types of a Union.\n Similarly, wrapping types must not be member types of a Union.\n 3. All member types of a Union type extension must be unique.\n 4. All member types of a Union type extension must not already be a member of\n the original Union type.\n-5. Any directives provided must not already apply to the original Union type.\n+5. Any non-repeatable directives provided must not already apply to the\n+ original Union type.\n\n ## Enums\n\n-EnumTypeDefinition : Description? enum Name Directives[Const]? EnumValuesDefinition?\n+EnumTypeDefinition :\n+ - Description? enum Name Directives[Const]? EnumValuesDefinition\n+ - Description? enum Name Directives[Const]? [lookahead != `{`]\n\n EnumValuesDefinition : { EnumValueDefinition+ }\n\n EnumValueDefinition : Description? EnumValue Directives[Const]?\n\n-GraphQL Enum types, like scalar types, also represent leaf values in a GraphQL\n+GraphQL Enum types, like Scalar types, also represent leaf values in a GraphQL\n type system. However Enum types describe the set of possible values.\n\n Enums are not references for a numeric value, but are unique values in their own\n right. They may serialize as a string: the name of the represented value.\n\n In this example, an Enum type called `Direction` is defined:\n\n ```graphql example\n@@ -1263,62 +1432,65 @@ enum Direction {\n EAST\n SOUTH\n WEST\n }\n ```\n\n **Result Coercion**\n\n-GraphQL servers must return one of the defined set of possible values. If a\n+GraphQL services must return one of the defined set of possible values. If a\n reasonable coercion is not possible they must raise a field error.\n\n **Input Coercion**\n\n GraphQL has a constant literal to represent enum input values. GraphQL string\n-literals must not be accepted as an enum input and instead raise a query error.\n+literals must not be accepted as an enum input and instead raise a request error.\n\n-Query variable transport serializations which have a different representation\n+Variable transport serializations which have a different representation\n for non-string symbolic values (for example, [EDN](https://github.com/edn-format/edn))\n should only allow such values as enum input values. Otherwise, for most\n transport serializations that do not, strings may be interpreted as the enum\n input value with the same name.\n\n **Type Validation**\n\n Enum types have the potential to be invalid if incorrectly defined.\n\n 1. An Enum type must define one or more unique enum values.\n\n\n ### Enum Extensions\n\n EnumTypeExtension :\n - extend enum Name Directives[Const]? EnumValuesDefinition\n- - extend enum Name Directives[Const]\n+ - extend enum Name Directives[Const] [lookahead != `{`]\n\n Enum type extensions are used to represent an enum type which has been\n extended from some original enum type. For example, this might be used to\n represent additional local data, or by a GraphQL service which is itself an\n extension of another GraphQL service.\n\n **Type Validation**\n\n Enum type extensions have the potential to be invalid if incorrectly defined.\n\n 1. The named type must already be defined and must be an Enum type.\n 2. All values of an Enum type extension must be unique.\n 3. All values of an Enum type extension must not already be a value of\n the original Enum.\n-4. Any directives provided must not already apply to the original Enum type.\n+4. Any non-repeatable directives provided must not already apply to the\n+ original Enum type.\n\n\n ## Input Objects\n\n-InputObjectTypeDefinition : Description? input Name Directives[Const]? InputFieldsDefinition?\n+InputObjectTypeDefinition :\n+ - Description? input Name Directives[Const]? InputFieldsDefinition\n+ - Description? input Name Directives[Const]? [lookahead != `{`]\n\n InputFieldsDefinition : { InputValueDefinition+ }\n\n Fields may accept arguments to configure their behavior. These inputs are often\n scalars or enums, but they sometimes need to represent more complex values.\n\n A GraphQL Input Object defines a set of input fields; the input fields are either\n scalars, enums, or other input objects. This allows arguments to accept\n@@ -1334,51 +1506,105 @@ input Point2D {\n ```\n\n Note: The GraphQL Object type ({ObjectTypeDefinition}) defined above is\n inappropriate for re-use here, because Object types can contain fields that\n define arguments or contain references to interfaces and unions, neither of\n which is appropriate for use as an input argument. For this reason, input\n objects have a separate type in the system.\n\n+**Circular References**\n+\n+Input Objects are allowed to reference other Input Objects as field types. A\n+circular reference occurs when an Input Object references itself either directly\n+or through referenced Input Objects.\n+\n+Circular references are generally allowed, however they may not be defined as an\n+unbroken chain of Non-Null singular fields. Such Input Objects are invalid\n+because there is no way to provide a legal value for them.\n+\n+This example of a circularly-referenced input type is valid as the field `self`\n+may be omitted or the value {null}.\n+\n+```graphql example\n+input Example {\n+ self: Example\n+ value: String\n+}\n+```\n+\n+This example is also valid as the field `self` may be an empty List.\n+\n+```graphql example\n+input Example {\n+ self: [Example!]!\n+ value: String\n+}\n+```\n+\n+This example of a circularly-referenced input type is invalid as the field\n+`self` cannot be provided a finite value.\n+\n+```graphql counter-example\n+input Example {\n+ value: String\n+ self: Example!\n+}\n+```\n+\n+This example is also invalid, as there is a non-null singular circular reference\n+via the `First.second` and `Second.first` fields.\n+\n+```graphql counter-example\n+input First {\n+ second: Second!\n+ value: String\n+}\n+\n+input Second {\n+ first: First!\n+ value: String\n+}\n+```\n+\n **Result Coercion**\n\n An input object is never a valid result. Input Object types cannot be the return\n type of an Object or Interface field.\n\n **Input Coercion**\n\n The value for an input object should be an input object literal or an unordered\n-map supplied by a variable, otherwise a query error must be thrown. In either\n+map supplied by a variable, otherwise a request error must be raised. In either\n case, the input object literal or unordered map must not contain any entries\n-with names not defined by a field of this input object type, otherwise an error\n-must be thrown.\n+with names not defined by a field of this input object type, otherwise a\n+response error must be raised.\n\n The result of coercion is an unordered map with an entry for each field both\n defined by the input object type and for which a value exists. The resulting map\n is constructed with the following rules:\n\n * If no value is provided for a defined input object field and that field\n definition provides a default value, the default value should be used. If no\n default value is provided and the input object field's type is non-null, an\n- error should be thrown. Otherwise, if the field is not required, then no entry\n+ error should be raised. Otherwise, if the field is not required, then no entry\n is added to the coerced unordered map.\n\n * If the value {null} was provided for an input object field, and the field's\n type is not a non-null type, an entry in the coerced unordered map is given\n the value {null}. In other words, there is a semantic difference between the\n explicitly provided value {null} versus having not provided a value.\n\n * If a literal value is provided for an input object field, an entry in the\n coerced unordered map is given the result of coercing that value according\n to the input coercion rules for the type of that field.\n\n * If a variable is provided for an input object field, the runtime value of that\n variable must be used. If the runtime value is {null} and the field type\n- is non-null, a field error must be thrown. If no runtime value is provided,\n+ is non-null, a field error must be raised. If no runtime value is provided,\n the variable definition's default value should be used. If the variable\n definition does not provide a default value, the input object field\n definition's default value should be used.\n\n Following are examples of input coercion for an input object type with a\n `String` field `a` and a required (non-null) `Int!` field `b`:\n\n ```graphql example\n@@ -1393,17 +1619,17 @@ Literal Value | Variables | Coerced Value\n `{ a: \"abc\", b: 123 }` | `{}` | `{ a: \"abc\", b: 123 }`\n `{ a: null, b: 123 }` | `{}` | `{ a: null, b: 123 }`\n `{ b: 123 }` | `{}` | `{ b: 123 }`\n `{ a: $var, b: 123 }` | `{ var: null }` | `{ a: null, b: 123 }`\n `{ a: $var, b: 123 }` | `{}` | `{ b: 123 }`\n `{ b: $var }` | `{ var: 123 }` | `{ b: 123 }`\n `$var` | `{ var: { b: 123 } }` | `{ b: 123 }`\n `\"abc123\"` | `{}` | Error: Incorrect value\n-`$var` | `{ var: \"abc123\" } }` | Error: Incorrect value\n+`$var` | `{ var: \"abc123\" }` | Error: Incorrect value\n `{ a: \"abc\", b: \"123\" }` | `{}` | Error: Incorrect value for field {b}\n `{ a: \"abc\" }` | `{}` | Error: Missing required field {b}\n `{ b: $var }` | `{}` | Error: Missing required field {b}.\n `$var` | `{ var: { a: \"abc\" } }` | Error: Missing required field {b}\n `{ a: \"abc\", b: null }` | `{}` | Error: {b} must be non-null.\n `{ b: $var }` | `{ var: null }` | Error: {b} must be non-null.\n `{ b: 123, c: \"xyz\" }` | `{}` | Error: Unexpected field {c}\n\n@@ -1412,89 +1638,95 @@ Literal Value | Variables | Coerced Value\n 1. An Input Object type must define one or more input fields.\n 2. For each input field of an Input Object type:\n 1. The input field must have a unique name within that Input Object type;\n no two input fields may share the same name.\n 2. The input field must not have a name which begins with the\n characters {\"__\"} (two underscores).\n 3. The input field must accept a type where {IsInputType(inputFieldType)}\n returns {true}.\n+3. If an Input Object references itself either directly or through referenced\n+ Input Objects, at least one of the fields in the chain of references must be\n+ either a nullable or a List type.\n\n\n ### Input Object Extensions\n\n InputObjectTypeExtension :\n - extend input Name Directives[Const]? InputFieldsDefinition\n- - extend input Name Directives[Const]\n+ - extend input Name Directives[Const] [lookahead != `{`]\n\n Input object type extensions are used to represent an input object type which\n has been extended from some original input object type. For example, this might\n be used by a GraphQL service which is itself an extension of another GraphQL service.\n\n **Type Validation**\n\n Input object type extensions have the potential to be invalid if incorrectly defined.\n\n 1. The named type must already be defined and must be a Input Object type.\n-3. All fields of an Input Object type extension must have unique names.\n-4. All fields of an Input Object type extension must not already be a field of\n+2. All fields of an Input Object type extension must have unique names.\n+3. All fields of an Input Object type extension must not already be a field of\n the original Input Object.\n-5. Any directives provided must not already apply to the original Input Object type.\n+4. Any non-repeatable directives provided must not already apply to the\n+ original Input Object type.\n\n\n ## List\n\n A GraphQL list is a special collection type which declares the type of each\n item in the List (referred to as the *item type* of the list). List values are\n serialized as ordered lists, where each item in the list is serialized as per\n-the item type. To denote that a field uses a List type the item type is wrapped\n-in square brackets like this: `pets: [Pet]`.\n+the item type.\n+\n+To denote that a field uses a List type the item type is wrapped in square brackets\n+like this: `pets: [Pet]`. Nesting lists is allowed: `matrix: [[Int]]`.\n\n **Result Coercion**\n\n-GraphQL servers must return an ordered list as the result of a list type. Each\n+GraphQL services must return an ordered list as the result of a list type. Each\n item in the list must be the result of a result coercion of the item type. If a\n reasonable coercion is not possible it must raise a field error. In\n particular, if a non-list is returned, the coercion should fail, as this\n indicates a mismatch in expectations between the type system and the\n implementation.\n\n-If a list's item type is nullable, then errors occuring during preparation or\n+If a list's item type is nullable, then errors occurring during preparation or\n coercion of an individual item in the list must result in a the value {null} at\n-that position in the list along with an error added to the response. If a list's\n-item type is non-null, an error occuring at an individual item in the list must\n-result in a field error for the entire list.\n+that position in the list along with a field error added to the response.\n+If a list's item type is non-null, a field error occurring at an individual item\n+in the list must result in a field error for the entire list.\n\n-Note: For more information on the error handling process, see \"Errors and\n-Non-Nullability\" within the Execution section.\n+Note: See [Handling Field Errors](#sec-Handling-Field-Errors) for more about\n+this behavior.\n\n **Input Coercion**\n\n When expected as an input, list values are accepted only when each item in the\n list can be accepted by the list's item type.\n\n If the value passed as an input to a list type is *not* a list and not the\n {null} value, then the result of input coercion is a list of size one,\n where the single item value is the result of input coercion for the list's item\n type on the provided value (note this may apply recursively for nested lists).\n\n-This allow inputs which accept one or many arguments (sometimes referred to as\n+This allows inputs which accept one or many arguments (sometimes referred to as\n \"var args\") to declare their input type as a list while for the common case of a\n single value, a client can just pass that value directly rather than\n constructing the list.\n\n Following are examples of input coercion with various list types and values:\n\n Expected Type | Provided Value | Coerced Value\n ------------- | ---------------- | ---------------------------\n `[Int]` | `[1, 2, 3]` | `[1, 2, 3]`\n `[Int]` | `[1, \"b\", true]` | Error: Incorrect item value\n `[Int]` | `1` | `[1]`\n `[Int]` | `null` | `null`\n-`[[Int]]` | `[[1], [2, 3]]` | `[[1], [2, 3]`\n+`[[Int]]` | `[[1], [2, 3]]` | `[[1], [2, 3]]`\n `[[Int]]` | `[1, 2, 3]` | Error: Incorrect item value\n `[[Int]]` | `1` | `[[1]]`\n `[[Int]]` | `null` | `null`\n\n\n ## Non-Null\n\n By default, all types in GraphQL are nullable; the {null} value is a valid\n@@ -1502,43 +1734,43 @@ response for all of the above types. To declare a type that disallows null,\n the GraphQL Non-Null type can be used. This type wraps an underlying type,\n and this type acts identically to that wrapped type, with the exception\n that {null} is not a valid response for the wrapping type. A trailing\n exclamation mark is used to denote a field that uses a Non-Null type like this:\n `name: String!`.\n\n **Nullable vs. Optional**\n\n-Fields are *always* optional within the context of a query, a field may be\n-omitted and the query is still valid. However fields that return Non-Null types\n-will never return the value {null} if queried.\n+Fields are *always* optional within the context of a selection set, a field may\n+be omitted and the selection set is still valid. However fields that return\n+Non-Null types will never return the value {null} if queried.\n\n Inputs (such as field arguments), are always optional by default. However a\n non-null input type is required. In addition to not accepting the value {null},\n it also does not accept omission. For the sake of simplicity nullable types\n are always optional and non-null types are always required.\n\n **Result Coercion**\n\n In all of the above result coercions, {null} was considered a valid value.\n To coerce the result of a Non-Null type, the coercion of the wrapped type\n should be performed. If that result was not {null}, then the result of coercing\n the Non-Null type is that result. If that result was {null}, then a field error\n must be raised.\n\n-Note: When a field error is raised on a non-null value, the error propogates to\n+Note: When a field error is raised on a non-null value, the error propagates to\n the parent field. For more information on this process, see\n \"Errors and Non-Nullability\" within the Execution section.\n\n **Input Coercion**\n\n If an argument or input-object field of a Non-Null type is not provided, is\n provided with the literal value {null}, or is provided with a variable that was\n either not provided a value at runtime, or was provided the value {null}, then\n-a query error must be raised.\n+a request error must be raised.\n\n If the value provided to the Non-Null type is provided with a literal value\n other than {null}, or a Non-Null variable value, it is coerced using the input\n coercion for the wrapped type.\n\n A non-null argument cannot be omitted:\n\n ```graphql counter-example\n@@ -1601,74 +1833,103 @@ Expected Type | Internal Value | Coerced Result\n `[Int!]!` | `[1, 2, 3]` | `[1, 2, 3]`\n `[Int!]!` | `null` | Error: Value cannot be null\n `[Int!]!` | `[1, 2, null]` | Error: Item cannot be null\n `[Int!]!` | `[1, 2, Error]` | Error: Error occurred in item\n\n\n ## Directives\n\n-DirectiveDefinition : Description? directive @ Name ArgumentsDefinition? on DirectiveLocations\n+DirectiveDefinition : Description? directive @ Name ArgumentsDefinition? `repeatable`? on DirectiveLocations\n\n DirectiveLocations :\n- - `|`? DirectiveLocation\n - DirectiveLocations | DirectiveLocation\n+ - `|`? DirectiveLocation\n\n DirectiveLocation :\n - ExecutableDirectiveLocation\n - TypeSystemDirectiveLocation\n\n ExecutableDirectiveLocation : one of\n- `QUERY`\n- `MUTATION`\n- `SUBSCRIPTION`\n- `FIELD`\n- `FRAGMENT_DEFINITION`\n- `FRAGMENT_SPREAD`\n- `INLINE_FRAGMENT`\n+ - `QUERY`\n+ - `MUTATION`\n+ - `SUBSCRIPTION`\n+ - `FIELD`\n+ - `FRAGMENT_DEFINITION`\n+ - `FRAGMENT_SPREAD`\n+ - `INLINE_FRAGMENT`\n+ - `VARIABLE_DEFINITION`\n\n TypeSystemDirectiveLocation : one of\n- `SCHEMA`\n- `SCALAR`\n- `OBJECT`\n- `FIELD_DEFINITION`\n- `ARGUMENT_DEFINITION`\n- `INTERFACE`\n- `UNION`\n- `ENUM`\n- `ENUM_VALUE`\n- `INPUT_OBJECT`\n- `INPUT_FIELD_DEFINITION`\n+ - `SCHEMA`\n+ - `SCALAR`\n+ - `OBJECT`\n+ - `FIELD_DEFINITION`\n+ - `ARGUMENT_DEFINITION`\n+ - `INTERFACE`\n+ - `UNION`\n+ - `ENUM`\n+ - `ENUM_VALUE`\n+ - `INPUT_OBJECT`\n+ - `INPUT_FIELD_DEFINITION`\n\n A GraphQL schema describes directives which are used to annotate various parts\n of a GraphQL document as an indicator that they should be evaluated differently\n by a validator, executor, or client tool such as a code generator.\n\n+**Built-in Directives**\n+\n+:: A *built-in directive* is any directive defined within this specification.\n+\n GraphQL implementations should provide the `@skip` and `@include` directives.\n\n GraphQL implementations that support the type system definition language must\n provide the `@deprecated` directive if representing deprecated portions of\n the schema.\n\n+GraphQL implementations that support the type system definition language should\n+provide the `@specifiedBy` directive if representing custom scalar\n+definitions.\n+\n+When representing a GraphQL schema using the type system definition language\n+any *built-in directive* may be omitted for brevity.\n+\n+When introspecting a GraphQL service all provided directives, including\n+any *built-in directive*, must be included in the set of returned directives.\n+\n+**Custom Directives**\n+\n+:: GraphQL services and client tooling may provide any additional\n+*custom directive* beyond those defined in this document. Directives are the\n+preferred way to extend GraphQL with custom or experimental behavior.\n+\n+Note: When defining a *custom directive*, it is recommended to prefix the\n+directive's name to make its scope of usage clear and to prevent a collision\n+with *built-in directive* which may be specified by future versions of this\n+document (which will not include `_` in their name). For example, a\n+*custom directive* used by Facebook's GraphQL service should be named `@fb_auth`\n+instead of `@auth`. This is especially recommended for proposed additions to\n+this specification which can change during the [RFC process](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md).\n+For example a work in progress version of `@live` should be named `@rfc_live`.\n+\n Directives must only be used in the locations they are declared to belong in.\n-In this example, a directive is defined which can be used to annotate a\n-fragment definition:\n+In this example, a directive is defined which can be used to annotate a field:\n\n ```graphql example\n directive @example on FIELD\n\n fragment SomeFragment on SomeType {\n field @example\n }\n ```\n\n Directive locations may be defined with an optional leading `|` character to aid\n formatting when representing a longer list of possible locations:\n\n-```graphql example\n+```raw graphql example\n directive @example on\n | FIELD\n | FRAGMENT_SPREAD\n | INLINE_FRAGMENT\n ```\n\n Directives can also be used to annotate the type system definition language\n as well, which can be a useful tool for supplying additional metadata in order\n@@ -1680,22 +1941,41 @@ In this example, the directive `@example` annotates field and argument definitio\n ```graphql example\n directive @example on FIELD_DEFINITION | ARGUMENT_DEFINITION\n\n type SomeType {\n field(arg: Int @example): String @example\n }\n ```\n\n+A directive may be defined as repeatable by including the \"repeatable\" keyword.\n+Repeatable directives are often useful when the same directive should be used\n+with different arguments at a single location, especially in cases where\n+additional information needs to be provided to a type or schema extension via\n+a directive:\n+\n+```graphql example\n+directive @delegateField(name: String!) repeatable on OBJECT | INTERFACE\n+\n+type Book @delegateField(name: \"pageCount\") @delegateField(name: \"author\") {\n+ id: ID!\n+}\n+\n+extend type Book @delegateField(name: \"index\")\n+```\n+\n While defining a directive, it must not reference itself directly or indirectly:\n\n ```graphql counter-example\n directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION\n ```\n\n+Note: The order in which directives appear may be significant, including\n+repeatable directives.\n+\n **Validation**\n\n 1. A directive definition must not contain the use of a directive which\n references itself directly.\n 2. A directive definition must not contain the use of a directive which\n references itself indirectly by referencing a Type or Directive which\n transitively includes a reference to this directive.\n 3. The directive must not have a name which begins with the characters\n@@ -1707,73 +1987,93 @@ directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION\n returns {true}.\n\n ### @skip\n\n ```graphql\n directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT\n ```\n\n-The `@skip` directive may be provided for fields, fragment spreads, and\n-inline fragments, and allows for conditional exclusion during execution as\n-described by the if argument.\n+The `@skip` *built-in directive* may be provided for fields, fragment spreads,\n+and inline fragments, and allows for conditional exclusion during execution as\n+described by the `if` argument.\n\n In this example `experimentalField` will only be queried if the variable\n `$someTest` has the value `false`.\n\n ```graphql example\n-query myQuery($someTest: Boolean) {\n+query myQuery($someTest: Boolean!) {\n experimentalField @skip(if: $someTest)\n }\n ```\n\n\n ### @include\n\n ```graphql\n directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT\n ```\n\n-The `@include` directive may be provided for fields, fragment spreads, and\n-inline fragments, and allows for conditional inclusion during execution as\n-described by the if argument.\n+The `@include` *built-in directive* may be provided for fields, fragment\n+spreads, and inline fragments, and allows for conditional inclusion during\n+execution as described by the `if` argument.\n\n In this example `experimentalField` will only be queried if the variable\n `$someTest` has the value `true`\n\n ```graphql example\n-query myQuery($someTest: Boolean) {\n+query myQuery($someTest: Boolean!) {\n experimentalField @include(if: $someTest)\n }\n ```\n\n Note: Neither `@skip` nor `@include` has precedence over the other. In the case\n-that both the `@skip` and `@include` directives are provided in on the same the\n+that both the `@skip` and `@include` directives are provided on the same\n field or fragment, it *must* be queried only if the `@skip` condition is false\n *and* the `@include` condition is true. Stated conversely, the field or fragment\n must *not* be queried if either the `@skip` condition is true *or* the\n `@include` condition is false.\n\n\n ### @deprecated\n\n ```graphql\n directive @deprecated(\n reason: String = \"No longer supported\"\n ) on FIELD_DEFINITION | ENUM_VALUE\n ```\n\n-The `@deprecated` directive is used within the type system definition language\n-to indicate deprecated portions of a GraphQL service's schema, such as\n+The `@deprecated` *built-in directive* is used within the type system definition\n+language to indicate deprecated portions of a GraphQL service's schema, such as\n deprecated fields on a type or deprecated enum values.\n\n Deprecations include a reason for why it is deprecated, which is formatted using\n-Markdown syntax (as specified by [CommonMark](http://commonmark.org/)).\n+Markdown syntax (as specified by [CommonMark](https://commonmark.org/)).\n\n In this example type definition, `oldField` is deprecated in favor of\n using `newField`.\n\n ```graphql example\n type ExampleType {\n newField: String\n oldField: String @deprecated(reason: \"Use `newField`.\")\n }\n ```\n+\n+\n+### @specifiedBy\n+\n+```graphql\n+directive @specifiedBy(url: String!) on SCALAR\n+```\n+\n+The `@specifiedBy` *built-in directive* is used within the type system\n+definition language to provide a *scalar specification URL* for specifying the\n+behavior of [custom scalar types](#sec-Scalars.Custom-Scalars). The URL should\n+point to a human-readable specification of the data format, serialization, and\n+coercion rules. It must not appear on built-in scalar types.\n+\n+In this example, a custom scalar type for `UUID` is defined with a URL pointing\n+to the relevant IETF specification.\n+\n+```graphql example\n+scalar UUID @specifiedBy(url: \"https://tools.ietf.org/html/rfc4122\")\n+```\n~~~\n
\n\n
\nspec/Section 4 -- Introspection.md\n\n~~~diff\n@@ -1,43 +1,43 @@\n # Introspection\n\n-A GraphQL server supports introspection over its schema. This schema is queried\n+A GraphQL service supports introspection over its schema. This schema is queried\n using GraphQL itself, creating a powerful platform for tool-building.\n\n-Take an example query for a trivial app. In this case there is a User type with\n+Take an example request for a trivial app. In this case there is a User type with\n three fields: id, name, and birthday.\n\n-For example, given a server with the following type definition:\n+For example, given a service with the following type definition:\n\n ```graphql example\n type User {\n id: String\n name: String\n birthday: Date\n }\n ```\n\n-The query\n+A request containing the operation:\n\n ```graphql example\n {\n __type(name: \"User\") {\n name\n fields {\n name\n type {\n name\n }\n }\n }\n }\n ```\n\n-would return\n+would produce the result:\n\n ```json example\n {\n \"__type\": {\n \"name\": \"User\",\n \"fields\": [\n {\n \"name\": \"id\",\n@@ -45,112 +45,127 @@ would return\n },\n {\n \"name\": \"name\",\n \"type\": { \"name\": \"String\" }\n },\n {\n \"name\": \"birthday\",\n \"type\": { \"name\": \"Date\" }\n- },\n+ }\n ]\n }\n }\n ```\n\n-## Reserved Names\n+**Reserved Names**\n\n Types and fields required by the GraphQL introspection system that are used in\n the same context as user-defined types and fields are prefixed with {\"__\"} two\n underscores. This in order to avoid naming collisions with user-defined GraphQL\n-types. Conversely, GraphQL type system authors must not define any types,\n-fields, arguments, or any other type system artifact with two leading\n-underscores.\n-\n-\n-## Documentation\n-\n-All types in the introspection system provide a `description` field of type\n-`String` to allow type designers to publish documentation in addition to\n-capabilities. A GraphQL server may return the `description` field using Markdown\n-syntax (as specified by [CommonMark](http://commonmark.org/)). Therefore it is\n-recommended that any tool that displays `description` use a CommonMark-compliant\n-Markdown renderer.\n-\n-\n-## Deprecation\n-\n-To support the management of backwards compatibility, GraphQL fields and enum\n-values can indicate whether or not they are deprecated (`isDeprecated: Boolean`)\n-and a description of why it is deprecated (`deprecationReason: String`).\n-\n-Tools built using GraphQL introspection should respect deprecation by\n-discouraging deprecated use through information hiding or developer-facing\n-warnings.\n+types.\n\n+Otherwise, any {Name} within a GraphQL type system must not start with\n+two underscores {\"__\"}.\n\n ## Type Name Introspection\n\n-GraphQL supports type name introspection at any point within a query by the\n-meta-field `__typename: String!` when querying against any Object, Interface,\n-or Union. It returns the name of the object type currently being queried.\n+GraphQL supports type name introspection within any selection set in an\n+operation, with the single exception of selections at the root of a subscription\n+operation. Type name introspection is accomplished via the meta-field\n+`__typename: String!` on any Object, Interface, or Union. It returns the name of\n+the concrete Object type at that point during execution.\n\n This is most often used when querying against Interface or Union types to\n-identify which actual type of the possible types has been returned.\n+identify which actual Object type of the possible types has been returned.\n\n-This field is implicit and does not appear in the fields list in any defined type.\n+As a meta-field, `__typename` is implicit and does not appear in the fields list\n+in any defined type.\n\n+Note: `__typename` may not be included as a root field in a subscription\n+operation.\n\n ## Schema Introspection\n\n The schema introspection system is accessible from the meta-fields `__schema`\n and `__type` which are accessible from the type of the root of a query\n operation.\n\n ```graphql\n __schema: __Schema!\n __type(name: String!): __Type\n ```\n\n-These fields are implicit and do not appear in the fields list in the root type\n-of the query operation.\n+Like all meta-fields, these are implicit and do not appear in the fields list in\n+the root type of the query operation.\n\n-The schema of the GraphQL schema introspection system:\n+**First Class Documentation**\n+\n+All types in the introspection system provide a `description` field of type\n+`String` to allow type designers to publish documentation in addition to\n+capabilities. A GraphQL service may return the `description` field using Markdown\n+syntax (as specified by [CommonMark](https://commonmark.org/)). Therefore it is\n+recommended that any tool that displays `description` use a CommonMark-compliant\n+Markdown renderer.\n+\n+**Deprecation**\n+\n+To support the management of backwards compatibility, GraphQL fields and enum\n+values can indicate whether or not they are deprecated (`isDeprecated: Boolean`)\n+and a description of why it is deprecated (`deprecationReason: String`).\n+\n+Tools built using GraphQL introspection should respect deprecation by\n+discouraging deprecated use through information hiding or developer-facing\n+warnings.\n+\n+**Schema Introspection Schema**\n+\n+The schema introspection system is itself represented as a GraphQL schema. Below\n+are the full set of type system definitions providing schema introspection,\n+which are fully defined in the sections below.\n\n ```graphql\n type __Schema {\n+ description: String\n types: [__Type!]!\n queryType: __Type!\n mutationType: __Type\n subscriptionType: __Type\n directives: [__Directive!]!\n }\n\n type __Type {\n kind: __TypeKind!\n name: String\n description: String\n-\n- # OBJECT and INTERFACE only\n+ # must be non-null for OBJECT and INTERFACE, otherwise null.\n fields(includeDeprecated: Boolean = false): [__Field!]\n-\n- # OBJECT only\n+ # must be non-null for OBJECT and INTERFACE, otherwise null.\n interfaces: [__Type!]\n-\n- # INTERFACE and UNION only\n+ # must be non-null for INTERFACE and UNION, otherwise null.\n possibleTypes: [__Type!]\n-\n- # ENUM only\n+ # must be non-null for ENUM, otherwise null.\n enumValues(includeDeprecated: Boolean = false): [__EnumValue!]\n-\n- # INPUT_OBJECT only\n+ # must be non-null for INPUT_OBJECT, otherwise null.\n inputFields: [__InputValue!]\n-\n- # NON_NULL and LIST only\n+ # must be non-null for NON_NULL and LIST, otherwise null.\n ofType: __Type\n+ # may be non-null for custom SCALAR, otherwise null.\n+ specifiedByURL: String\n+}\n+\n+enum __TypeKind {\n+ SCALAR\n+ OBJECT\n+ INTERFACE\n+ UNION\n+ ENUM\n+ INPUT_OBJECT\n+ LIST\n+ NON_NULL\n }\n\n type __Field {\n name: String!\n description: String\n args: [__InputValue!]!\n type: __Type!\n isDeprecated: Boolean!\n@@ -166,211 +181,245 @@ type __InputValue {\n\n type __EnumValue {\n name: String!\n description: String\n isDeprecated: Boolean!\n deprecationReason: String\n }\n\n-enum __TypeKind {\n- SCALAR\n- OBJECT\n- INTERFACE\n- UNION\n- ENUM\n- INPUT_OBJECT\n- LIST\n- NON_NULL\n-}\n-\n type __Directive {\n name: String!\n description: String\n locations: [__DirectiveLocation!]!\n args: [__InputValue!]!\n+ isRepeatable: Boolean!\n }\n\n enum __DirectiveLocation {\n QUERY\n MUTATION\n SUBSCRIPTION\n FIELD\n FRAGMENT_DEFINITION\n FRAGMENT_SPREAD\n INLINE_FRAGMENT\n+ VARIABLE_DEFINITION\n SCHEMA\n SCALAR\n OBJECT\n FIELD_DEFINITION\n ARGUMENT_DEFINITION\n INTERFACE\n UNION\n ENUM\n ENUM_VALUE\n INPUT_OBJECT\n INPUT_FIELD_DEFINITION\n }\n ```\n\n+### The __Schema Type\n\n-### The __Type Type\n+The `__Schema` type is returned from the `__schema` meta-field and provides\n+all information about the schema of a GraphQL service.\n\n-`__Type` is at the core of the type introspection system.\n-It represents scalars, interfaces, object types, unions, enums in the system.\n+Fields\\:\n\n-`__Type` also represents type modifiers, which are used to modify a type\n-that it refers to (`ofType: __Type`). This is how we represent lists,\n-non-nullable types, and the combinations thereof.\n+* `description` may return a String or {null}.\n+* `queryType` is the root type of a query operation.\n+* `mutationType` is the root type of a mutation operation, if supported.\n+ Otherwise {null}.\n+* `subscriptionType` is the root type of a subscription operation, if supported.\n+ Otherwise {null}.\n+* `types` must return the set of all named types contained within this schema.\n+ Any named type which can be found through a field of any introspection type\n+ must be included in this set.\n+* `directives` must return the set of all directives available within\n+ this schema including all built-in directives.\n\n\n-### Type Kinds\n+### The __Type Type\n+\n+`__Type` is at the core of the type introspection system, it represents all\n+types in the system: both named types (e.g. Scalars and Object types) and\n+type modifiers (e.g. List and Non-Null types).\n+\n+Type modifiers are used to modify the type presented in the field `ofType`.\n+This modified type may recursively be a modified type, representing lists,\n+non-nullables, and combinations thereof, ultimately modifying a named type.\n\n There are several different kinds of type. In each kind, different fields are\n-actually valid. These kinds are listed in the `__TypeKind` enumeration.\n+actually valid. All possible kinds are listed in the `__TypeKind` enum.\n+\n+Each sub-section below defines the expected fields of `__Type` given each\n+possible value of the `__TypeKind` enum:\n\n+* {\"SCALAR\"}\n+* {\"OBJECT\"}\n+* {\"INTERFACE\"}\n+* {\"UNION\"}\n+* {\"ENUM\"}\n+* {\"INPUT_OBJECT\"}\n+* {\"LIST\"}\n+* {\"NON_NULL\"}\n\n-#### Scalar\n+**Scalar**\n\n Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields.\n\n-A GraphQL type designer should describe the data format and scalar coercion\n-rules in the description field of any scalar.\n+Also represents [Custom scalars](#sec-Scalars.Custom-Scalars) which may provide\n+`specifiedByURL` as a *scalar specification URL*.\n\n-Fields\n+Fields\\:\n\n * `kind` must return `__TypeKind.SCALAR`.\n * `name` must return a String.\n * `description` may return a String or {null}.\n+* `specifiedByURL` may return a String (in the form of a URL) for custom\n+ scalars, otherwise must be {null}.\n * All other fields must return {null}.\n\n\n-#### Object\n+**Object**\n\n Object types represent concrete instantiations of sets of fields. The\n introspection types (e.g. `__Type`, `__Field`, etc) are examples of objects.\n\n-Fields\n+Fields\\:\n\n * `kind` must return `__TypeKind.OBJECT`.\n * `name` must return a String.\n * `description` may return a String or {null}.\n-* `fields`: The set of fields query-able on this type.\n+* `fields` must return the set of fields that can be selected for this type.\n * Accepts the argument `includeDeprecated` which defaults to {false}. If\n {true}, deprecated fields are also returned.\n-* `interfaces`: The set of interfaces that an object implements.\n+* `interfaces` must return the set of interfaces that an object implements\n+ (if none, `interfaces` must return the empty set).\n * All other fields must return {null}.\n\n\n-#### Union\n+**Union**\n\n Unions are an abstract type where no common fields are declared. The possible\n types of a union are explicitly listed out in `possibleTypes`. Types can be\n made parts of unions without modification of that type.\n\n-Fields\n+Fields\\:\n\n * `kind` must return `__TypeKind.UNION`.\n * `name` must return a String.\n * `description` may return a String or {null}.\n * `possibleTypes` returns the list of types that can be represented within this\n union. They must be object types.\n * All other fields must return {null}.\n\n\n-#### Interface\n+**Interface**\n\n Interfaces are an abstract type where there are common fields declared. Any type\n that implements an interface must define all the fields with names and types\n exactly matching. The implementations of this interface are explicitly listed\n out in `possibleTypes`.\n\n-Fields\n+Fields\\:\n\n * `kind` must return `__TypeKind.INTERFACE`.\n * `name` must return a String.\n * `description` may return a String or {null}.\n-* `fields`: The set of fields required by this interface.\n+* `fields` must return the set of fields required by this interface.\n * Accepts the argument `includeDeprecated` which defaults to {false}. If\n {true}, deprecated fields are also returned.\n+* `interfaces` must return the set of interfaces that an object implements\n+ (if none, `interfaces` must return the empty set).\n * `possibleTypes` returns the list of types that implement this interface.\n They must be object types.\n * All other fields must return {null}.\n\n\n-#### Enum\n+**Enum**\n\n Enums are special scalars that can only have a defined set of values.\n\n-Fields\n+Fields\\:\n\n * `kind` must return `__TypeKind.ENUM`.\n * `name` must return a String.\n * `description` may return a String or {null}.\n-* `enumValues`: The list of `EnumValue`. There must be at least one and they\n- must have unique names.\n+* `enumValues` must return the set of enum values as a list of `__EnumValue`.\n+ There must be at least one and they must have unique names.\n * Accepts the argument `includeDeprecated` which defaults to {false}. If\n {true}, deprecated enum values are also returned.\n * All other fields must return {null}.\n\n\n-#### Input Object\n+**Input Object**\n\n-Input objects are composite types used as inputs into queries defined as a list\n-of named input values.\n+Input objects are composite types defined as a list of named input values. They\n+are only used as inputs to arguments and variables and cannot be a field\n+return type.\n\n For example the input object `Point` could be defined as:\n\n ```graphql example\n input Point {\n x: Int\n y: Int\n }\n ```\n\n-Fields\n+Fields\\:\n\n * `kind` must return `__TypeKind.INPUT_OBJECT`.\n * `name` must return a String.\n * `description` may return a String or {null}.\n-* `inputFields`: a list of `InputValue`.\n+* `inputFields` must return the set of input fields as a list of `__InputValue`.\n * All other fields must return {null}.\n\n\n-#### List\n+**List**\n\n Lists represent sequences of values in GraphQL. A List type is a type modifier:\n it wraps another type instance in the `ofType` field, which defines the type of\n each item in the list.\n\n-Fields\n+The modified type in the `ofType` field may itself be a modified type, allowing\n+the representation of Lists of Lists, or Lists of Non-Nulls.\n+\n+Fields\\:\n\n * `kind` must return `__TypeKind.LIST`.\n-* `ofType`: Any type.\n+* `ofType` must return a type of any kind.\n * All other fields must return {null}.\n\n\n-#### Non-Null\n+**Non-Null**\n\n GraphQL types are nullable. The value {null} is a valid response for field type.\n\n-A Non-null type is a type modifier: it wraps another type instance in the\n+A Non-Null type is a type modifier: it wraps another type instance in the\n `ofType` field. Non-null types do not allow {null} as a response, and indicate\n required inputs for arguments and input object fields.\n\n+The modified type in the `ofType` field may itself be a modified List type,\n+allowing the representation of Non-Null of Lists. However it must not be a\n+modified Non-Null type to avoid a redundant Non-Null of Non-Null.\n+\n+Fields\\:\n+\n * `kind` must return `__TypeKind.NON_NULL`.\n-* `ofType`: Any type except Non-null.\n+* `ofType` must return a type of any kind except Non-Null.\n * All other fields must return {null}.\n\n\n ### The __Field Type\n\n The `__Field` type represents each field in an Object or Interface type.\n\n-Fields\n+Fields\\:\n\n * `name` must return a String\n * `description` may return a String or {null}\n * `args` returns a List of `__InputValue` representing the arguments this\n field accepts.\n * `type` must return a `__Type` that represents the type of value returned by\n this field.\n * `isDeprecated` returns {true} if this field should no longer be used,\n@@ -378,42 +427,69 @@ Fields\n * `deprecationReason` optionally provides a reason why this field is deprecated.\n\n\n ### The __InputValue Type\n\n The `__InputValue` type represents field and directive arguments as well as the\n `inputFields` of an input object.\n\n-Fields\n+Fields\\:\n\n * `name` must return a String\n * `description` may return a String or {null}\n * `type` must return a `__Type` that represents the type this input\n value expects.\n * `defaultValue` may return a String encoding (using the GraphQL language) of the\n default value used by this input value in the condition a value is not\n provided at runtime. If this input value has no default value, returns {null}.\n\n ### The __EnumValue Type\n\n The `__EnumValue` type represents one of possible values of an enum.\n\n-Fields\n+Fields\\:\n\n * `name` must return a String\n * `description` may return a String or {null}\n-* `isDeprecated` returns {true} if this field should no longer be used,\n+* `isDeprecated` returns {true} if this enum value should no longer be used,\n otherwise {false}.\n-* `deprecationReason` optionally provides a reason why this field is deprecated.\n+* `deprecationReason` optionally provides a reason why this enum value is deprecated.\n\n ### The __Directive Type\n\n-The `__Directive` type represents a Directive that a server supports.\n-\n-Fields\n+The `__Directive` type represents a directive that a service supports.\n+\n+This includes both any *built-in directive* and any *custom directive*.\n+\n+Individual directives may only be used in locations that are explicitly\n+supported. All possible locations are listed in the `__DirectiveLocation` enum:\n+\n+* {\"QUERY\"}\n+* {\"MUTATION\"}\n+* {\"SUBSCRIPTION\"}\n+* {\"FIELD\"}\n+* {\"FRAGMENT_DEFINITION\"}\n+* {\"FRAGMENT_SPREAD\"}\n+* {\"INLINE_FRAGMENT\"}\n+* {\"VARIABLE_DEFINITION\"}\n+* {\"SCHEMA\"}\n+* {\"SCALAR\"}\n+* {\"OBJECT\"}\n+* {\"FIELD_DEFINITION\"}\n+* {\"ARGUMENT_DEFINITION\"}\n+* {\"INTERFACE\"}\n+* {\"UNION\"}\n+* {\"ENUM\"}\n+* {\"ENUM_VALUE\"}\n+* {\"INPUT_OBJECT\"}\n+* {\"INPUT_FIELD_DEFINITION\"}\n+\n+Fields\\:\n\n * `name` must return a String\n * `description` may return a String or {null}\n * `locations` returns a List of `__DirectiveLocation` representing the valid\n locations this directive may be placed.\n * `args` returns a List of `__InputValue` representing the arguments this\n directive accepts.\n+* `isRepeatable` must return a Boolean that indicates if the directive may be\n+ used repeatedly at a single location.\n~~~\n
\n\n
\nspec/Section 5 -- Validation.md\n\n~~~diff\n@@ -16,17 +16,17 @@ validated before. For example: the request may be validated during development,\n provided it does not later change, or a service may validate a request once and\n memoize the result to avoid validating the same request again in the future.\n Any client-side or development-time tool should report validation errors and not\n allow the formulation or execution of requests known to be invalid at that given\n point in time.\n\n **Type system evolution**\n\n-As GraphQL type system schema evolve over time by adding new types and new\n+As GraphQL type system schema evolves over time by adding new types and new\n fields, it is possible that a request which was previously valid could later\n become invalid. Any change that can cause a previously valid request to become\n invalid is considered a *breaking change*. GraphQL services and schema\n maintainers are encouraged to avoid breaking changes, however in order to be\n more resilient to these breaking changes, sophisticated GraphQL systems may\n still allow for the execution of requests which *at some point* were known to\n be free of any validation errors, and have not changed since.\n\n@@ -35,24 +35,28 @@ be free of any validation errors, and have not changed since.\n For this section of this schema, we will assume the following type system\n in order to demonstrate examples:\n\n ```graphql example\n type Query {\n dog: Dog\n }\n\n-enum DogCommand { SIT, DOWN, HEEL }\n+enum DogCommand {\n+ SIT\n+ DOWN\n+ HEEL\n+}\n\n type Dog implements Pet {\n name: String!\n nickname: String\n barkVolume: Int\n doesKnowCommand(dogCommand: DogCommand!): Boolean!\n- isHousetrained(atOtherHomes: Boolean): Boolean!\n+ isHouseTrained(atOtherHomes: Boolean): Boolean!\n owner: Human\n }\n\n interface Sentient {\n name: String!\n }\n\n interface Pet {\n@@ -61,19 +65,22 @@ interface Pet {\n\n type Alien implements Sentient {\n name: String!\n homePlanet: String\n }\n\n type Human implements Sentient {\n name: String!\n+ pets: [Pet!]\n }\n\n-enum CatCommand { JUMP }\n+enum CatCommand {\n+ JUMP\n+}\n\n type Cat implements Pet {\n name: String!\n nickname: String\n doesKnowCommand(catCommand: CatCommand!): Boolean!\n meowVolume: Int\n }\n\n@@ -84,31 +91,31 @@ union HumanOrAlien = Human | Alien\n\n\n ## Documents\n\n ### Executable Definitions\n\n **Formal Specification**\n\n- * For each definition {definition} in the document.\n- * {definition} must be {OperationDefinition} or {FragmentDefinition} (it must\n- not be {TypeSystemDefinition}).\n+* For each definition {definition} in the document.\n+* {definition} must be {ExecutableDefinition} (it must not be\n+ {TypeSystemDefinitionOrExtension}).\n\n **Explanatory Text**\n\n GraphQL execution will only consider the executable definitions Operation and\n Fragment. Type system definitions and extensions are not executable, and are not\n considered during execution.\n\n-To avoid ambiguity, a document containing {TypeSystemDefinition} is invalid\n-for execution.\n+To avoid ambiguity, a document containing {TypeSystemDefinitionOrExtension} is\n+invalid for execution.\n\n GraphQL documents not intended to be directly executed may include\n-{TypeSystemDefinition}.\n+{TypeSystemDefinitionOrExtension}.\n\n For example, the following document is invalid for execution since the original\n executing schema may not know about the provided type extension:\n\n ```graphql counter-example\n query getDogName {\n dog {\n name\n@@ -124,21 +131,21 @@ extend type Dog {\n ## Operations\n\n ### Named Operation Definitions\n\n #### Operation Name Uniqueness\n\n **Formal Specification**\n\n- * For each operation definition {operation} in the document.\n- * Let {operationName} be the name of {operation}.\n- * If {operationName} exists\n- * Let {operations} be all operation definitions in the document named {operationName}.\n- * {operations} must be a set of one.\n+* For each operation definition {operation} in the document.\n+* Let {operationName} be the name of {operation}.\n+* If {operationName} exists\n+ * Let {operations} be all operation definitions in the document named {operationName}.\n+ * {operations} must be a set of one.\n\n **Explanatory Text**\n\n Each named operation definition must be unique within a document when referred\n to by its name.\n\n For example the following document is valid:\n\n@@ -193,20 +200,20 @@ mutation dogOperation {\n ```\n\n ### Anonymous Operation Definitions\n\n #### Lone Anonymous Operation\n\n **Formal Specification**\n\n- * Let {operations} be all operation definitions in the document.\n- * Let {anonymous} be all anonymous operation definitions in the document.\n- * If {operations} is a set of more than 1:\n- * {anonymous} must be empty.\n+* Let {operations} be all operation definitions in the document.\n+* Let {anonymous} be all anonymous operation definitions in the document.\n+* If {operations} is a set of more than 1:\n+ * {anonymous} must be empty.\n\n **Explanatory Text**\n\n GraphQL allows a short-hand form for defining query operations when only that\n one operation exists in the document.\n\n For example the following document is valid:\n\n@@ -237,23 +244,24 @@ query getName {\n ```\n\n ### Subscription Operation Definitions\n\n #### Single root field\n\n **Formal Specification**\n\n- * For each subscription operation definition {subscription} in the document\n- * Let {subscriptionType} be the root Subscription type in {schema}.\n- * Let {selectionSet} be the top level selection set on {subscription}.\n- * Let {variableValues} be the empty set.\n- * Let {groupedFieldSet} be the result of\n- {CollectFields(subscriptionType, selectionSet, variableValues)}.\n- * {groupedFieldSet} must have exactly one entry.\n+* For each subscription operation definition {subscription} in the document\n+* Let {subscriptionType} be the root Subscription type in {schema}.\n+* Let {selectionSet} be the top level selection set on {subscription}.\n+* Let {variableValues} be the empty set.\n+* Let {groupedFieldSet} be the result of\n+ {CollectFields(subscriptionType, selectionSet, variableValues)}.\n+* {groupedFieldSet} must have exactly one entry, which must not be an\n+ introspection field.\n\n **Explanatory Text**\n\n Subscription operations must have exactly one root field.\n\n Valid examples:\n\n ```graphql example\n@@ -299,42 +307,41 @@ fragment multipleSubscriptions on Subscription {\n newMessage {\n body\n sender\n }\n disallowedSecondRootField\n }\n ```\n\n-Introspection fields are counted. The following example is also invalid:\n+The root field of a subscription operation must not be an introspection field.\n+The following example is also invalid:\n\n ```graphql counter-example\n subscription sub {\n- newMessage {\n- body\n- sender\n- }\n __typename\n }\n ```\n\n Note: While each subscription must have exactly one root field, a document may\n contain any number of operations, each of which may contain different root\n fields. When executed, a document containing multiple subscription operations\n must provide the operation name as described in {GetOperation()}.\n\n ## Fields\n\n-### Field Selections on Objects, Interfaces, and Unions Types\n+### Field Selections\n+\n+Field selections must exist on Object, Interface, and Union types.\n\n **Formal Specification**\n\n- * For each {selection} in the document.\n- * Let {fieldName} be the target field of {selection}\n- * {fieldName} must be defined on type in scope\n+* For each {selection} in the document.\n+* Let {fieldName} be the target field of {selection}\n+* {fieldName} must be defined on type in scope\n\n **Explanatory Text**\n\n The target field of a field selection must be defined on the scoped type of the\n selection set. There are no limitations on alias names.\n\n For example the following fragment would not pass validation:\n\n@@ -396,48 +403,50 @@ fragment directFieldSelectionOnUnion on CatOrDog {\n }\n ```\n\n\n ### Field Selection Merging\n\n **Formal Specification**\n\n- * Let {set} be any selection set defined in the GraphQL document.\n- * {FieldsInSetCanMerge(set)} must be true.\n+* Let {set} be any selection set defined in the GraphQL document.\n+* {FieldsInSetCanMerge(set)} must be true.\n+\n+FieldsInSetCanMerge(set):\n\n-FieldsInSetCanMerge(set) :\n * Let {fieldsForName} be the set of selections with a given response name in\n {set} including visiting fragments and inline fragments.\n * Given each pair of members {fieldA} and {fieldB} in {fieldsForName}:\n * {SameResponseShape(fieldA, fieldB)} must be true.\n * If the parent types of {fieldA} and {fieldB} are equal or if either is not\n an Object Type:\n * {fieldA} and {fieldB} must have identical field names.\n * {fieldA} and {fieldB} must have identical sets of arguments.\n * Let {mergedSet} be the result of adding the selection set of {fieldA}\n and the selection set of {fieldB}.\n * {FieldsInSetCanMerge(mergedSet)} must be true.\n\n-SameResponseShape(fieldA, fieldB) :\n+SameResponseShape(fieldA, fieldB):\n+\n * Let {typeA} be the return type of {fieldA}.\n * Let {typeB} be the return type of {fieldB}.\n * If {typeA} or {typeB} is Non-Null.\n * If {typeA} or {typeB} is nullable, return false.\n * Let {typeA} be the nullable type of {typeA}\n * Let {typeB} be the nullable type of {typeB}\n * If {typeA} or {typeB} is List.\n * If {typeA} or {typeB} is not List, return false.\n * Let {typeA} be the item type of {typeA}\n * Let {typeB} be the item type of {typeB}\n * Repeat from step 3.\n * If {typeA} or {typeB} is Scalar or Enum.\n * If {typeA} and {typeB} are the same type return true, otherwise return\n false.\n- * If {typeA} or {typeB} is not a composite type, return false.\n+ * Assert: {typeA} and {typeB} are both composite types.\n * Let {mergedSet} be the result of adding the selection set of {fieldA} and\n the selection set of {fieldB}.\n * Let {fieldsForName} be the set of selections with a given response name in\n {mergedSet} including visiting fragments and inline fragments.\n * Given each pair of members {subfieldA} and {subfieldB} in {fieldsForName}:\n * If {SameResponseShape(subfieldA, subfieldB)} is false, return false.\n * Return true.\n\n@@ -556,27 +565,27 @@ fragment conflictingDifferingResponses on Pet {\n }\n ```\n\n\n ### Leaf Field Selections\n\n **Formal Specification**\n\n- * For each {selection} in the document\n- * Let {selectionType} be the result type of {selection}\n- * If {selectionType} is a scalar or enum:\n- * The subselection set of that selection must be empty\n- * If {selectionType} is an interface, union, or object\n- * The subselection set of that selection must NOT BE empty\n+* For each {selection} in the document\n+* Let {selectionType} be the result type of {selection}\n+* If {selectionType} is a scalar or enum:\n+ * The subselection set of that selection must be empty\n+* If {selectionType} is an interface, union, or object\n+ * The subselection set of that selection must NOT BE empty\n\n **Explanatory Text**\n\n Field selections on scalars or enums are never allowed, because they\n-are the leaf nodes of any GraphQL query.\n+are the leaf nodes of any GraphQL operation.\n\n The following is valid.\n\n ```graphql example\n fragment scalarSelection on Dog {\n barkVolume\n }\n ```\n@@ -586,21 +595,22 @@ The following is invalid.\n ```graphql counter-example\n fragment scalarSelectionsNotAllowedOnInt on Dog {\n barkVolume {\n sinceWhen\n }\n }\n ```\n\n-Conversely the leaf field selections of GraphQL queries\n+Conversely the leaf field selections of GraphQL operations\n must be of type scalar or enum. Leaf selections on objects, interfaces,\n and unions without subfields are disallowed.\n\n-Let's assume the following additions to the query root type of the schema:\n+Let's assume the following additions to the query root operation type of\n+the schema:\n\n ```graphql example\n extend type Query {\n human: Human\n pet: Pet\n catOrDog: CatOrDog\n }\n ```\n@@ -627,98 +637,98 @@ query directQueryOnUnionWithoutSubFields {\n Arguments are provided to both fields and directives. The following validation\n rules apply in both cases.\n\n\n ### Argument Names\n\n **Formal Specification**\n\n- * For each {argument} in the document\n- * Let {argumentName} be the Name of {argument}.\n- * Let {argumentDefinition} be the argument definition provided by the parent field or definition named {argumentName}.\n- * {argumentDefinition} must exist.\n+* For each {argument} in the document\n+* Let {argumentName} be the Name of {argument}.\n+* Let {argumentDefinition} be the argument definition provided by the parent field or definition named {argumentName}.\n+* {argumentDefinition} must exist.\n\n **Explanatory Text**\n\n Every argument provided to a field or directive must be defined in the set of\n possible arguments of that field or directive.\n\n For example the following are valid:\n\n ```graphql example\n fragment argOnRequiredArg on Dog {\n doesKnowCommand(dogCommand: SIT)\n }\n\n fragment argOnOptional on Dog {\n- isHousetrained(atOtherHomes: true) @include(if: true)\n+ isHouseTrained(atOtherHomes: true) @include(if: true)\n }\n ```\n\n the following is invalid since `command` is not defined on `DogCommand`.\n\n ```graphql counter-example\n fragment invalidArgName on Dog {\n doesKnowCommand(command: CLEAN_UP_HOUSE)\n }\n ```\n\n and this is also invalid as `unless` is not defined on `@include`.\n\n ```graphql counter-example\n fragment invalidArgName on Dog {\n- isHousetrained(atOtherHomes: true) @include(unless: false)\n+ isHouseTrained(atOtherHomes: true) @include(unless: false)\n }\n ```\n\n In order to explore more complicated argument examples, let's add the following\n to our type system:\n\n ```graphql example\n type Arguments {\n- multipleReqs(x: Int!, y: Int!): Int!\n+ multipleRequirements(x: Int!, y: Int!): Int!\n booleanArgField(booleanArg: Boolean): Boolean\n floatArgField(floatArg: Float): Float\n intArgField(intArg: Int): Int\n nonNullBooleanArgField(nonNullBooleanArg: Boolean!): Boolean!\n booleanListArgField(booleanListArg: [Boolean]!): [Boolean]\n optionalNonNullBooleanArgField(optionalBooleanArg: Boolean! = false): Boolean!\n }\n\n extend type Query {\n arguments: Arguments\n }\n ```\n\n-Order does not matter in arguments. Therefore both the following example are valid.\n+Order does not matter in arguments. Therefore both the following examples are valid.\n\n ```graphql example\n fragment multipleArgs on Arguments {\n- multipleReqs(x: 1, y: 2)\n+ multipleRequirements(x: 1, y: 2)\n }\n\n fragment multipleArgsReverseOrder on Arguments {\n- multipleReqs(y: 1, x: 2)\n+ multipleRequirements(y: 2, x: 1)\n }\n ```\n\n\n ### Argument Uniqueness\n\n Fields and directives treat arguments as a mapping of argument name to value.\n More than one argument with the same name in an argument set is ambiguous\n and invalid.\n\n **Formal Specification**\n\n- * For each {argument} in the Document.\n- * Let {argumentName} be the Name of {argument}.\n- * Let {arguments} be all Arguments named {argumentName} in the Argument Set which contains {argument}.\n- * {arguments} must be the set containing only {argument}.\n+* For each {argument} in the Document.\n+* Let {argumentName} be the Name of {argument}.\n+* Let {arguments} be all Arguments named {argumentName} in the Argument Set which contains {argument}.\n+* {arguments} must be the set containing only {argument}.\n\n\n #### Required Arguments\n\n * For each Field or Directive in the document.\n * Let {arguments} be the arguments provided by the Field or Directive.\n * Let {argumentDefinitions} be the set of argument definitions of that Field or Directive.\n * For each {argumentDefinition} in {argumentDefinitions}:\n@@ -745,17 +755,17 @@ fragment goodBooleanArg on Arguments {\n\n fragment goodNonNullArg on Arguments {\n nonNullBooleanArgField(nonNullBooleanArg: true)\n }\n ```\n\n The argument can be omitted from a field with a nullable argument.\n\n-Therefore the following query is valid:\n+Therefore the following fragment is valid:\n\n ```graphql example\n fragment goodBooleanArgDefault on Arguments {\n booleanArgField\n }\n ```\n\n but this is not valid on a required argument.\n@@ -778,20 +788,20 @@ fragment missingRequiredArg on Arguments {\n ## Fragments\n\n ### Fragment Declarations\n\n #### Fragment Name Uniqueness\n\n **Formal Specification**\n\n- * For each fragment definition {fragment} in the document\n- * Let {fragmentName} be the name of {fragment}.\n- * Let {fragments} be all fragment definitions in the document named {fragmentName}.\n- * {fragments} must be a set of one.\n+* For each fragment definition {fragment} in the document\n+* Let {fragmentName} be the name of {fragment}.\n+* Let {fragments} be all fragment definitions in the document named {fragmentName}.\n+* {fragments} must be a set of one.\n\n **Explanatory Text**\n\n Fragment definitions are referenced in fragment spreads by name. To avoid\n ambiguity, each fragment's name must be unique within a document.\n\n Inline fragments are not considered fragment definitions, and are unaffected by this\n validation rule.\n@@ -837,25 +847,25 @@ fragment fragmentOne on Dog {\n }\n ```\n\n\n #### Fragment Spread Type Existence\n\n **Formal Specification**\n\n- * For each named spread {namedSpread} in the document\n- * Let {fragment} be the target of {namedSpread}\n- * The target type of {fragment} must be defined in the schema\n+* For each named spread {namedSpread} in the document\n+* Let {fragment} be the target of {namedSpread}\n+* The target type of {fragment} must be defined in the schema\n\n **Explanatory Text**\n\n Fragments must be specified on types that exist in the schema. This\n applies for both named and inline fragments. If they are\n-not defined in the schema, the query does not validate.\n+not defined in the schema, the fragment is invalid.\n\n For example the following fragments are valid:\n\n ```graphql example\n fragment correctType on Dog {\n name\n }\n\n@@ -886,19 +896,19 @@ fragment inlineNotExistingType on Dog {\n }\n ```\n\n\n #### Fragments On Composite Types\n\n **Formal Specification**\n\n- * For each {fragment} defined in the document.\n- * The target type of fragment must have kind {UNION}, {INTERFACE}, or\n- {OBJECT}.\n+* For each {fragment} defined in the document.\n+* The target type of fragment must have kind {UNION}, {INTERFACE}, or\n+ {OBJECT}.\n\n **Explanatory Text**\n\n Fragments can only be declared on unions, interfaces, and objects. They are\n invalid on scalars. They can only be applied on non-leaf fields. This rule\n applies to both inline and named fragments.\n\n The following fragment declarations are valid:\n@@ -933,53 +943,53 @@ fragment inlineFragOnScalar on Dog {\n }\n ```\n\n\n #### Fragments Must Be Used\n\n **Formal Specification**\n\n- * For each {fragment} defined in the document.\n- * {fragment} must be the target of at least one spread in the document\n+* For each {fragment} defined in the document.\n+* {fragment} must be the target of at least one spread in the document\n\n **Explanatory Text**\n\n Defined fragments must be used within a document.\n\n For example the following is an invalid document:\n\n-```graphql counter-example\n+```raw graphql counter-example\n fragment nameFragment on Dog { # unused\n name\n }\n\n {\n dog {\n name\n }\n }\n ```\n\n\n ### Fragment Spreads\n\n Field selection is also determined by spreading fragments into one\n-another. The selection set of the target fragment is unioned with\n+another. The selection set of the target fragment is combined into\n the selection set at the level at which the target fragment is\n referenced.\n\n\n #### Fragment spread target defined\n\n **Formal Specification**\n\n- * For every {namedSpread} in the document.\n- * Let {fragment} be the target of {namedSpread}\n- * {fragment} must be defined in the document\n+* For every {namedSpread} in the document.\n+* Let {fragment} be the target of {namedSpread}\n+* {fragment} must be defined in the document\n\n **Explanatory Text**\n\n Named fragment spreads must refer to fragments defined within the\n document. It is a validation error if the target of a spread is\n not defined.\n\n ```graphql counter-example\n@@ -990,27 +1000,28 @@ not defined.\n }\n ```\n\n\n #### Fragment spreads must not form cycles\n\n **Formal Specification**\n\n- * For each {fragmentDefinition} in the document\n- * Let {visited} be the empty set.\n- * {DetectCycles(fragmentDefinition, visited)}\n+* For each {fragmentDefinition} in the document\n+* Let {visited} be the empty set.\n+* {DetectFragmentCycles(fragmentDefinition, visited)}\n+\n+DetectFragmentCycles(fragmentDefinition, visited):\n\n-{DetectCycles(fragmentDefinition, visited)} :\n * Let {spreads} be all fragment spread descendants of {fragmentDefinition}\n * For each {spread} in {spreads}\n * {visited} must not contain {spread}\n * Let {nextVisited} be the set including {spread} and members of {visited}\n * Let {nextFragmentDefinition} be the target of {spread}\n- * {DetectCycles(nextFragmentDefinition, nextVisited)}\n+ * {DetectFragmentCycles(nextFragmentDefinition, nextVisited)}\n\n **Explanatory Text**\n\n The graph of fragment spreads must not form any cycles including spreading itself.\n Otherwise an operation could infinitely spread or infinitely execute on cycles\n in the underlying data.\n\n This invalidates fragments that would result in an infinite spread:\n@@ -1062,38 +1073,39 @@ executed against cyclic data:\n\n fragment dogFragment on Dog {\n name\n owner {\n ...ownerFragment\n }\n }\n\n-fragment ownerFragment on Dog {\n+fragment ownerFragment on Human {\n name\n pets {\n ...dogFragment\n }\n }\n ```\n\n\n #### Fragment spread is possible\n\n **Formal Specification**\n\n- * For each {spread} (named or inline) defined in the document.\n- * Let {fragment} be the target of {spread}\n- * Let {fragmentType} be the type condition of {fragment}\n- * Let {parentType} be the type of the selection set containing {spread}\n- * Let {applicableTypes} be the intersection of\n- {GetPossibleTypes(fragmentType)} and {GetPossibleTypes(parentType)}\n- * {applicableTypes} must not be empty.\n+* For each {spread} (named or inline) defined in the document.\n+* Let {fragment} be the target of {spread}\n+* Let {fragmentType} be the type condition of {fragment}\n+* Let {parentType} be the type of the selection set containing {spread}\n+* Let {applicableTypes} be the intersection of\n+ {GetPossibleTypes(fragmentType)} and {GetPossibleTypes(parentType)}\n+* {applicableTypes} must not be empty.\n+\n+GetPossibleTypes(type):\n\n-GetPossibleTypes(type) :\n * If {type} is an object type, return a set containing {type}\n * If {type} is an interface type, return the set of types implementing {type}\n * If {type} is a union type, return the set of possible types of {type}\n\n **Explanatory Text**\n\n Fragments are declared on a type and will only apply when the\n runtime object type matches the type condition. They also are\n@@ -1233,17 +1245,17 @@ fragment unionWithInterface on Pet {\n\n fragment dogOrHumanFragment on DogOrHuman {\n ... on Dog {\n barkVolume\n }\n }\n ```\n\n-is consider valid because {Dog} implements interface {Pet} and is a\n+is considered valid because {Dog} implements interface {Pet} and is a\n member of {DogOrHuman}.\n\n However\n\n ```graphql counter-example\n fragment nonIntersectingInterfaces on Pet {\n ...sentientFragment\n }\n@@ -1252,33 +1264,61 @@ fragment sentientFragment on Sentient {\n name\n }\n ```\n\n is not valid because there exists no type that implements both {Pet}\n and {Sentient}.\n\n\n+**Interface Spreads in implemented Interface Scope**\n+\n+Additionally, an interface type fragment can always be spread into an\n+interface scope which it implements.\n+\n+In the example below, the `...resourceFragment` fragments spreads is valid,\n+since `Resource` implements `Node`.\n+\n+```raw graphql example\n+interface Node {\n+ id: ID!\n+}\n+\n+interface Resource implements Node {\n+ id: ID!\n+ url: String\n+}\n+\n+fragment interfaceWithInterface on Node {\n+ ...resourceFragment\n+}\n+\n+fragment resourceFragment on Resource {\n+ url\n+}\n+```\n+\n+\n ## Values\n\n\n ### Values of Correct Type\n\n-**Format Specification**\n+**Formal Specification**\n\n- * For each input Value {value} in the document.\n- * Let {type} be the type expected in the position {value} is found.\n- * {value} must be coercible to {type}.\n+* For each input Value {value} in the document.\n+ * Let {type} be the type expected in the position {value} is found.\n+ * {value} must be coercible to {type}.\n\n **Explanatory Text**\n\n Literal values must be compatible with the type expected in the position they\n are found as per the coercion rules defined in the Type System chapter.\n\n-The type expected in a position include the type defined by the argument a value\n+The type expected in a position includes the type defined by the argument a value\n is provided for, the type defined by an input object field a value is provided\n for, and the type of a variable definition a default value is provided for.\n\n The following examples are valid use of value literals:\n\n ```graphql example\n fragment goodBooleanArg on Arguments {\n booleanArgField(booleanArg: true)\n@@ -1307,21 +1347,21 @@ query badComplexValue {\n }\n ```\n\n\n ### Input Object Field Names\n\n **Formal Specification**\n\n- * For each Input Object Field {inputField} in the document\n- * Let {inputFieldName} be the Name of {inputField}.\n- * Let {inputFieldDefinition} be the input field definition provided by the\n- parent input object type named {inputFieldName}.\n- * {inputFieldDefinition} must exist.\n+* For each Input Object Field {inputField} in the document\n+* Let {inputFieldName} be the Name of {inputField}.\n+* Let {inputFieldDefinition} be the input field definition provided by the\n+ parent input object type named {inputFieldName}.\n+* {inputFieldDefinition} must exist.\n\n **Explanatory Text**\n\n Every input field provided in an input object value must be defined in the set\n of possible fields of that input object's expected type.\n\n For example the following example input object is valid:\n\n@@ -1340,138 +1380,140 @@ which is not defined on the expected type:\n }\n ```\n\n\n ### Input Object Field Uniqueness\n\n **Formal Specification**\n\n- * For each input object value {inputObject} in the document.\n- * For every {inputField} in {inputObject}\n- * Let {name} be the Name of {inputField}.\n- * Let {fields} be all Input Object Fields named {name} in {inputObject}.\n- * {fields} must be the set containing only {inputField}.\n+* For each input object value {inputObject} in the document.\n+* For every {inputField} in {inputObject}\n+ * Let {name} be the Name of {inputField}.\n+ * Let {fields} be all Input Object Fields named {name} in {inputObject}.\n+ * {fields} must be the set containing only {inputField}.\n\n **Explanatory Text**\n\n Input objects must not contain more than one field of the same name, otherwise\n an ambiguity would exist which includes an ignored portion of syntax.\n\n-For example the following query will not pass validation.\n+For example the following document will not pass validation.\n\n ```graphql counter-example\n {\n field(arg: { field: true, field: false })\n }\n ```\n\n\n ### Input Object Required Fields\n\n **Formal Specification**\n\n- * For each Input Object in the document.\n- * Let {fields} be the fields provided by that Input Object.\n- * Let {fieldDefinitions} be the set of input field definitions of that Input Object.\n- * For each {fieldDefinition} in {fieldDefinitions}:\n- * Let {type} be the expected type of {fieldDefinition}.\n- * Let {defaultValue} be the default value of {fieldDefinition}.\n- * If {type} is Non-Null and {defaultValue} does not exist:\n- * Let {fieldName} be the name of {fieldDefinition}.\n- * Let {field} be the input field in {fields} named {fieldName}\n- * {field} must exist.\n- * Let {value} be the value of {field}.\n- * {value} must not be the {null} literal.\n+* For each Input Object in the document.\n+ * Let {fields} be the fields provided by that Input Object.\n+ * Let {fieldDefinitions} be the set of input field definitions of that Input Object.\n+* For each {fieldDefinition} in {fieldDefinitions}:\n+ * Let {type} be the expected type of {fieldDefinition}.\n+ * Let {defaultValue} be the default value of {fieldDefinition}.\n+ * If {type} is Non-Null and {defaultValue} does not exist:\n+ * Let {fieldName} be the name of {fieldDefinition}.\n+ * Let {field} be the input field in {fields} named {fieldName}\n+ * {field} must exist.\n+ * Let {value} be the value of {field}.\n+ * {value} must not be the {null} literal.\n\n **Explanatory Text**\n\n Input object fields may be required. Much like a field may have required\n arguments, an input object may have required fields. An input field is required\n if it has a non-null type and does not have a default value. Otherwise, the\n input object field is optional.\n\n\n ## Directives\n\n\n ### Directives Are Defined\n\n **Formal Specification**\n\n- * For every {directive} in a document.\n- * Let {directiveName} be the name of {directive}.\n- * Let {directiveDefinition} be the directive named {directiveName}.\n- * {directiveDefinition} must exist.\n+* For every {directive} in a document.\n+* Let {directiveName} be the name of {directive}.\n+* Let {directiveDefinition} be the directive named {directiveName}.\n+* {directiveDefinition} must exist.\n\n **Explanatory Text**\n\n-GraphQL servers define what directives they support. For each\n-usage of a directive, the directive must be available on that server.\n+GraphQL services define what directives they support. For each\n+usage of a directive, the directive must be available on that service.\n\n\n ### Directives Are In Valid Locations\n\n **Formal Specification**\n\n- * For every {directive} in a document.\n- * Let {directiveName} be the name of {directive}.\n- * Let {directiveDefinition} be the directive named {directiveName}.\n- * Let {locations} be the valid locations for {directiveDefinition}.\n- * Let {adjacent} be the AST node the directive affects.\n- * {adjacent} must be represented by an item within {locations}.\n+* For every {directive} in a document.\n+* Let {directiveName} be the name of {directive}.\n+* Let {directiveDefinition} be the directive named {directiveName}.\n+* Let {locations} be the valid locations for {directiveDefinition}.\n+* Let {adjacent} be the AST node the directive affects.\n+* {adjacent} must be represented by an item within {locations}.\n\n **Explanatory Text**\n\n-GraphQL servers define what directives they support and where they support them.\n+GraphQL services define what directives they support and where they support them.\n For each usage of a directive, the directive must be used in a location that the\n-server has declared support for.\n+service has declared support for.\n\n-For example the following query will not pass validation because `@skip` does\n+For example the following document will not pass validation because `@skip` does\n not provide `QUERY` as a valid location.\n\n ```graphql counter-example\n query @skip(if: $foo) {\n field\n }\n ```\n\n\n ### Directives Are Unique Per Location\n\n **Formal Specification**\n\n- * For every {location} in the document for which Directives can apply:\n- * Let {directives} be the set of Directives which apply to {location}.\n- * For each {directive} in {directives}:\n- * Let {directiveName} be the name of {directive}.\n- * Let {namedDirectives} be the set of all Directives named {directiveName}\n- in {directives}.\n- * {namedDirectives} must be a set of one.\n+* For every {location} in the document for which Directives can apply:\n+ * Let {directives} be the set of Directives which apply to {location} and\n+ are not repeatable.\n+ * For each {directive} in {directives}:\n+ * Let {directiveName} be the name of {directive}.\n+ * Let {namedDirectives} be the set of all Directives named {directiveName}\n+ in {directives}.\n+ * {namedDirectives} must be a set of one.\n\n **Explanatory Text**\n\n Directives are used to describe some metadata or behavioral change on the\n definition they apply to. When more than one directive of the same name is used,\n the expected metadata or behavior becomes ambiguous, therefore only one of each\n directive is allowed per location.\n\n-For example, the following query will not pass validation because `@skip` has\n+For example, the following document will not pass validation because `@skip` has\n been used twice for the same field:\n\n-```graphql counter-example\n+```raw graphql counter-example\n query ($foo: Boolean = true, $bar: Boolean = false) {\n field @skip(if: $foo) @skip(if: $bar)\n }\n ```\n\n However the following example is valid because `@skip` has been used only once\n-per location, despite being used twice in the query and on the same named field:\n+per location, despite being used twice in the operation and on the same\n+named field:\n\n-```graphql example\n+```raw graphql example\n query ($foo: Boolean = true, $bar: Boolean = false) {\n field @skip(if: $foo) {\n subfieldA\n }\n field @skip(if: $bar) {\n subfieldB\n }\n }\n@@ -1479,33 +1521,33 @@ query ($foo: Boolean = true, $bar: Boolean = false) {\n\n\n ## Variables\n\n ### Variable Uniqueness\n\n **Formal Specification**\n\n- * For every {operation} in the document\n- * For every {variable} defined on {operation}\n- * Let {variableName} be the name of {variable}\n- * Let {variables} be the set of all variables named {variableName} on\n- {operation}\n- * {variables} must be a set of one\n+* For every {operation} in the document\n+ * For every {variable} defined on {operation}\n+ * Let {variableName} be the name of {variable}\n+ * Let {variables} be the set of all variables named {variableName} on\n+ {operation}\n+ * {variables} must be a set of one\n\n **Explanatory Text**\n\n If any operation defines more than one variable with the same name, it is\n ambiguous and invalid. It is invalid even if the type of the duplicate variable\n is the same.\n\n ```graphql counter-example\n query houseTrainedQuery($atOtherHomes: Boolean, $atOtherHomes: Boolean) {\n dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n }\n ```\n\n\n It is valid for multiple operations to define a variable with the same name. If\n two operations reference the same fragment, it might actually be necessary:\n\n@@ -1513,70 +1555,73 @@ two operations reference the same fragment, it might actually be necessary:\n query A($atOtherHomes: Boolean) {\n ...HouseTrainedFragment\n }\n\n query B($atOtherHomes: Boolean) {\n ...HouseTrainedFragment\n }\n\n-fragment HouseTrainedFragment {\n+fragment HouseTrainedFragment on Query {\n dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n }\n ```\n\n\n ### Variables Are Input Types\n\n **Formal Specification**\n\n- * For every {operation} in a {document}\n- * For every {variable} on each {operation}\n- * Let {variableType} be the type of {variable}\n- * {IsInputType(variableType)} must be {true}\n+* For every {operation} in a {document}\n+* For every {variable} on each {operation}\n+ * Let {variableType} be the type of {variable}\n+ * {IsInputType(variableType)} must be {true}\n\n **Explanatory Text**\n\n Variables can only be input types. Objects, unions, and interfaces cannot be\n used as inputs.\n\n-For these examples, consider the following typesystem additions:\n+For these examples, consider the following type system additions:\n\n ```graphql example\n-input ComplexInput { name: String, owner: String }\n+input ComplexInput {\n+ name: String\n+ owner: String\n+}\n\n extend type Query {\n findDog(complex: ComplexInput): Dog\n booleanList(booleanListArg: [Boolean!]): Boolean\n }\n ```\n\n-The following queries are valid:\n+The following operations are valid:\n\n ```graphql example\n query takesBoolean($atOtherHomes: Boolean) {\n dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n }\n\n query takesComplexInput($complexInput: ComplexInput) {\n findDog(complex: $complexInput) {\n name\n }\n }\n\n query TakesListOfBooleanBang($booleans: [Boolean!]) {\n booleanList(booleanListArg: $booleans)\n }\n ```\n\n-The following queries are invalid:\n+The following operations are invalid:\n\n ```graphql counter-example\n query takesCat($cat: Cat) {\n # ...\n }\n\n query takesDogBang($dog: Dog!) {\n # ...\n@@ -1591,268 +1636,270 @@ query takesCatOrDog($catOrDog: CatOrDog) {\n }\n ```\n\n\n ### All Variable Uses Defined\n\n **Formal Specification**\n\n- * For each {operation} in a document\n- * For each {variableUsage} in scope, variable must be in {operation}'s variable list.\n- * Let {fragments} be every fragment referenced by that {operation} transitively\n- * For each {fragment} in {fragments}\n- * For each {variableUsage} in scope of {fragment}, variable must be in\n- {operation}'s variable list.\n+* For each {operation} in a document\n+ * For each {variableUsage} in scope, variable must be in {operation}'s variable list.\n+ * Let {fragments} be every fragment referenced by that {operation} transitively\n+ * For each {fragment} in {fragments}\n+ * For each {variableUsage} in scope of {fragment}, variable must be in\n+ {operation}'s variable list.\n\n **Explanatory Text**\n\n Variables are scoped on a per-operation basis. That means that any variable\n used within the context of an operation must be defined at the top level of that\n operation\n\n For example:\n\n ```graphql example\n query variableIsDefined($atOtherHomes: Boolean) {\n dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n }\n ```\n\n is valid. ${atOtherHomes} is defined by the operation.\n\n-By contrast the following query is invalid:\n+By contrast the following document is invalid:\n\n ```graphql counter-example\n query variableIsNotDefined {\n dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n }\n ```\n\n ${atOtherHomes} is not defined by the operation.\n\n Fragments complicate this rule. Any fragment transitively included by an\n operation has access to the variables defined by that operation. Fragments\n can appear within multiple operations and therefore variable usages\n must correspond to variable definitions in all of those operations.\n\n For example the following is valid:\n\n ```graphql example\n query variableIsDefinedUsedInSingleFragment($atOtherHomes: Boolean) {\n dog {\n- ...isHousetrainedFragment\n+ ...isHouseTrainedFragment\n }\n }\n\n-fragment isHousetrainedFragment on Dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+fragment isHouseTrainedFragment on Dog {\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n ```\n\n-since {isHousetrainedFragment} is used within the context of the operation\n+since {isHouseTrainedFragment} is used within the context of the operation\n {variableIsDefinedUsedInSingleFragment} and the variable is defined by that\n operation.\n\n On the other hand, if a fragment is included within an operation that does\n-not define a referenced variable, the query is invalid.\n+not define a referenced variable, the document is invalid.\n\n ```graphql counter-example\n query variableIsNotDefinedUsedInSingleFragment {\n dog {\n- ...isHousetrainedFragment\n+ ...isHouseTrainedFragment\n }\n }\n\n-fragment isHousetrainedFragment on Dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+fragment isHouseTrainedFragment on Dog {\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n ```\n\n This applies transitively as well, so the following also fails:\n\n ```graphql counter-example\n query variableIsNotDefinedUsedInNestedFragment {\n dog {\n- ...outerHousetrainedFragment\n+ ...outerHouseTrainedFragment\n }\n }\n\n-fragment outerHousetrainedFragment on Dog {\n- ...isHousetrainedFragment\n+fragment outerHouseTrainedFragment on Dog {\n+ ...isHouseTrainedFragment\n }\n\n-fragment isHousetrainedFragment on Dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+fragment isHouseTrainedFragment on Dog {\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n ```\n\n Variables must be defined in all operations in which a fragment\n is used.\n\n ```graphql example\n-query housetrainedQueryOne($atOtherHomes: Boolean) {\n+query houseTrainedQueryOne($atOtherHomes: Boolean) {\n dog {\n- ...isHousetrainedFragment\n+ ...isHouseTrainedFragment\n }\n }\n\n-query housetrainedQueryTwo($atOtherHomes: Boolean) {\n+query houseTrainedQueryTwo($atOtherHomes: Boolean) {\n dog {\n- ...isHousetrainedFragment\n+ ...isHouseTrainedFragment\n }\n }\n\n-fragment isHousetrainedFragment on Dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+fragment isHouseTrainedFragment on Dog {\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n ```\n\n However the following does not validate:\n\n ```graphql counter-example\n-query housetrainedQueryOne($atOtherHomes: Boolean) {\n+query houseTrainedQueryOne($atOtherHomes: Boolean) {\n dog {\n- ...isHousetrainedFragment\n+ ...isHouseTrainedFragment\n }\n }\n\n-query housetrainedQueryTwoNotDefined {\n+query houseTrainedQueryTwoNotDefined {\n dog {\n- ...isHousetrainedFragment\n+ ...isHouseTrainedFragment\n }\n }\n\n-fragment isHousetrainedFragment on Dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+fragment isHouseTrainedFragment on Dog {\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n ```\n\n-This is because {housetrainedQueryTwoNotDefined} does not define\n-a variable ${atOtherHomes} but that variable is used by {isHousetrainedFragment}\n+This is because {houseTrainedQueryTwoNotDefined} does not define\n+a variable ${atOtherHomes} but that variable is used by {isHouseTrainedFragment}\n which is included in that operation.\n\n\n ### All Variables Used\n\n **Formal Specification**\n\n- * For every {operation} in the document.\n- * Let {variables} be the variables defined by that {operation}\n- * Each {variable} in {variables} must be used at least once in either\n- the operation scope itself or any fragment transitively referenced by that\n- operation.\n+* For every {operation} in the document.\n+* Let {variables} be the variables defined by that {operation}\n+* Each {variable} in {variables} must be used at least once in either\n+ the operation scope itself or any fragment transitively referenced by that\n+ operation.\n\n **Explanatory Text**\n\n All variables defined by an operation must be used in that operation or a\n fragment transitively included by that operation. Unused variables cause\n a validation error.\n\n For example the following is invalid:\n\n ```graphql counter-example\n query variableUnused($atOtherHomes: Boolean) {\n dog {\n- isHousetrained\n+ isHouseTrained\n }\n }\n ```\n\n because ${atOtherHomes} is not referenced.\n\n These rules apply to transitive fragment spreads as well:\n\n ```graphql example\n query variableUsedInFragment($atOtherHomes: Boolean) {\n dog {\n- ...isHousetrainedFragment\n+ ...isHouseTrainedFragment\n }\n }\n\n-fragment isHousetrainedFragment on Dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+fragment isHouseTrainedFragment on Dog {\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n ```\n\n-The above is valid since ${atOtherHomes} is used in {isHousetrainedFragment}\n+The above is valid since ${atOtherHomes} is used in {isHouseTrainedFragment}\n which is included by {variableUsedInFragment}.\n\n If that fragment did not have a reference to ${atOtherHomes} it would be not valid:\n\n ```graphql counter-example\n query variableNotUsedWithinFragment($atOtherHomes: Boolean) {\n dog {\n- ...isHousetrainedWithoutVariableFragment\n+ ...isHouseTrainedWithoutVariableFragment\n }\n }\n\n-fragment isHousetrainedWithoutVariableFragment on Dog {\n- isHousetrained\n+fragment isHouseTrainedWithoutVariableFragment on Dog {\n+ isHouseTrained\n }\n ```\n\n All operations in a document must use all of their variables.\n\n As a result, the following document does not validate.\n\n ```graphql counter-example\n query queryWithUsedVar($atOtherHomes: Boolean) {\n dog {\n- ...isHousetrainedFragment\n+ ...isHouseTrainedFragment\n }\n }\n\n query queryWithExtraVar($atOtherHomes: Boolean, $extra: Int) {\n dog {\n- ...isHousetrainedFragment\n+ ...isHouseTrainedFragment\n }\n }\n\n-fragment isHousetrainedFragment on Dog {\n- isHousetrained(atOtherHomes: $atOtherHomes)\n+fragment isHouseTrainedFragment on Dog {\n+ isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n ```\n\n This document is not valid because {queryWithExtraVar} defines\n an extraneous variable.\n\n\n ### All Variable Usages are Allowed\n\n **Formal Specification**\n\n- * For each {operation} in {document}:\n- * Let {variableUsages} be all usages transitively included in the {operation}.\n- * For each {variableUsage} in {variableUsages}:\n- * Let {variableName} be the name of {variableUsage}.\n- * Let {variableDefinition} be the {VariableDefinition} named {variableName}\n- defined within {operation}.\n- * {IsVariableUsageAllowed(variableDefinition, variableUsage)} must be {true}.\n+* For each {operation} in {document}:\n+* Let {variableUsages} be all usages transitively included in the {operation}.\n+* For each {variableUsage} in {variableUsages}:\n+ * Let {variableName} be the name of {variableUsage}.\n+ * Let {variableDefinition} be the {VariableDefinition} named {variableName}\n+ defined within {operation}.\n+ * {IsVariableUsageAllowed(variableDefinition, variableUsage)} must be {true}.\n\n IsVariableUsageAllowed(variableDefinition, variableUsage):\n+\n * Let {variableType} be the expected type of {variableDefinition}.\n * Let {locationType} be the expected type of the {Argument}, {ObjectField},\n or {ListValue} entry where {variableUsage} is located.\n * If {locationType} is a non-null type AND {variableType} is NOT a non-null type:\n * Let {hasNonNullVariableDefaultValue} be {true} if a default value exists\n for {variableDefinition} and is not the value {null}.\n * Let {hasLocationDefaultValue} be {true} if a default value exists for\n the {Argument} or {ObjectField} where {variableUsage} is located.\n * If {hasNonNullVariableDefaultValue} is NOT {true} AND\n {hasLocationDefaultValue} is NOT {true}, return {false}.\n * Let {nullableLocationType} be the unwrapped nullable type of {locationType}.\n * Return {AreTypesCompatible(variableType, nullableLocationType)}.\n * Return {AreTypesCompatible(variableType, locationType)}.\n\n AreTypesCompatible(variableType, locationType):\n+\n * If {locationType} is a non-null type:\n * If {variableType} is NOT a non-null type, return {false}.\n * Let {nullableLocationType} be the unwrapped nullable type of {locationType}.\n * Let {nullableVariableType} be the unwrapped nullable type of {variableType}.\n * Return {AreTypesCompatible(nullableVariableType, nullableLocationType)}.\n * Otherwise, if {variableType} is a non-null type:\n * Let {nullableVariableType} be the nullable type of {variableType}.\n * Return {AreTypesCompatible(nullableVariableType, locationType)}.\n@@ -1877,17 +1924,17 @@ Types must match:\n ```graphql counter-example\n query intCannotGoIntoBoolean($intArg: Int) {\n arguments {\n booleanArgField(booleanArg: $intArg)\n }\n }\n ```\n\n-${intArg} typed as {Int} cannot be used as a argument to {booleanArg}, typed as {Boolean}.\n+${intArg} typed as {Int} cannot be used as an argument to {booleanArg}, typed as {Boolean}.\n\n List cardinality must also be the same. For example, lists cannot be passed into singular\n values.\n\n ```graphql counter-example\n query booleanListCannotGoIntoBoolean($booleanListArg: [Boolean]) {\n arguments {\n booleanArgField(booleanArg: $booleanListArg)\n@@ -1933,33 +1980,37 @@ This would fail validation because a `[T]` cannot be passed to a `[T]!`.\n Similarly a `[T]` cannot be passed to a `[T!]`.\n\n **Allowing optional variables when default values exist**\n\n A notable exception to typical variable type compatibility is allowing a\n variable definition with a nullable type to be provided to a non-null location\n as long as either that variable or that location provides a default value.\n\n+In the example below, an optional variable `$booleanArg` is allowed to be used\n+in the non-null argument `optionalBooleanArg` because the field argument is\n+optional since it provides a default value in the schema.\n+\n ```graphql example\n query booleanArgQueryWithDefault($booleanArg: Boolean) {\n arguments {\n optionalNonNullBooleanArgField(optionalBooleanArg: $booleanArg)\n }\n }\n ```\n\n-In the example above, an optional variable is allowed to be used in an non-null argument which provides a default value.\n+In the example below, an optional variable `$booleanArg` is allowed to be used\n+in the non-null argument (`nonNullBooleanArg`) because the variable provides\n+a default value in the operation. This behavior is explicitly supported for\n+compatibility with earlier editions of this specification. GraphQL authoring\n+tools may wish to report this as a warning with the suggestion to replace\n+`Boolean` with `Boolean!` to avoid ambiguity.\n\n ```graphql example\n query booleanArgQueryWithDefault($booleanArg: Boolean = true) {\n arguments {\n nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)\n }\n }\n ```\n\n-In the example above, a variable provides a default value and can be used in a\n-non-null argument. This behavior is explicitly supported for compatibility with\n-earlier editions of this specification. GraphQL authoring tools may wish to\n-report this is a warning with the suggestion to replace `Boolean` with `Boolean!`.\n-\n-Note: The value {null} could still be provided to a such a variable at runtime.\n-A non-null argument must produce a field error if provided a {null} value.\n+Note: The value {null} could still be provided to such a variable at runtime.\n+A non-null argument must raise a field error if provided a {null} value.\n~~~\n
\n\n
\nspec/Section 6 -- Execution.md\n\n~~~diff\n@@ -36,20 +36,20 @@ ExecuteRequest(schema, document, operationName, variableValues, initialValue):\n * Otherwise if {operation} is a subscription operation:\n * Return {Subscribe(operation, schema, coercedVariableValues, initialValue)}.\n\n GetOperation(document, operationName):\n\n * If {operationName} is {null}:\n * If {document} contains exactly one operation.\n * Return the Operation contained in the {document}.\n- * Otherwise produce a query error requiring {operationName}.\n+ * Otherwise raise a request error requiring {operationName}.\n * Otherwise:\n * Let {operation} be the Operation named {operationName} in {document}.\n- * If {operation} was not found, produce a query error.\n+ * If {operation} was not found, raise a request error.\n * Return {operation}.\n\n\n ### Validating Requests\n\n As explained in the Validation section, only requests which pass all validation\n rules should be executed. If validation errors are known, they should be\n reported in the list of \"errors\" in the response and the request must fail\n@@ -66,17 +66,17 @@ For example: the request may be validated during development, provided it does\n not later change, or a service may validate a request once and memoize the\n result to avoid validating the same request again in the future.\n\n\n ### Coercing Variable Values\n\n If the operation has defined any variables, then the values for\n those variables need to be coerced using the input coercion rules\n-of variable's declared type. If a query error is encountered during\n+of variable's declared type. If a request error is encountered during\n input coercion of variable values, then the operation fails without\n execution.\n\n CoerceVariableValues(schema, operation, variableValues):\n\n * Let {coercedValues} be an empty unordered Map.\n * Let {variableDefinitions} be the variables defined by {operation}.\n * For each {variableDefinition} in {variableDefinitions}:\n@@ -87,62 +87,63 @@ CoerceVariableValues(schema, operation, variableValues):\n * Let {hasValue} be {true} if {variableValues} provides a value for the\n name {variableName}.\n * Let {value} be the value provided in {variableValues} for the\n name {variableName}.\n * If {hasValue} is not {true} and {defaultValue} exists (including {null}):\n * Add an entry to {coercedValues} named {variableName} with the\n value {defaultValue}.\n * Otherwise if {variableType} is a Non-Nullable type, and either {hasValue}\n- is not {true} or {value} is {null}, throw a query error.\n+ is not {true} or {value} is {null}, raise a request error.\n * Otherwise if {hasValue} is true:\n * If {value} is {null}:\n * Add an entry to {coercedValues} named {variableName} with the\n value {null}.\n * Otherwise:\n * If {value} cannot be coerced according to the input coercion\n- rules of {variableType}, throw a query error.\n+ rules of {variableType}, raise a request error.\n * Let {coercedValue} be the result of coercing {value} according to the\n input coercion rules of {variableType}.\n * Add an entry to {coercedValues} named {variableName} with the\n value {coercedValue}.\n * Return {coercedValues}.\n\n Note: This algorithm is very similar to {CoerceArgumentValues()}.\n\n\n ## Executing Operations\n\n The type system, as described in the \"Type System\" section of the spec, must\n-provide a query root object type. If mutations or subscriptions are supported,\n-it must also provide a mutation or subscription root object type, respectively.\n+provide a query root operation type. If mutations or subscriptions are supported,\n+it must also provide a mutation or subscription root operation type, respectively.\n\n ### Query\n\n If the operation is a query, the result of the operation is the result of\n-executing the query’s top level selection set with the query root object type.\n+executing the operation’s top level selection set with the query root\n+operation type.\n\n-An initial value may be provided when executing a query.\n+An initial value may be provided when executing a query operation.\n\n ExecuteQuery(query, schema, variableValues, initialValue):\n\n * Let {queryType} be the root Query type in {schema}.\n * Assert: {queryType} is an Object type.\n * Let {selectionSet} be the top level Selection Set in {query}.\n * Let {data} be the result of running\n {ExecuteSelectionSet(selectionSet, queryType, initialValue, variableValues)}\n *normally* (allowing parallelization).\n * Let {errors} be any *field errors* produced while executing the\n selection set.\n * Return an unordered map containing {data} and {errors}.\n\n ### Mutation\n\n If the operation is a mutation, the result of the operation is the result of\n-executing the mutation’s top level selection set on the mutation root\n+executing the operation’s top level selection set on the mutation root\n object type. This selection set should be executed serially.\n\n It is expected that the top level fields in a mutation operation perform\n side-effects on the underlying data system. Serial execution of the provided\n mutations ensures against race conditions during these side-effects.\n\n ExecuteMutation(mutation, schema, variableValues, initialValue):\n\n@@ -157,18 +158,18 @@ ExecuteMutation(mutation, schema, variableValues, initialValue):\n * Return an unordered map containing {data} and {errors}.\n\n ### Subscription\n\n If the operation is a subscription, the result is an event stream called the\n \"Response Stream\" where each event in the event stream is the result of\n executing the operation for each new event on an underlying \"Source Stream\".\n\n-Executing a subscription creates a persistent function on the server that\n-maps an underlying Source Stream to a returned Response Stream.\n+Executing a subscription operation creates a persistent function on the service\n+that maps an underlying Source Stream to a returned Response Stream.\n\n Subscribe(subscription, schema, variableValues, initialValue):\n\n * Let {sourceStream} be the result of running {CreateSourceEventStream(subscription, schema, variableValues, initialValue)}.\n * Let {responseStream} be the result of running {MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues)}\n * Return {responseStream}.\n\n Note: In large scale subscription systems, the {Subscribe()} and\n@@ -216,48 +217,49 @@ events or may complete at any point. Event streams may complete in response to\n an error or simply because no more events will occur. An observer may at any\n point decide to stop observing an event stream by cancelling it, after which it\n must receive no more events from that event stream.\n\n **Supporting Subscriptions at Scale**\n\n Supporting subscriptions is a significant change for any GraphQL service. Query\n and mutation operations are stateless, allowing scaling via cloning of GraphQL\n-server instances. Subscriptions, by contrast, are stateful and require\n+service instances. Subscriptions, by contrast, are stateful and require\n maintaining the GraphQL document, variables, and other context over the lifetime\n of the subscription.\n\n Consider the behavior of your system when state is lost due to the failure of a\n single machine in a service. Durability and availability may be improved by\n having separate dedicated services for managing subscription state and client\n connectivity.\n\n **Delivery Agnostic**\n\n GraphQL subscriptions do not require any specific serialization format or\n transport mechanism. Subscriptions specifies algorithms for the creation of a\n stream, the content of each payload on that stream, and the closing of that\n-stream. There are intentionally no specifications for message acknoledgement,\n+stream. There are intentionally no specifications for message acknowledgement,\n buffering, resend requests, or any other quality of service (QoS) details.\n Message serialization, transport mechanisms, and quality of service details\n should be chosen by the implementing service.\n\n #### Source Stream\n\n A Source Stream represents the sequence of events, each of which will\n trigger a GraphQL execution corresponding to that event. Like field value\n resolution, the logic to create a Source Stream is application-specific.\n\n CreateSourceEventStream(subscription, schema, variableValues, initialValue):\n\n * Let {subscriptionType} be the root Subscription type in {schema}.\n * Assert: {subscriptionType} is an Object type.\n+ * Let {selectionSet} be the top level Selection Set in {subscription}.\n * Let {groupedFieldSet} be the result of\n {CollectFields(subscriptionType, selectionSet, variableValues)}.\n- * If {groupedFieldSet} does not have exactly one entry, throw a query error.\n+ * If {groupedFieldSet} does not have exactly one entry, raise a request error.\n * Let {fields} be the value of the first entry in {groupedFieldSet}.\n * Let {fieldName} be the name of the first entry in {fields}.\n Note: This value is unaffected if an alias is used.\n * Let {field} be the first entry in {fields}.\n * Let {argumentValues} be the result of {CoerceArgumentValues(subscriptionType, field, variableValues)}\n * Let {fieldStream} be the result of running {ResolveFieldEventStream(subscriptionType, initialValue, fieldName, argumentValues)}.\n * Return {fieldStream}.\n\n@@ -325,41 +327,41 @@ ExecuteSelectionSet(selectionSet, objectType, objectValue, variableValues):\n * Let {groupedFieldSet} be the result of\n {CollectFields(objectType, selectionSet, variableValues)}.\n * Initialize {resultMap} to an empty ordered map.\n * For each {groupedFieldSet} as {responseKey} and {fields}:\n * Let {fieldName} be the name of the first entry in {fields}.\n Note: This value is unaffected if an alias is used.\n * Let {fieldType} be the return type defined for the field {fieldName} of {objectType}.\n * If {fieldType} is defined:\n- * Let {responseValue} be {ExecuteField(objectType, objectValue, fields, fieldType, variableValues)}.\n+ * Let {responseValue} be {ExecuteField(objectType, objectValue, fieldType, fields, variableValues)}.\n * Set {responseValue} as the value for {responseKey} in {resultMap}.\n * Return {resultMap}.\n\n-Note: {resultMap} is ordered by which fields appear first in the query. This\n+Note: {resultMap} is ordered by which fields appear first in the operation. This\n is explained in greater detail in the Field Collection section below.\n\n **Errors and Non-Null Fields**\n\n-If during {ExecuteSelectionSet()} a field with a non-null {fieldType} throws a\n+If during {ExecuteSelectionSet()} a field with a non-null {fieldType} raises a\n field error then that error must propagate to this entire selection set, either\n resolving to {null} if allowed or further propagated to a parent field.\n\n If this occurs, any sibling fields which have not yet executed or have not yet\n yielded a value may be cancelled to avoid unnecessary work.\n\n-See the [Errors and Non-Nullability](#sec-Errors-and-Non-Nullability) section\n-of Field Execution for more about this behavior.\n+Note: See [Handling Field Errors](#sec-Handling-Field-Errors) for more about\n+this behavior.\n\n ### Normal and Serial Execution\n\n Normally the executor can execute the entries in a grouped field set in whatever\n order it chooses (normally in parallel). Because the resolution of fields other\n than top-level mutation fields must always be side effect-free and idempotent,\n-the execution order must not affect the result, and hence the server has the\n+the execution order must not affect the result, and hence the service has the\n freedom to execute the field entries in whatever order it deems optimal.\n\n For example, given the following grouped field set to be executed normally:\n\n ```graphql example\n {\n birthday {\n month\n@@ -446,18 +448,18 @@ A correct executor must generate the following result for that selection set:\n ```\n\n\n ### Field Collection\n\n Before execution, the selection set is converted to a grouped field set by\n calling {CollectFields()}. Each entry in the grouped field set is a list of\n fields that share a response key (the alias if defined, otherwise the field\n-name). This ensures all fields with the same response key included via\n-referenced fragments are executed at the same time.\n+name). This ensures all fields with the same response key (including those\n+in referenced fragments) are executed at the same time.\n\n As an example, collecting the fields of this selection set would collect two\n instances of the field `a` and one of field `b`:\n\n ```graphql example\n {\n a {\n subfield1\n@@ -474,17 +476,17 @@ fragment ExampleFragment on Query {\n ```\n\n The depth-first-search order of the field groups produced by {CollectFields()}\n is maintained through execution, ensuring that fields appear in the executed\n response in a stable and predictable order.\n\n CollectFields(objectType, selectionSet, variableValues, visitedFragments):\n\n- * If {visitedFragments} if not provided, initialize it to the empty set.\n+ * If {visitedFragments} is not provided, initialize it to the empty set.\n * Initialize {groupedFields} to an empty ordered map of lists.\n * For each {selection} in {selectionSet}:\n * If {selection} provides the directive `@skip`, let {skipDirective} be that directive.\n * If {skipDirective}'s {if} argument is {true} or is a variable in {variableValues} with the value {true}, continue with the next\n {selection} in {selectionSet}.\n * If {selection} provides the directive `@include`, let {includeDirective} be that directive.\n * If {includeDirective}'s {if} argument is not {true} and is not a variable in {variableValues} with the value {true}, continue with the next\n {selection} in {selectionSet}.\n@@ -502,17 +504,17 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):\n {fragmentSpreadName}.\n * If no such {fragment} exists, continue with the next {selection} in\n {selectionSet}.\n * Let {fragmentType} be the type condition on {fragment}.\n * If {DoesFragmentTypeApply(objectType, fragmentType)} is false, continue\n with the next {selection} in {selectionSet}.\n * Let {fragmentSelectionSet} be the top-level selection set of {fragment}.\n * Let {fragmentGroupedFieldSet} be the result of calling\n- {CollectFields(objectType, fragmentSelectionSet, visitedFragments)}.\n+ {CollectFields(objectType, fragmentSelectionSet, variableValues, visitedFragments)}.\n * For each {fragmentGroup} in {fragmentGroupedFieldSet}:\n * Let {responseKey} be the response key shared by all fields in {fragmentGroup}.\n * Let {groupForResponseKey} be the list in {groupedFields} for\n {responseKey}; if no such list exists, create it as an empty list.\n * Append all items in {fragmentGroup} to {groupForResponseKey}.\n * If {selection} is an {InlineFragment}:\n * Let {fragmentType} be the type condition on {selection}.\n * If {fragmentType} is not {null} and {DoesFragmentTypeApply(objectType, fragmentType)} is false, continue\n@@ -530,16 +532,19 @@ DoesFragmentTypeApply(objectType, fragmentType):\n\n * If {fragmentType} is an Object Type:\n * if {objectType} and {fragmentType} are the same type, return {true}, otherwise return {false}.\n * If {fragmentType} is an Interface Type:\n * if {objectType} is an implementation of {fragmentType}, return {true} otherwise return {false}.\n * If {fragmentType} is a Union:\n * if {objectType} is a possible type of {fragmentType}, return {true} otherwise return {false}.\n\n+Note: The steps in {CollectFields()} evaluating the `@skip` and `@include`\n+directives may be applied in either order since they apply commutatively.\n+\n\n ## Executing Fields\n\n Each field requested in the grouped field set that is defined on the selected\n objectType will result in an entry in the response map. Field execution first\n coerces any provided argument values, then resolves a value for the field, and\n finally completes that value either by recursively executing another selection\n set or coercing a scalar value.\n@@ -553,18 +558,18 @@ ExecuteField(objectType, objectValue, fieldType, fields, variableValues):\n\n\n ### Coercing Field Arguments\n\n Fields may include arguments which are provided to the underlying runtime in\n order to correctly produce a value. These arguments are defined by the field in\n the type system to have a specific input type.\n\n-At each argument position in a query may be a literal {Value}, or a {Variable}\n-to be provided at runtime.\n+At each argument position in an operation may be a literal {Value}, or a\n+{Variable} to be provided at runtime.\n\n CoerceArgumentValues(objectType, field, variableValues):\n * Let {coercedValues} be an empty unordered Map.\n * Let {argumentValues} be the argument values provided in {field}.\n * Let {fieldName} be the name of {field}.\n * Let {argumentDefinitions} be the arguments defined by {objectType} for the\n field named {fieldName}.\n * For each {argumentDefinition} in {argumentDefinitions}:\n@@ -581,35 +586,35 @@ CoerceArgumentValues(objectType, field, variableValues):\n name {variableName}.\n * Let {value} be the value provided in {variableValues} for the\n name {variableName}.\n * Otherwise, let {value} be {argumentValue}.\n * If {hasValue} is not {true} and {defaultValue} exists (including {null}):\n * Add an entry to {coercedValues} named {argumentName} with the\n value {defaultValue}.\n * Otherwise if {argumentType} is a Non-Nullable type, and either {hasValue}\n- is not {true} or {value} is {null}, throw a field error.\n+ is not {true} or {value} is {null}, raise a field error.\n * Otherwise if {hasValue} is true:\n * If {value} is {null}:\n * Add an entry to {coercedValues} named {argumentName} with the\n value {null}.\n * Otherwise, if {argumentValue} is a {Variable}:\n * Add an entry to {coercedValues} named {argumentName} with the\n value {value}.\n * Otherwise:\n * If {value} cannot be coerced according to the input coercion\n- rules of {variableType}, throw a field error.\n+ rules of {argumentType}, raise a field error.\n * Let {coercedValue} be the result of coercing {value} according to the\n- input coercion rules of {variableType}.\n+ input coercion rules of {argumentType}.\n * Add an entry to {coercedValues} named {argumentName} with the\n value {coercedValue}.\n * Return {coercedValues}.\n\n Note: Variable values are not coerced because they are expected to be coerced\n-before executing the operation in {CoerceVariableValues()}, and valid queries\n+before executing the operation in {CoerceVariableValues()}, and valid operations\n must only allow usage of variables of appropriate types.\n\n\n ### Value Resolution\n\n While nearly all of GraphQL execution can be described generically, ultimately\n the internal system exposing the GraphQL interface must provide values.\n This is exposed via {ResolveFieldValue}, which produces a value for a given\n@@ -636,37 +641,58 @@ After resolving the value for a field, it is completed by ensuring it adheres\n to the expected return type. If the return type is another Object type, then\n the field execution process continues recursively.\n\n CompleteValue(fieldType, fields, result, variableValues):\n * If the {fieldType} is a Non-Null type:\n * Let {innerType} be the inner type of {fieldType}.\n * Let {completedResult} be the result of calling\n {CompleteValue(innerType, fields, result, variableValues)}.\n- * If {completedResult} is {null}, throw a field error.\n+ * If {completedResult} is {null}, raise a field error.\n * Return {completedResult}.\n * If {result} is {null} (or another internal value similar to {null} such as\n- {undefined} or {NaN}), return {null}.\n+ {undefined}), return {null}.\n * If {fieldType} is a List type:\n- * If {result} is not a collection of values, throw a field error.\n+ * If {result} is not a collection of values, raise a field error.\n * Let {innerType} be the inner type of {fieldType}.\n * Return a list where each list item is the result of calling\n {CompleteValue(innerType, fields, resultItem, variableValues)}, where\n {resultItem} is each item in {result}.\n * If {fieldType} is a Scalar or Enum type:\n- * Return the result of \"coercing\" {result}, ensuring it is a legal value of\n- {fieldType}, otherwise {null}.\n+ * Return the result of {CoerceResult(fieldType, result)}.\n * If {fieldType} is an Object, Interface, or Union type:\n * If {fieldType} is an Object type.\n * Let {objectType} be {fieldType}.\n * Otherwise if {fieldType} is an Interface or Union type.\n * Let {objectType} be {ResolveAbstractType(fieldType, result)}.\n * Let {subSelectionSet} be the result of calling {MergeSelectionSets(fields)}.\n * Return the result of evaluating {ExecuteSelectionSet(subSelectionSet, objectType, result, variableValues)} *normally* (allowing for parallelization).\n\n+**Coercing Results**\n+\n+The primary purpose of value completion is to ensure that the values returned by\n+field resolvers are valid according to the GraphQL type system and a service's\n+schema. This \"dynamic type checking\" allows GraphQL to provide consistent\n+guarantees about returned types atop any service's internal runtime.\n+\n+See the Scalars [Result Coercion and Serialization](#sec-Scalars.Result-Coercion-and-Serialization)\n+sub-section for more detailed information about how GraphQL's built-in scalars\n+coerce result values.\n+\n+CoerceResult(leafType, value):\n+ * Assert {value} is not {null}.\n+ * Return the result of calling the internal method provided by the type\n+ system for determining the \"result coercion\" of {leafType} given the value\n+ {value}. This internal method must return a valid value for the\n+ type and not {null}. Otherwise throw a field error.\n+\n+Note: If a field resolver returns {null} then it is handled within\n+{CompleteValue()} before {CoerceResult()} is called. Therefore both the input\n+and output of {CoerceResult()} must not be {null}.\n+\n **Resolving Abstract Types**\n\n When completing a field with an abstract return type, that is an Interface or\n Union return type, first the abstract type must be resolved to a relevant Object\n type. This determination is made by the internal system using whatever\n means appropriate.\n\n Note: A common method of determining the Object type for an {objectValue} in\n@@ -675,21 +701,21 @@ the {objectValue}.\n\n ResolveAbstractType(abstractType, objectValue):\n * Return the result of calling the internal method provided by the type\n system for determining the Object type of {abstractType} given the\n value {objectValue}.\n\n **Merging Selection Sets**\n\n-When more than one fields of the same name are executed in parallel, their\n+When more than one field of the same name is executed in parallel, their\n selection sets are merged together when completing the value in order to\n continue execution of the sub-selection sets.\n\n-An example query illustrating parallel fields with the same name with\n+An example operation illustrating parallel fields with the same name with\n sub-selections.\n\n ```graphql example\n {\n me {\n firstName\n }\n me {\n@@ -705,36 +731,44 @@ MergeSelectionSets(fields):\n * Let {selectionSet} be an empty list.\n * For each {field} in {fields}:\n * Let {fieldSelectionSet} be the selection set of {field}.\n * If {fieldSelectionSet} is null or empty, continue to the next field.\n * Append all selections in {fieldSelectionSet} to {selectionSet}.\n * Return {selectionSet}.\n\n\n-### Errors and Non-Nullability\n+### Handling Field Errors\n+\n+[\"Field errors\"](#sec-Errors.Field-errors) are raised from a particular field\n+during value resolution or coercion. While these errors should be reported in\n+the response, they are \"handled\" by producing a partial response.\n+\n+Note: This is distinct from [\"request errors\"](#sec-Errors.Request-errors) which\n+are raised before execution begins. If a request error is encountered, execution\n+does not begin and no data is returned in the response.\n\n-If an error is thrown while resolving a field, it should be treated as though\n-the field returned {null}, and an error must be added to the {\"errors\"} list\n-in the response.\n+If a field error is raised while resolving a field, it is handled as though the\n+field returned {null}, and the error must be added to the {\"errors\"} list in\n+the response.\n\n If the result of resolving a field is {null} (either because the function to\n-resolve the field returned {null} or because an error occurred), and that\n-field is of a `Non-Null` type, then a field error is thrown. The\n+resolve the field returned {null} or because a field error was raised), and that\n+field is of a `Non-Null` type, then a field error is raised. The\n error must be added to the {\"errors\"} list in the response.\n\n-If the field returns {null} because of an error which has already been added to\n-the {\"errors\"} list in the response, the {\"errors\"} list must not be\n+If the field returns {null} because of a field error which has already been\n+added to the {\"errors\"} list in the response, the {\"errors\"} list must not be\n further affected. That is, only one error should be added to the errors list per\n field.\n\n Since `Non-Null` type fields cannot be {null}, field errors are propagated to be\n handled by the parent field. If the parent field may be {null} then it resolves\n to {null}, otherwise if it is a `Non-Null` type, the field error is further\n-propagated to it's parent field.\n+propagated to its parent field.\n\n If a `List` type wraps a `Non-Null` type, and one of the elements of that list\n resolves to {null}, then the entire list must resolve to {null}.\n If the `List` type is also wrapped in a `Non-Null`, the field error continues\n to propagate upwards.\n\n If all fields from the root of the request to the source of the field error\n return `Non-Null` types, then the {\"data\"} entry in the response should\n~~~\n
\n\n
\nspec/Section 7 -- Response.md\n\n~~~diff\n@@ -1,76 +1,98 @@\n # Response\n\n-When a GraphQL server receives a request, it must return a well-formed\n-response. The server's response describes the result of executing the requested\n-operation if successful, and describes any errors encountered during the\n-request.\n-\n-A response may contain both a partial response as well as encountered errors in\n-the case that a field error occurred on a field which was replaced with {null}.\n+When a GraphQL service receives a request, it must return a well-formed\n+response. The service's response describes the result of executing the requested\n+operation if successful, and describes any errors raised during the request.\n\n+A response may contain both a partial response as well as any field errors in\n+the case that a field error was raised on a field and was replaced with {null}.\n\n ## Response Format\n\n-A response to a GraphQL operation must be a map.\n+A response to a GraphQL request must be a map.\n\n-If the operation encountered any errors, the response map must contain an\n+If the request raised any errors, the response map must contain an\n entry with key `errors`. The value of this entry is described in the \"Errors\"\n-section. If the operation completed without encountering any errors, this entry\n+section. If the request completed without raising any errors, this entry\n must not be present.\n\n-If the operation included execution, the response map must contain an entry\n+If the request included execution, the response map must contain an entry\n with key `data`. The value of this entry is described in the \"Data\" section. If\n-the operation failed before execution, due to a syntax error, missing\n+the request failed before execution, due to a syntax error, missing\n information, or validation error, this entry must not be present.\n\n The response map may also contain an entry with key `extensions`. This entry,\n if set, must have a map as its value. This entry is reserved for implementors\n to extend the protocol however they see fit, and hence there are no additional\n restrictions on its contents.\n\n-To ensure future changes to the protocol do not break existing servers and\n+To ensure future changes to the protocol do not break existing services and\n clients, the top level response map must not contain any entries other than the\n three described above.\n\n Note: When `errors` is present in the response, it may be helpful for it to\n appear first when serialized to make it more clear when errors are present\n in a response during debugging.\n\n ### Data\n\n The `data` entry in the response will be the result of the execution of the\n requested operation. If the operation was a query, this output will be an\n-object of the schema's query root type; if the operation was a mutation, this\n-output will be an object of the schema's mutation root type.\n+object of the query root operation type; if the operation was a\n+mutation, this output will be an object of the mutation root operation type.\n\n-If an error was encountered before execution begins, the `data` entry should\n+If an error was raised before execution begins, the `data` entry should\n not be present in the result.\n\n-If an error was encountered during the execution that prevented a valid\n+If an error was raised during the execution that prevented a valid\n response, the `data` entry in the response should be `null`.\n\n\n ### Errors\n\n The `errors` entry in the response is a non-empty list of errors, where each\n error is a map.\n\n-If no errors were encountered during the requested operation, the `errors`\n-entry should not be present in the result.\n+If no errors were raised during the request, the `errors` entry should\n+not be present in the result.\n\n If the `data` entry in the response is not present, the `errors`\n entry in the response must not be empty. It must contain at least one error.\n The errors it contains should indicate why no data was able to be returned.\n\n If the `data` entry in the response is present (including if it is the value\n-{null}), the `errors` entry in the response may contain any errors that\n-occurred during execution. If errors occurred during execution, it should\n-contain those errors.\n+{null}), the `errors` entry in the response may contain any field errors that\n+were raised during execution. If field errors were raised during execution, it\n+should contain those errors.\n+\n+**Request errors**\n+\n+Request errors are raised before execution begins. This may occur due to a parse\n+grammar or validation error in the requested document, an inability to determine\n+which operation to execute, or invalid input values for variables.\n+\n+Request errors are typically the fault of the requesting client.\n+\n+If a request error is raised, execution does not begin and the `data` entry in\n+the response must not be present. The `errors` entry must include the error.\n+\n+**Field errors**\n+\n+Field errors are raised during execution from a particular field. This may occur\n+due to an internal error during value resolution or failure to coerce the\n+resulting value.\n+\n+Field errors are typically the fault of GraphQL service.\n+\n+If a field error is raised, execution attempts to continue and a partial result\n+is produced (see [Handling Field Errors](#sec-Handling-Field-Errors)).\n+The `data` entry in the response must be present. The `errors` entry should\n+include all raised field errors.\n\n **Error result format**\n\n Every error must contain an entry with the key `message` with a string\n description of the error intended for the developer as a guide to understand\n and correct the error.\n\n If an error can be associated to a particular point in the requested GraphQL\n@@ -84,20 +106,20 @@ must contain an entry with the key `path` that details the path of the\n response field which experienced the error. This allows clients to identify\n whether a `null` result is intentional or caused by a runtime error.\n\n This field should be a list of path segments starting at the root of the\n response and ending with the field associated with the error. Path segments\n that represent fields should be strings, and path segments that\n represent list indices should be 0-indexed integers. If the error happens\n in an aliased field, the path to the error should use the aliased name, since\n-it represents a path in the response, not in the query.\n+it represents a path in the response, not in the request.\n\n For example, if fetching one of the friends' names fails in the following\n-query:\n+operation:\n\n ```graphql example\n {\n hero(episode: $episode) {\n name\n heroFriends: friends {\n id\n name\n@@ -108,18 +130,18 @@ query:\n\n The response might look like:\n\n ```json example\n {\n \"errors\": [\n {\n \"message\": \"Name for character with ID 1002 could not be fetched.\",\n- \"locations\": [ { \"line\": 6, \"column\": 7 } ],\n- \"path\": [ \"hero\", \"heroFriends\", 1, \"name\" ]\n+ \"locations\": [{ \"line\": 6, \"column\": 7 }],\n+ \"path\": [\"hero\", \"heroFriends\", 1, \"name\"]\n }\n ],\n \"data\": {\n \"hero\": {\n \"name\": \"R2-D2\",\n \"heroFriends\": [\n {\n \"id\": \"1000\",\n@@ -137,29 +159,29 @@ The response might look like:\n }\n }\n }\n ```\n\n If the field which experienced an error was declared as `Non-Null`, the `null`\n result will bubble up to the next nullable field. In that case, the `path`\n for the error should include the full path to the result field where the error\n-occurred, even if that field is not present in the response.\n+was raised, even if that field is not present in the response.\n\n For example, if the `name` field from above had declared a `Non-Null` return\n type in the schema, the result would look different but the error reported would\n be the same:\n\n ```json example\n {\n \"errors\": [\n {\n \"message\": \"Name for character with ID 1002 could not be fetched.\",\n- \"locations\": [ { \"line\": 6, \"column\": 7 } ],\n- \"path\": [ \"hero\", \"heroFriends\", 1, \"name\" ]\n+ \"locations\": [{ \"line\": 6, \"column\": 7 }],\n+ \"path\": [\"hero\", \"heroFriends\", 1, \"name\"]\n }\n ],\n \"data\": {\n \"hero\": {\n \"name\": \"R2-D2\",\n \"heroFriends\": [\n {\n \"id\": \"1000\",\n@@ -181,18 +203,18 @@ This entry, if set, must have a map as its value. This entry is reserved for\n implementors to add additional information to errors however they see fit, and\n there are no additional restrictions on its contents.\n\n ```json example\n {\n \"errors\": [\n {\n \"message\": \"Name for character with ID 1002 could not be fetched.\",\n- \"locations\": [ { \"line\": 6, \"column\": 7 } ],\n- \"path\": [ \"hero\", \"heroFriends\", 1, \"name\" ],\n+ \"locations\": [{ \"line\": 6, \"column\": 7 }],\n+ \"path\": [\"hero\", \"heroFriends\", 1, \"name\"],\n \"extensions\": {\n \"code\": \"CAN_NOT_FETCH_BY_ID\",\n \"timestamp\": \"Fri Feb 9 14:33:09 UTC 2018\"\n }\n }\n ]\n }\n ```\n@@ -205,18 +227,18 @@ Note: Previous versions of this spec did not describe the `extensions` entry\n for error formatting. While non-specified entries are not violations, they are\n still discouraged.\n\n ```json counter-example\n {\n \"errors\": [\n {\n \"message\": \"Name for character with ID 1002 could not be fetched.\",\n- \"locations\": [ { \"line\": 6, \"column\": 7 } ],\n- \"path\": [ \"hero\", \"heroFriends\", 1, \"name\" ],\n+ \"locations\": [{ \"line\": 6, \"column\": 7 }],\n+ \"path\": [\"hero\", \"heroFriends\", 1, \"name\"],\n \"code\": \"CAN_NOT_FETCH_BY_ID\",\n \"timestamp\": \"Fri Feb 9 14:33:09 UTC 2018\"\n }\n ]\n }\n ```\n\n\n@@ -269,18 +291,18 @@ values should be used to encode the related GraphQL values:\n Note: For consistency and ease of notation, examples of responses are given in\n JSON format throughout this document.\n\n\n ### Serialized Map Ordering\n\n Since the result of evaluating a selection set is ordered, the serialized Map of\n results should preserve this order by writing the map entries in the same order\n-as those fields were requested as defined by query execution. Producing a\n-serialized response where fields are represented in the same order in which\n+as those fields were requested as defined by selection set execution. Producing\n+a serialized response where fields are represented in the same order in which\n they appear in the request improves human readability during debugging and\n enables more efficient parsing of responses if the order of properties can\n be anticipated.\n\n Serialization formats which represent an ordered map should preserve the\n order of requested fields as defined by {CollectFields()} in the Execution\n section. Serialization formats which only represent unordered maps but where\n order is still implicit in the serialization's textual order (such as JSON)\n~~~\n
\n\n
\nspec/Appendix A -- Notation Conventions.md\n\n~~~diff\n@@ -17,119 +17,133 @@ its right-hand side.\n\n Starting from a single goal non-terminal symbol, a context-free grammar\n describes a language: the set of possible sequences of characters that can be\n described by repeatedly replacing any non-terminal in the goal sequence with one\n of the sequences it is defined by, until all non-terminal symbols have been\n replaced by terminal characters.\n\n Terminals are represented in this document in a monospace font in two forms: a\n-specific Unicode character or sequence of Unicode characters (ex. {`=`} or {`terminal`}), and a pattern of Unicode characters defined by a regular expression\n-(ex {/[0-9]+/}).\n+specific Unicode character or sequence of Unicode characters (ie. {`=`} or\n+{`terminal`}), and prose typically describing a specific Unicode code-point\n+{\"Space (U+0020)\"}. Sequences of Unicode characters only appear in syntactic\n+grammars and represent a {Name} token of that specific sequence.\n\n Non-terminal production rules are represented in this document using the\n following notation for a non-terminal with a single definition:\n\n NonTerminalWithSingleDefinition : NonTerminal `terminal`\n\n While using the following notation for a production with a list of definitions:\n\n NonTerminalWithManyDefinitions :\n - OtherNonTerminal `terminal`\n - `terminal`\n\n A definition may refer to itself, which describes repetitive sequences,\n for example:\n\n ListOfLetterA :\n- - `a`\n - ListOfLetterA `a`\n+ - `a`\n\n\n ## Lexical and Syntactical Grammar\n\n The GraphQL language is defined in a syntactic grammar where terminal symbols\n are tokens. Tokens are defined in a lexical grammar which matches patterns of\n-source characters. The result of parsing a sequence of source Unicode characters\n-produces a GraphQL AST.\n+source characters. The result of parsing a source text sequence of Unicode\n+characters first produces a sequence of lexical tokens according to the lexical\n+grammar which then produces abstract syntax tree (AST) according to the\n+syntactical grammar.\n\n-A Lexical grammar production describes non-terminal \"tokens\" by\n+A lexical grammar production describes non-terminal \"tokens\" by\n patterns of terminal Unicode characters. No \"whitespace\" or other ignored\n characters may appear between any terminal Unicode characters in the lexical\n grammar production. A lexical grammar production is distinguished by a two colon\n `::` definition.\n\n-Word :: /[A-Za-z]+/\n+Word :: Letter+\n\n A Syntactical grammar production describes non-terminal \"rules\" by patterns of\n-terminal Tokens. Whitespace and other ignored characters may appear before or\n-after any terminal Token. A syntactical grammar production is distinguished by a\n-one colon `:` definition.\n+terminal Tokens. {WhiteSpace} and other {Ignored} sequences may appear before or\n+after any terminal {Token}. A syntactical grammar production is distinguished by\n+a one colon `:` definition.\n\n-Sentence : Noun Verb\n+Sentence : Word+ `.`\n\n\n ## Grammar Notation\n\n This specification uses some additional notation to describe common patterns,\n such as optional or repeated patterns, or parameterized alterations of the\n definition of a non-terminal. This section explains these short-hand notations\n and their expanded definitions in the context-free grammar.\n\n\n **Constraints**\n\n A grammar production may specify that certain expansions are not permitted by\n using the phrase \"but not\" and then indicating the expansions to be excluded.\n\n-For example, the production:\n-\n-SafeName : Name but not SevenCarlinWords\n+For example, the following production means that the non-terminal {SafeWord} may\n+be replaced by any sequence of characters that could replace {Word} provided\n+that the same sequence of characters could not replace {SevenCarlinWords}.\n\n-means that the nonterminal {SafeName} may be replaced by any sequence of\n-characters that could replace {Name} provided that the same sequence of\n-characters could not replace {SevenCarlinWords}.\n+SafeWord : Word but not SevenCarlinWords\n\n A grammar may also list a number of restrictions after \"but not\" separated\n by \"or\".\n\n For example:\n\n NonBooleanName : Name but not `true` or `false`\n\n\n+**Lookahead Restrictions**\n+\n+A grammar production may specify that certain characters or tokens are not\n+permitted to follow it by using the pattern {[lookahead != NotAllowed]}.\n+Lookahead restrictions are often used to remove ambiguity from the grammar.\n+\n+The following example makes it clear that {Letter+} must be greedy, since {Word}\n+cannot be followed by yet another {Letter}.\n+\n+Word :: Letter+ [lookahead != Letter]\n+\n+\n **Optionality and Lists**\n\n A subscript suffix \"{Symbol?}\" is shorthand for two possible sequences, one\n including that symbol and one excluding it.\n\n As an example:\n\n Sentence : Noun Verb Adverb?\n\n is shorthand for\n\n Sentence :\n- - Noun Verb\n - Noun Verb Adverb\n+ - Noun Verb\n\n-A subscript suffix \"{Symbol+}\" is shorthand for a list of\n-one or more of that symbol.\n+A subscript suffix \"{Symbol+}\" is shorthand for a list of one or more of that\n+symbol, represented as an additional recursive production.\n\n As an example:\n\n Book : Cover Page+ Cover\n\n is shorthand for\n\n Book : Cover Page_list Cover\n\n Page_list :\n- - Page\n - Page_list Page\n+ - Page\n\n\n **Parameterized Grammar Productions**\n\n A symbol definition subscript suffix parameter in braces \"{Symbol[Param]}\"\n is shorthand for two symbol definitions, one appended with that parameter name,\n the other without. The same subscript suffix on a symbol is shorthand for that\n variant of the definition. If the parameter starts with \"?\", that\n@@ -182,19 +196,19 @@ StringValue :: `\"` StringCharacter+ `\"`\n\n This specification describes some algorithms used by the static and runtime\n semantics, they're defined in the form of a function-like syntax with the\n algorithm's name and the arguments it accepts along with a list of algorithmic\n steps to take in the order listed. Each step may establish references to other\n values, check various conditions, call other algorithms, and eventually return\n a value representing the outcome of the algorithm for the provided arguments.\n\n-For example, the following example describes an algorithm named {Fibonacci} which\n-accepts a single argument {number}. The algoritm's steps produce the next number\n-in the Fibonacci sequence:\n+For example, the following example describes an algorithm named {Fibonacci}\n+which accepts a single argument {number}. The algorithm's steps produce the next\n+number in the Fibonacci sequence:\n\n Fibonacci(number):\n * If {number} is {0}:\n * Return {1}.\n * If {number} is {1}:\n * Return {2}.\n * Let {previousNumber} be {number} - {1}.\n * Let {previousPreviousNumber} be {number} - {2}.\n~~~\n
\n\n
\nspec/Appendix B -- Grammar Summary.md\n\n~~~diff\n@@ -1,11 +1,17 @@\n # B. Appendix: Grammar Summary\n\n-SourceCharacter :: /[\\u0009\\u000A\\u000D\\u0020-\\uFFFF]/\n+## Source Text\n+\n+SourceCharacter ::\n+ - \"U+0009\"\n+ - \"U+000A\"\n+ - \"U+000D\"\n+ - \"U+0020–U+FFFF\"\n\n\n ## Ignored Tokens\n\n Ignored ::\n - UnicodeBOM\n - WhiteSpace\n - LineTerminator\n@@ -15,103 +21,122 @@ Ignored ::\n UnicodeBOM :: \"Byte Order Mark (U+FEFF)\"\n\n WhiteSpace ::\n - \"Horizontal Tab (U+0009)\"\n - \"Space (U+0020)\"\n\n LineTerminator ::\n - \"New Line (U+000A)\"\n- - \"Carriage Return (U+000D)\" [ lookahead ! \"New Line (U+000A)\" ]\n+ - \"Carriage Return (U+000D)\" [lookahead != \"New Line (U+000A)\"]\n - \"Carriage Return (U+000D)\" \"New Line (U+000A)\"\n\n-Comment :: `#` CommentChar*\n+Comment :: `#` CommentChar* [lookahead != CommentChar]\n\n CommentChar :: SourceCharacter but not LineTerminator\n\n Comma :: ,\n\n\n ## Lexical Tokens\n\n Token ::\n - Punctuator\n - Name\n - IntValue\n - FloatValue\n - StringValue\n\n-Punctuator :: one of ! $ ( ) ... : = @ [ ] { | }\n+Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | }\n+\n+Name ::\n+ - NameStart NameContinue* [lookahead != NameContinue]\n+\n+NameStart ::\n+ - Letter\n+ - `_`\n\n-Name :: /[_A-Za-z][_0-9A-Za-z]*/\n+NameContinue ::\n+ - Letter\n+ - Digit\n+ - `_`\n\n-IntValue :: IntegerPart\n+Letter :: one of\n+ - `A` `B` `C` `D` `E` `F` `G` `H` `I` `J` `K` `L` `M`\n+ - `N` `O` `P` `Q` `R` `S` `T` `U` `V` `W` `X` `Y` `Z`\n+ - `a` `b` `c` `d` `e` `f` `g` `h` `i` `j` `k` `l` `m`\n+ - `n` `o` `p` `q` `r` `s` `t` `u` `v` `w` `x` `y` `z`\n+\n+Digit :: one of\n+ - `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`\n+\n+IntValue :: IntegerPart [lookahead != {Digit, `.`, NameStart}]\n\n IntegerPart ::\n - NegativeSign? 0\n - NegativeSign? NonZeroDigit Digit*\n\n NegativeSign :: -\n\n-Digit :: one of 0 1 2 3 4 5 6 7 8 9\n-\n NonZeroDigit :: Digit but not `0`\n\n FloatValue ::\n- - IntegerPart FractionalPart\n- - IntegerPart ExponentPart\n- - IntegerPart FractionalPart ExponentPart\n+ - IntegerPart FractionalPart ExponentPart [lookahead != {Digit, `.`, NameStart}]\n+ - IntegerPart FractionalPart [lookahead != {Digit, `.`, NameStart}]\n+ - IntegerPart ExponentPart [lookahead != {Digit, `.`, NameStart}]\n\n FractionalPart :: . Digit+\n\n ExponentPart :: ExponentIndicator Sign? Digit+\n\n ExponentIndicator :: one of `e` `E`\n\n Sign :: one of + -\n\n StringValue ::\n- - `\"` StringCharacter* `\"`\n+ - `\"\"` [lookahead != `\"`]\n+ - `\"` StringCharacter+ `\"`\n - `\"\"\"` BlockStringCharacter* `\"\"\"`\n\n StringCharacter ::\n- - SourceCharacter but not `\"` or \\ or LineTerminator\n- - \\u EscapedUnicode\n- - \\ EscapedCharacter\n+ - SourceCharacter but not `\"` or `\\` or LineTerminator\n+ - `\\u` EscapedUnicode\n+ - `\\` EscapedCharacter\n\n EscapedUnicode :: /[0-9A-Fa-f]{4}/\n\n-EscapedCharacter :: one of `\"` \\ `/` b f n r t\n+EscapedCharacter :: one of `\"` `\\` `/` `b` `f` `n` `r` `t`\n\n BlockStringCharacter ::\n - SourceCharacter but not `\"\"\"` or `\\\"\"\"`\n - `\\\"\"\"`\n\n Note: Block string values are interpreted to exclude blank initial and trailing\n lines and uniform indentation with {BlockStringValue()}.\n\n\n-## Document\n+## Document Syntax\n\n Document : Definition+\n\n Definition :\n - ExecutableDefinition\n- - TypeSystemDefinition\n- - TypeSystemExtension\n+ - TypeSystemDefinitionOrExtension\n+\n+ExecutableDocument : ExecutableDefinition+\n\n ExecutableDefinition :\n - OperationDefinition\n - FragmentDefinition\n\n OperationDefinition :\n- - SelectionSet\n - OperationType Name? VariableDefinitions? Directives? SelectionSet\n+ - SelectionSet\n\n-OperationType : one of query mutation subscription\n+OperationType : one of `query` `mutation` `subscription`\n\n SelectionSet : { Selection+ }\n\n Selection :\n - Field\n - FragmentSpread\n - InlineFragment\n\n@@ -157,17 +182,17 @@ ListValue[Const] :\n ObjectValue[Const] :\n - { }\n - { ObjectField[?Const]+ }\n\n ObjectField[Const] : Name : Value[?Const]\n\n VariableDefinitions : ( VariableDefinition+ )\n\n-VariableDefinition : Variable : Type DefaultValue?\n+VariableDefinition : Variable : Type DefaultValue? Directives[Const]?\n\n Variable : $ Name\n\n DefaultValue : = Value[Const]\n\n Type :\n - NamedType\n - ListType\n@@ -180,32 +205,40 @@ ListType : [ Type ]\n NonNullType :\n - NamedType !\n - ListType !\n\n Directives[Const] : Directive[?Const]+\n\n Directive[Const] : @ Name Arguments[?Const]?\n\n+TypeSystemDocument : TypeSystemDefinition+\n+\n TypeSystemDefinition :\n - SchemaDefinition\n - TypeDefinition\n - DirectiveDefinition\n\n+TypeSystemExtensionDocument : TypeSystemDefinitionOrExtension+\n+\n+TypeSystemDefinitionOrExtension :\n+ - TypeSystemDefinition\n+ - TypeSystemExtension\n+\n TypeSystemExtension :\n - SchemaExtension\n - TypeExtension\n\n-SchemaDefinition : schema Directives[Const]? { OperationTypeDefinition+ }\n+SchemaDefinition : Description? schema Directives[Const]? { RootOperationTypeDefinition+ }\n\n SchemaExtension :\n- - extend schema Directives[Const]? { OperationTypeDefinition+ }\n- - extend schema Directives[Const]\n+ - extend schema Directives[Const]? { RootOperationTypeDefinition+ }\n+ - extend schema Directives[Const] [lookahead != `{`]\n\n-OperationTypeDefinition : OperationType : NamedType\n+RootOperationTypeDefinition : OperationType : NamedType\n\n Description : StringValue\n\n TypeDefinition :\n - ScalarTypeDefinition\n - ObjectTypeDefinition\n - InterfaceTypeDefinition\n - UnionTypeDefinition\n@@ -220,92 +253,102 @@ TypeExtension :\n - EnumTypeExtension\n - InputObjectTypeExtension\n\n ScalarTypeDefinition : Description? scalar Name Directives[Const]?\n\n ScalarTypeExtension :\n - extend scalar Name Directives[Const]\n\n-ObjectTypeDefinition : Description? type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition?\n+ObjectTypeDefinition :\n+ - Description? type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition\n+ - Description? type Name ImplementsInterfaces? Directives[Const]? [lookahead != `{`]\n\n ObjectTypeExtension :\n - extend type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition\n- - extend type Name ImplementsInterfaces? Directives[Const]\n- - extend type Name ImplementsInterfaces\n+ - extend type Name ImplementsInterfaces? Directives[Const] [lookahead != `{`]\n+ - extend type Name ImplementsInterfaces [lookahead != `{`]\n\n ImplementsInterfaces :\n- - implements `&`? NamedType\n - ImplementsInterfaces & NamedType\n+ - implements `&`? NamedType\n\n FieldsDefinition : { FieldDefinition+ }\n\n FieldDefinition : Description? Name ArgumentsDefinition? : Type Directives[Const]?\n\n ArgumentsDefinition : ( InputValueDefinition+ )\n\n InputValueDefinition : Description? Name : Type DefaultValue? Directives[Const]?\n\n-InterfaceTypeDefinition : Description? interface Name Directives[Const]? FieldsDefinition?\n+InterfaceTypeDefinition :\n+ - Description? interface Name ImplementsInterfaces? Directives[Const]? FieldsDefinition\n+ - Description? interface Name ImplementsInterfaces? Directives[Const]? [lookahead != `{`]\n\n InterfaceTypeExtension :\n- - extend interface Name Directives[Const]? FieldsDefinition\n- - extend interface Name Directives[Const]\n+ - extend interface Name ImplementsInterfaces? Directives[Const]? FieldsDefinition\n+ - extend interface Name ImplementsInterfaces? Directives[Const] [lookahead != `{`]\n+ - extend interface Name ImplementsInterfaces [lookahead != `{`]\n\n UnionTypeDefinition : Description? union Name Directives[Const]? UnionMemberTypes?\n\n UnionMemberTypes :\n- - = `|`? NamedType\n - UnionMemberTypes | NamedType\n+ - = `|`? NamedType\n\n UnionTypeExtension :\n - extend union Name Directives[Const]? UnionMemberTypes\n - extend union Name Directives[Const]\n\n-EnumTypeDefinition : Description? enum Name Directives[Const]? EnumValuesDefinition?\n+EnumTypeDefinition :\n+ - Description? enum Name Directives[Const]? EnumValuesDefinition\n+ - Description? enum Name Directives[Const]? [lookahead != `{`]\n\n EnumValuesDefinition : { EnumValueDefinition+ }\n\n EnumValueDefinition : Description? EnumValue Directives[Const]?\n\n EnumTypeExtension :\n - extend enum Name Directives[Const]? EnumValuesDefinition\n- - extend enum Name Directives[Const]\n+ - extend enum Name Directives[Const] [lookahead != `{`]\n\n-InputObjectTypeDefinition : Description? input Name Directives[Const]? InputFieldsDefinition?\n+InputObjectTypeDefinition :\n+ - Description? input Name Directives[Const]? InputFieldsDefinition\n+ - Description? input Name Directives[Const]? [lookahead != `{`]\n\n InputFieldsDefinition : { InputValueDefinition+ }\n\n InputObjectTypeExtension :\n - extend input Name Directives[Const]? InputFieldsDefinition\n- - extend input Name Directives[Const]\n+ - extend input Name Directives[Const] [lookahead != `{`]\n\n-DirectiveDefinition : Description? directive @ Name ArgumentsDefinition? on DirectiveLocations\n+DirectiveDefinition : Description? directive @ Name ArgumentsDefinition? `repeatable`? on DirectiveLocations\n\n DirectiveLocations :\n- - `|`? DirectiveLocation\n - DirectiveLocations | DirectiveLocation\n+ - `|`? DirectiveLocation\n\n DirectiveLocation :\n - ExecutableDirectiveLocation\n - TypeSystemDirectiveLocation\n\n ExecutableDirectiveLocation : one of\n- `QUERY`\n- `MUTATION`\n- `SUBSCRIPTION`\n- `FIELD`\n- `FRAGMENT_DEFINITION`\n- `FRAGMENT_SPREAD`\n- `INLINE_FRAGMENT`\n+ - `QUERY`\n+ - `MUTATION`\n+ - `SUBSCRIPTION`\n+ - `FIELD`\n+ - `FRAGMENT_DEFINITION`\n+ - `FRAGMENT_SPREAD`\n+ - `INLINE_FRAGMENT`\n+ - `VARIABLE_DEFINITION`\n\n TypeSystemDirectiveLocation : one of\n- `SCHEMA`\n- `SCALAR`\n- `OBJECT`\n- `FIELD_DEFINITION`\n- `ARGUMENT_DEFINITION`\n- `INTERFACE`\n- `UNION`\n- `ENUM`\n- `ENUM_VALUE`\n- `INPUT_OBJECT`\n- `INPUT_FIELD_DEFINITION`\n+ - `SCHEMA`\n+ - `SCALAR`\n+ - `OBJECT`\n+ - `FIELD_DEFINITION`\n+ - `ARGUMENT_DEFINITION`\n+ - `INTERFACE`\n+ - `UNION`\n+ - `ENUM`\n+ - `ENUM_VALUE`\n+ - `INPUT_OBJECT`\n+ - `INPUT_FIELD_DEFINITION`\n~~~\n\n\nGenerated with:\n\n```sh\ngit diff June2018..HEAD --minimal -U8 -- spec\n```\n" }, { "path": "changelogs/September2025.md", "content": "# September 2025 Changelog\n\nThis describes the set of changes since the last edition of the GraphQL\nspecification, [October2021](https://spec.graphql.org/October2021/) (see\n[prior changelog](./October2021.md)). It's intended to ease the review of\nchanges since the last edition for reviewers or curious readers, but is not\nnormative. Please read the\n[specification document](https://spec.graphql.org/September2025/) itself for\nfull detail and context.\n\n## Thank you, contributors!\n\nThe last few years have seen GraphQL reach a wide breath of use, powering\ninternal and external APIs at startups and enterprises, and integrating with\nvarious platforms and tools. Work contributed to GraphQL has fit into two\npriorities:\n\n1. **Maintain a stable base.** With a huge ecosystem built atop GraphQL, it's\n our responsibility to put stability above all else. The vast majority of work\n has fixed inconsistencies, improved behavior in edge and corner cases,\n improve security, and avoid performance pitfalls.\n\n2. **Provide a productive expressive query language.** GraphQL was designed with\n API consumers in mind, and this spec release includes significant\n improvements to the GraphQL query engine and language.\n\nSignificant contributions have been made since the last edition of the spec, and\nboth of these priories remain active areas of investment with many exciting RFCs\nstill in the works.\n\nOver 100 commits made to the GraphQL spec since the last edition, most of which\nhave dozens or hundreds of comments! It's a huge amount of work to champion\nthese changes, and a great responsibility to evolve the technical foundations\nfor this community and ecosystem.\n\nThank you!\n\n- [@leebyron](https://github.com/leebyron), Editor\n\n## Contributors\n\nAnyone is welcome to join working group meetings and contribute to GraphQL. See\n[Contributing.md](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md)\nfor more information. Thank you to these community members for their technical\ncontribution to this edition of the GraphQL specification.\n\n| Author | Github |\n| ------------------ | -------------------------------------------------------- |\n| Alex Reilly | [@twof](https://github.com/twof) |\n| Andreas Marek | [@andimarek](https://github.com/andimarek) |\n| Ben Kraft | [@benjaminjkraft](https://github.com/benjaminjkraft) |\n| Benedikt Franke | [@spawnia](https://github.com/spawnia) |\n| Benjie | [@benjie](https://github.com/benjie) |\n| Benoit 'BoD' Lubek | [@BoD](https://github.com/BoD) |\n| dondonz | [@dondonz](https://github.com/dondonz) |\n| dugenkui | [@dugenkui03](https://github.com/dugenkui03) |\n| Glen | [@glen-84](https://github.com/glen-84) |\n| Ivan Goncharov | [@IvanGoncharov](https://github.com/IvanGoncharov) |\n| Ivan Maximov | [@sungam3r](https://github.com/sungam3r) |\n| James Bellenger | [@jbellenger](https://github.com/jbellenger) |\n| Jan Melcher | [@Yogu](https://github.com/Yogu) |\n| Jason Dent | [@Jason3S](https://github.com/Jason3S) |\n| Jeff Auriemma | [@bignimbus](https://github.com/bignimbus) |\n| Jovi De Croock | [@JoviDeCroock](https://github.com/JoviDeCroock) |\n| Kevin Smithson | [@smitt04](https://github.com/smitt04) |\n| Lee Byron | [@leebyron](https://github.com/leebyron) |\n| Mark Larah | [@magicmark](https://github.com/magicmark) |\n| Martin Bonnin | [@martinbonnin](https://github.com/martinbonnin) |\n| Michael Staib | [@michaelstaib](https://github.com/michaelstaib) |\n| Mike Solomon | [@msolomon](https://github.com/msolomon) |\n| PascalSenn | [@PascalSenn](https://github.com/PascalSenn) |\n| Renée | [@goto-bus-stop](https://github.com/goto-bus-stop) |\n| Rob Richard | [@robrichard](https://github.com/robrichard) |\n| Roman Ivantsov | [@rivantsov](https://github.com/rivantsov) |\n| Shane Krueger | [@Shane32](https://github.com/Shane32) |\n| Stephen Spalding | [@fotoetienne](https://github.com/fotoetienne) |\n| Thomas Heyenbrock | [@thomasheyenbrock](https://github.com/thomasheyenbrock) |\n| Yaacov Rydzinski | [@yaacovCR](https://github.com/yaacovCR) |\n\nGenerated with:\n\n```sh\nnode scripts/generate-contributor-list.mjs October2021..HEAD\n```\n\n## Notable contributions\n\nA few notable changes in this edition:\n\n- OneOf input objects, aka \"input unions\"\n ([#825](https://github.com/graphql/graphql-spec/pull/825))\n- Schema coordinates as a standard for GraphQL tooling and reporting\n ([#794](https://github.com/graphql/graphql-spec/pull/794))\n- Descriptions on documents, in motivation for AI-consumers\n ([#1170](https://github.com/graphql/graphql-spec/pull/1170))\n- Broader support for deprecation across a GraphQL Schema\n ([#805](https://github.com/graphql/graphql-spec/pull/805)\n [#1040](https://github.com/graphql/graphql-spec/pull/1040)\n [#1053](https://github.com/graphql/graphql-spec/pull/1053)\n [#1142](https://github.com/graphql/graphql-spec/pull/1142))\n- GraphQL language has been updated to support the full Unicode range\n ([#849](https://github.com/graphql/graphql-spec/pull/849))\n- Countless editorial improvements! The spec is much easier to read and\n contribute to, with fewer ambiguities.\n\n## Changeset\n\n- [Github: all Accepted RFC PRs merged since last spec cut](https://github.com/graphql/graphql-spec/pulls?q=is%3Apr+is%3Amerged+base%3Amain+merged%3A2021-10-01..2025-09-03+label%3A%22%F0%9F%8F%81+Accepted+%28RFC+3%29%22)\n- [Github: all Editorial PRs merged since last spec cut](https://github.com/graphql/graphql-spec/pulls?page=1&q=is%3Apr+is%3Amerged+base%3Amain+merged%3A2021-10-01..2025-09-03+label%3A%22%E2%9C%8F%EF%B8%8F+Editorial%22)\n- [Github: all changes since last spec cut](https://github.com/graphql/graphql-spec/compare/October2021...f29fbcd2ab5af763fce7ad62896eb62465a669b3)\n\nListed in reverse-chronological order (latest commit on top).\n\n| Hash | Change | Authors |\n| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| [f29fbcd](https://github.com/graphql/graphql-spec/commit/f29fbcd2ab5af763fce7ad62896eb62465a669b3) | gpt guided style guide improvements (#1190) | Lee Byron |\n| [0157a79](https://github.com/graphql/graphql-spec/commit/0157a79b8873f0f575d254270ee700f205b0f7b2) | Fix link format for input coercion rules (#1189) | Yaacov Rydzinski |\n| [f70abe2](https://github.com/graphql/graphql-spec/commit/f70abe24469d0c8bd374211c8eb621cd421b69f9) | Recommend that order of unordered collections is maintained where possible (#1092) | Benjie Lee Byron |\n| [11c6664](https://github.com/graphql/graphql-spec/commit/11c6664e2ea65eddd812bac73b9e7341b4610292) | condense the spec defs appendix (#1186) | Lee Byron |\n| [10331b0](https://github.com/graphql/graphql-spec/commit/10331b0f303a1df76d465f153704bc106ed449e6) | RFC: OneOf Input Objects (#825) | Benjie Michael Staib Shane Krueger Yaacov Rydzinski Glen Lee Byron |\n| [cd0b8bd](https://github.com/graphql/graphql-spec/commit/cd0b8bd14c0a741ee2ea92d24b97985c6522e5c9) | Pull copyright and license into repo-level LICENSE.md (#1172) | Lee Byron |\n| [1e29b8a](https://github.com/graphql/graphql-spec/commit/1e29b8aea0e098663e43dba4693e88c6b033f6f8) | Schema Coordinates (#794) | Mark Larah Benjie Gillam Lee Byron Lee Byron Martin Bonnin Benoit 'BoD' Lubek |\n| [bc4ddea](https://github.com/graphql/graphql-spec/commit/bc4ddea0c9121a3e4effd4bbdcc0ebdfaae6e79a) | Fix CoerceArgumentValues() hasValue (#1056) | Benjie |\n| [b1a23de](https://github.com/graphql/graphql-spec/commit/b1a23de96f86865b2bc7f8bd613900d4afd10cc0) | Fix typo in merged \"executable documents\" PR (#1176) | Benjie Lee Byron |\n| [9939469](https://github.com/graphql/graphql-spec/commit/9939469d1315dc2f7458c885699996e2a78516f1) | Minor editorial tweaks following the merge of #1039 (#1175) | Benjie |\n| [468d848](https://github.com/graphql/graphql-spec/commit/468d84881646b9da00511c7ce68febdfc9a1875b) | editorial: move normative clause above example in descriptions (#1173) | Lee Byron |\n| [7eb8983](https://github.com/graphql/graphql-spec/commit/7eb8983955fbbc047da301d6a58c450a175cea5b) | [RFC] Default value coercion rules (#793) | Benjie Lee Byron |\n| [fca6653](https://github.com/graphql/graphql-spec/commit/fca66537c5e1f0743eb67de76d520cde0892e6dc) | Add descriptions to executable documents 2025 Update (#1170) | Stephen Spalding Ivan Goncharov Glen Lee Byron |\n| [17e2a47](https://github.com/graphql/graphql-spec/commit/17e2a4739c2189b653de3f7c721bf1fad7ac721a) | Replace `ExecuteSelectionSet` with `ExecuteCollectedFields` (#1039) | Benjie Yaacov Rydzinski Lee Byron |\n| [e71805e](https://github.com/graphql/graphql-spec/commit/e71805e0745b61239824475fdfff8f0fd116b83f) | Fixed unclear wording in the validation section (#1096) | PascalSenn Benjie Lee Byron |\n| [ccf23e3](https://github.com/graphql/graphql-spec/commit/ccf23e304bc4314511cb0712b0787d2528783337) | Define Data Collections used in the spec (#1102) | Benjie Lee Byron |\n| [ac483bd](https://github.com/graphql/graphql-spec/commit/ac483bdda45b8fe09fabaa50940e4cdfa24a0372) | Add validation rule that operation types exist (#955) | Ben Kraft Benjie Gillam Shane Krueger |\n| [883c759](https://github.com/graphql/graphql-spec/commit/883c7592d88579fbd13070d5c17f25f621abb8d7) | Do not exclude schema keyword if schema has description (#1167) | Benjie |\n| [df9f4f8](https://github.com/graphql/graphql-spec/commit/df9f4f8330109e1aca06af27b78ac1055a27e3a0) | Define \"execution result\" and \"request error result\" (#1159) | Rob Richard Benjie |\n| [9d0710e](https://github.com/graphql/graphql-spec/commit/9d0710e050f10c1ff5d0c659ec289713a6ebe8b9) | Add Appendix C - Specified Type System Definitions (#1037) | Martin Bonnin Benjie Lee Byron |\n| [a44d4ec](https://github.com/graphql/graphql-spec/commit/a44d4ec24e4c1263ab984a201cf9207c5a4dd549) | [RFC] Prevent @skip and @include on root subscription selection set (#860) | Benjie |\n| [3b0d8e6](https://github.com/graphql/graphql-spec/commit/3b0d8e606609b196d9ae643f4e0f0707700d46cc) | Add 'Assert' consistency to algorithm format check (#1168) | Benjie |\n| [646f937](https://github.com/graphql/graphql-spec/commit/646f937c5cf005fec43a4a3749e0c5b5406cb601) | make `includeDeprecated` non nullable (#1142) | Martin Bonnin |\n| [73d8b26](https://github.com/graphql/graphql-spec/commit/73d8b2624270b3cc22255125479ad10a7591f6d3) | Implementations may not deprecate a field that the interface hasn't deprecated (#1053) | Benjie Lee Byron |\n| [1f690d4](https://github.com/graphql/graphql-spec/commit/1f690d48149505c8a0fa94f2f9a525b69d876ace) | Clarify 'Values of Correct Type' rule relates to literals (#1118) | Benjie |\n| [a1884bb](https://github.com/graphql/graphql-spec/commit/a1884bb9386b6105ff81ad628a08b57e1237ccd5) | 3.13 Directive validation edits (#1089) | James Bellenger Benjie |\n| [c855454](https://github.com/graphql/graphql-spec/commit/c855454d518ecd7fd2eaf8e7d696f0c94104709a) | 3.10 Input Objects - clarify lists are permitted as Input fields (#1068) | Mike Solomon Benjie |\n| [586cbed](https://github.com/graphql/graphql-spec/commit/586cbedc4e38d27512965bd641a0588658dd6d99) | Add 'extensions' to request (#976) | Benjie Lee Byron |\n| [4390617](https://github.com/graphql/graphql-spec/commit/43906173238470b76173948053bfcb2a2bfc2e99) | Consistently use 'response name' not 'response key' (#1147) | Benjie Lee Byron |\n| [521ef5b](https://github.com/graphql/graphql-spec/commit/521ef5b200e61db7edc6c72dd4619af15eaa872a) | Rename field error to execution error; define response position (#1152) | Benjie Lee Byron |\n| [4abd86e](https://github.com/graphql/graphql-spec/commit/4abd86e33c70bd880e6f5605422c59343f3aa30c) | Consistently use result map when referring to objectTypes selection set result (#1148) | Rob Richard |\n| [0ab3d4b](https://github.com/graphql/graphql-spec/commit/0ab3d4b80103beb265777f95d202312a7dd7d63d) | Ensure algorithm steps are always wrapped in braces (#1146) | Benjie |\n| [b7c57ea](https://github.com/graphql/graphql-spec/commit/b7c57ea7f218474701c52fd9d1ee383600414343) | Fix choice of language used in algorithm (#1134) | Benjie |\n| [b41339a](https://github.com/graphql/graphql-spec/commit/b41339a0fd22fb3ca9a1a6110334a7094f1f7643) | Editorial: Add response stream to Response Section (#1135) | Rob Richard |\n| [a1c025f](https://github.com/graphql/graphql-spec/commit/a1c025f3b2d9c69ad208dfc5a28639746c60ee09) | Field merging validation: clarify pair members are distinct (#1136) | Andreas Marek |\n| [e9ac8c8](https://github.com/graphql/graphql-spec/commit/e9ac8c8ce46fda6759a29adc61949b9b9356344a) | Editorial: move \"Path\" to it's own section (#1129) | Rob Richard Benjie |\n| [2073bc8](https://github.com/graphql/graphql-spec/commit/2073bc888d92692cd465db47cc544109db9c4181) | Change 'original' to 'previous' to clarify multiple extensions (#1123) | Benjie |\n| [5bf400e](https://github.com/graphql/graphql-spec/commit/5bf400e3b2867e6366fc27616b777ccd3388bbfd) | \"data\" and \"errors\" appear in the \"response\", not the \"result\" (#1130) | Benjie |\n| [c37a4a4](https://github.com/graphql/graphql-spec/commit/c37a4a400e2ff61ade66c1c5947e0845a6b85c9f) | Editorial changes for Event Streams (#1099) | Lee Byron |\n| [34730e8](https://github.com/graphql/graphql-spec/commit/34730e86a151643f51106ac1a1f35985d3da8caa) | Make the reason argument in `@deprecated` non-nullable (#1040) | Martin Bonnin |\n| [df1acea](https://github.com/graphql/graphql-spec/commit/df1acea882d28df22184a7c12449864b239b9dd7) | Fix coercion table for list (#1057) | Benjie |\n| [7073e3a](https://github.com/graphql/graphql-spec/commit/7073e3a096c0a3fea9e605079a885d988a59d79f) | enhance(ResolveFieldValue): note that list items may be async (#1066) | Yaacov Rydzinski |\n| [e5bddd9](https://github.com/graphql/graphql-spec/commit/e5bddd9c31fcd6796698e4fd059514a5a035bf20) | Fix punctuation in grammar rule (#1084) | Benjie |\n| [a80f9ff](https://github.com/graphql/graphql-spec/commit/a80f9ff13b7ef9957d93ebe09e2dc4f2c93aede4) | Consistently spell 'implementers' (#1087) | Benjie |\n| [497e333](https://github.com/graphql/graphql-spec/commit/497e333c35a29dbe1ab3d1f24c31a59789843fb6) | Fix reference mistake in subscription execution (#994) | Jan Melcher |\n| [7485a34](https://github.com/graphql/graphql-spec/commit/7485a342b1c5f0ba4dbbe270d1f6863f55f7180b) | Reformat the parts of an execution request (#1090) | Benjie |\n| [8076f1e](https://github.com/graphql/graphql-spec/commit/8076f1e32a305188b41a71c2fec382b72186b424) | chore: add clarifying note for composite and expand term (#1078) | Jovi De Croock Benjie |\n| [b5ecff0](https://github.com/graphql/graphql-spec/commit/b5ecff0b7dfd1ebe8bb8a3de7e9180b93da73c53) | Add definition of \"selection set\" and clarify serial execution examples (#1032) | Benjie |\n| [32d24f6](https://github.com/graphql/graphql-spec/commit/32d24f6fda912253d395639561a88deae0863a8e) | Be strict about error paths format (#1073) | Martin Bonnin Benjie |\n| [4ab71e3](https://github.com/graphql/graphql-spec/commit/4ab71e330a41742d0b169be94d42055fad26b130) | Add missing . (#1088) | Benjie |\n| [a5da8bb](https://github.com/graphql/graphql-spec/commit/a5da8bb39e3ae44e38e7744e0b7bcb2dba453f97) | ID must always serialize as String would (#1086) | Benjie |\n| [0ba7cdf](https://github.com/graphql/graphql-spec/commit/0ba7cdf781125779498df3b45a5b97a697a439ba) | Enforce consistent punctuation in algorithms (#1069) | Benjie |\n| [8682a86](https://github.com/graphql/graphql-spec/commit/8682a86cd66cdc6d054c678a3f3ef7a32457e5fc) | Fix 'response error' -> 'request error' (#1016) | Benjie |\n| [feac5a5](https://github.com/graphql/graphql-spec/commit/feac5a54c6a95c1d4f7804bfaeb268c8bd206f2c) | Fix punctuation in some algorithms (#1067) | Yaacov Rydzinski |\n| [56d6107](https://github.com/graphql/graphql-spec/commit/56d61073137caac3dbea6ec8c3652cc3c8b90d86) | Fix heading level for Required Arguments validation rule (#1055) | Renée |\n| [3adfcca](https://github.com/graphql/graphql-spec/commit/3adfcca73644234fbbbb062a5cec9e7703419a9f) | Add explicit definition for BlockString (#1042) | Benjie |\n| [6b7c2c4](https://github.com/graphql/graphql-spec/commit/6b7c2c45d7136f7fa727cd64b994d2573d4e8014) | Remove \"subscriptions is a significant change\" sentence (#983) | Roman Ivantsov Benjie Roman Ivantsov |\n| [a5cc6ea](https://github.com/graphql/graphql-spec/commit/a5cc6ea0c9f3850f58ef1947d8eda8c6e593b95a) | Clarify that selection sets cannot be empty (#1025) | Benjie |\n| [afc0a35](https://github.com/graphql/graphql-spec/commit/afc0a35d271ba9502c3c68aeda6e6c6fbc223774) | Add links to contributed custom scalar specs at scalars.graphql.org (#1009) | dondonz <13839920+dondonz@users.noreply.github.com> Benjie |\n| [4e93488](https://github.com/graphql/graphql-spec/commit/4e93488096479c3fcfcc905126c8d157ad2e8c4c) | Fix ambiguity around when schema definition may be omitted (#987) | Benjie Lee Byron |\n| [12b7ad7](https://github.com/graphql/graphql-spec/commit/12b7ad7f0fe6ac3996fd5a2bc564357cd2dcb0bc) | add explanation about argument name uniqueness. (#891) | dugenkui Benjie Gillam |\n| [559063c](https://github.com/graphql/graphql-spec/commit/559063cb37c14ed74050f73efd3971ee13ff134d) | Change 'server' to 'service' (#1005) | Benjie |\n| [cbb8354](https://github.com/graphql/graphql-spec/commit/cbb83545cf8eeb5106856dda8f9d0b750f553124) | Fix broken license link (#1007) | Lee Byron |\n| [e736f78](https://github.com/graphql/graphql-spec/commit/e736f78b3cb5c8abb1d6b2ec5e5102de455f98ed) | Add a style guide to the specification (#1003) | Benjie |\n| [193fba3](https://github.com/graphql/graphql-spec/commit/193fba3912a43a5e2c9741f4269d279a018e2829) | field merging - field TYPES must not differ (#979) | Roman Ivantsov Roman Ivantsov Benjie Lee Byron |\n| [3d03cab](https://github.com/graphql/graphql-spec/commit/3d03cab7a8ffc455387f486fbab5155c2a7c7f3e) | P30: Fixed the explanatory text for algorithm checking uniqueness of non-repeatable directives (#975) | Roman Ivantsov Roman Ivantsov Lee Byron |\n| [342b838](https://github.com/graphql/graphql-spec/commit/342b8381ee0ebd25071697e2cc7e784d539700c7) | P34: implementing field type is either exact match or of covariant type (#974) | Roman Ivantsov Roman Ivantsov Lee Byron |\n| [ab865f9](https://github.com/graphql/graphql-spec/commit/ab865f95c000b48bdbe9134c4e53573f1996a5c1) | Provide explicit ref to Value Completion section (#982) | Roman Ivantsov Benjie Gillam Roman Ivantsov |\n| [edda836](https://github.com/graphql/graphql-spec/commit/edda83613a999c562afbfec6fba2accb96f058a4) | Changed 'must NOT BE' to 'must not be' (#980) | Roman Ivantsov Roman Ivantsov |\n| [3aa021f](https://github.com/graphql/graphql-spec/commit/3aa021fb3651710508a37e13c71b7268189982f9) | separate out IsSubType from IsValidImplementationFieldType (#977) | Yaacov Rydzinski |\n| [47a6bfd](https://github.com/graphql/graphql-spec/commit/47a6bfdba35ad9b96cba501a52593d3f04c8c5e9) | Editorial: Clarify intro for inline fragments (#969) | Lee Byron |\n| [3885a64](https://github.com/graphql/graphql-spec/commit/3885a64f3dc0f9cb64b43aaf1f77e661d98f4dca) | Editorial: Error Terminology (#966) | Lee Byron Roman Ivantsov Benjie Gillam |\n| [9a96fc4](https://github.com/graphql/graphql-spec/commit/9a96fc40f2307af15eecc3a257f85ec49adf50d9) | Editorial: Clarity about subject being a GraphQL service or system (#965) | Lee Byron Roman Ivantsov |\n| [57bd86d](https://github.com/graphql/graphql-spec/commit/57bd86d779482e9167d2113a9ba926e2ecb74dcc) | Editorial: Fix reference to object in interface introspection (#964) | Lee Byron Roman Ivantsov |\n| [299ce69](https://github.com/graphql/graphql-spec/commit/299ce69388aa7fb0012246e377950cf3fd41439d) | Editorial: Remove inaccurate statement about line terminator within tokens (#963) | Lee Byron Roman Ivantsov |\n| [1b8fe7a](https://github.com/graphql/graphql-spec/commit/1b8fe7a68f3552a614ab467ea1313947e9f7b1fc) | Leaf field selections clarification (#958) | Benjie Gillam Roman Ivantsov Lee Byron |\n| [a91e158](https://github.com/graphql/graphql-spec/commit/a91e15832682931585b8dad46fc8996df1d29735) | Light editorial around delivery agnostic subscriptions (#959) | Benjie Gillam Roman Ivantsov |\n| [bb95060](https://github.com/graphql/graphql-spec/commit/bb950608a161af5fc255835bcce10bc160ae1bc8) | Move punctuation outside quotation marks (#962) | Benedikt Franke |\n| [4de8782](https://github.com/graphql/graphql-spec/commit/4de87822d2bc807b746c6a37f6a99bb54d705185) | Clarify query shorthand relationship with directives (#873) | Benjie Gillam Lee Byron |\n| [94f73f4](https://github.com/graphql/graphql-spec/commit/94f73f48c12a6bdafa9dc729a89482aa7917303f) | Allow deprecation of input values (field args, directive args, input fields) (#805) | Ivan Goncharov Kevin Smithson Lee Byron Ivan Maximov Stephen Spalding |\n| [6b69577](https://github.com/graphql/graphql-spec/commit/6b69577b6e854099ce2595849e0b887c13fe300c) | use `findDog` query from example schema only after defining it (#927) | Thomas Heyenbrock |\n| [7dd73e7](https://github.com/graphql/graphql-spec/commit/7dd73e7607665bc84dbac504ae83058c996cffcf) | Define request, note it is transport independent (#949) | Benjie Gillam |\n| [84ec339](https://github.com/graphql/graphql-spec/commit/84ec33914393bb46e49e5d7a7fb05e0626daa7a8) | RFC: Allow full unicode range (#849) | Lee Byron Andreas Marek |\n| [00b88f0](https://github.com/graphql/graphql-spec/commit/00b88f05c4ae049f649e163a4914c94e58a784bf) | Fix formatting | Lee Byron |\n| [a61e35d](https://github.com/graphql/graphql-spec/commit/a61e35d301229c494b8bbd69ab0140b33884a95a) | consistent indentation and punctuation (#925) | Thomas Heyenbrock |\n| [266fcca](https://github.com/graphql/graphql-spec/commit/266fcca386518d4b05ed58f2d8f57f1fdaaad7f1) | Rename VariableDefinitions to VariablesDefinition (#916) | Ivan Maximov |\n| [7908822](https://github.com/graphql/graphql-spec/commit/7908822d4cbae5ad7136437ca577e8bc56f7efab) | Format the spec with prettier (#727) | Benjie Gillam |\n| [c18590c](https://github.com/graphql/graphql-spec/commit/c18590c477d6817d73e19b6c248c9fcc62b03017) | Fix typo in Type System section (#905) | Benoit Lubek |\n| [60323c9](https://github.com/graphql/graphql-spec/commit/60323c90dc2699266be7da7f0d4ab293953cd733) | fix typo (#896) | Alex Reilly |\n| [357bb72](https://github.com/graphql/graphql-spec/commit/357bb727b5a9dc5b1ed132cc4ffa27c309fb8258) | Start next working draft | Lee Byron |\n\nGenerated with:\n\n```sh\ngit log October2021..f29fbcd2ab5af763fce7ad62896eb62465a669b3 --format=\"| [%h](https://github.com/graphql/graphql-spec/commit/%H) | %s | %an <%ae> %(trailers:key=Co-authored-by,valueonly,separator=%x20)\" -- spec\n```\n\n## Diff\n\n[Github: diff from last spec cut](https://github.com/graphql/graphql-spec/compare/October2021...f29fbcd2ab5af763fce7ad62896eb62465a669b3?w=1)\n" }, { "path": "cspell.yml", "content": "language: en-US\nignoreRegExpList:\n # Posessives\n - /[a-z]{2,}'s/\nwords:\n # Terms of art\n - endianness\n - interoperation\n - monospace\n - openwebfoundation\n - parallelization\n - structs\n - subselection\n # Fictional characters / examples\n - alderaan\n - hagrid\n - leia\n - newhope\n - othername\n - skywalker\n - tatooine\n - zuck\n - zuckerberg\n - brontie\n - oneOf\n# Forbid Alternative spellings\nflagWords:\n - implementor\n - implementors\n" }, { "path": "package.json", "content": "{\n \"name\": \"graphql-spec\",\n \"private\": true,\n \"contributors\": [\n \"Lee Byron (http://leebyron.com/)\",\n \"Nicholas Schrock \",\n \"Daniel Schafer \"\n ],\n \"license\": \"OWFa-1.0\",\n \"homepage\": \"https://spec.graphql.org/\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"http://github.com/graphql/graphql-spec.git\"\n },\n \"scripts\": {\n \"test\": \"npm run test:spelling && npm run test:format && npm run test:build\",\n \"test:spelling\": \"cspell \\\"spec/**/*.md\\\" README.md LICENSE.md\",\n \"format\": \"prettier --write \\\"**/*.{md,yml,yaml,json}\\\"\",\n \"test:format\": \"prettier --check \\\"**/*.{md,yml,yaml,json}\\\" || npm run suggest:format\",\n \"test:algorithm-format\": \"node .github/algorithm-format-check.mjs\",\n \"suggest:format\": \"echo \\\"\\nTo resolve this, run: $(tput bold)npm run format$(tput sgr0)\\\" && exit 1\",\n \"build\": \"./build.sh\",\n \"test:build\": \"spec-md --metadata spec/metadata.json spec/GraphQL.md > /dev/null\",\n \"watch\": \"nodemon -e json,md --exec \\\"npm run build\\\"\",\n \"update-appendix-specified-definitions\": \"node scripts/update-appendix-specified-definitions.mjs; prettier --write \\\"spec/Appendix D -- Specified Definitions.md\\\"\"\n },\n \"devDependencies\": {\n \"cspell\": \"5.9.1\",\n \"nodemon\": \"2.0.20\",\n \"prettier\": \"2.8.2\",\n \"spec-md\": \"3.1.0\",\n \"graphql\": \"^17.0.0-alpha.9\"\n },\n \"prettier\": {\n \"proseWrap\": \"always\",\n \"trailingComma\": \"none\"\n }\n}\n" }, { "path": "scripts/generate-contributor-list.mjs", "content": "import { execFileSync } from \"node:child_process\";\nimport https from \"node:https\";\n\n// ---------- flags / utils\nconst RAW_ARGS = process.argv.slice(2);\nconst DEBUG = RAW_ARGS.includes(\"--debug\");\nconst logd = (...xs) => { if (DEBUG) console.error(...xs) };\n\nconst collator = new Intl.Collator(\"en\", { sensitivity: \"base\" });\nconst cmp = (a, b) => collator.compare(a, b);\nconst sleep = (ms) => new Promise((r) => setTimeout(r, ms));\nconst toLower = (s) => (s || \"\").toLowerCase();\nfunction die(msg, code = 1) { console.error(msg); process.exit(code) }\n\nfunction normalizeName(s) {\n return (s || \"\")\n .normalize(\"NFKD\")\n .replace(/\\p{Diacritic}/gu, \"\")\n .replace(/\\s+/g, \" \")\n .trim()\n .toLowerCase();\n}\nfunction pickBetterName(current, candidate) {\n if (!current) return (candidate || \"\").trim();\n const c = current.trim();\n const d = (candidate || \"\").trim();\n if (!c && d) return d;\n const spaceC = /\\s/.test(c), spaceD = /\\s/.test(d);\n if (spaceD && !spaceC) return d;\n if (d.length > c.length) return d;\n return c;\n}\nfunction sanitizeDisplayName(raw, fallback) {\n const s = (raw || \"\").trim();\n if (!s) return fallback;\n if (/moved\\s+to\\s+@/i.test(s)) return fallback;\n if (/@/.test(s)) return fallback;\n if (/^\\s*[-–—]+\\s*$/.test(s)) return fallback;\n return s;\n}\n\nfunction parseArgs() {\n const args = RAW_ARGS.filter(x => x !== \"--debug\");\n if (args.length === 0) die(\"Usage: node scripts/generate-contributor-list.mjs [-- ] [--debug]\");\n const dd = args.indexOf(\"--\");\n return { range: args[0], paths: dd === -1 ? [] : args.slice(dd + 1) };\n}\n\nfunction execGit(argv, opts = {}) {\n try {\n return execFileSync(\"git\", argv, { encoding: \"utf8\", maxBuffer: 1024 * 1024 * 400, ...opts });\n } catch (e) {\n die(`git ${argv.join(\" \")} failed: ${e.message}`);\n }\n}\nfunction repoNameWithOwner() {\n let url = \"\";\n try { url = execGit([\"remote\", \"get-url\", \"origin\"]).trim(); } catch { }\n const m = url.match(/github\\.com[:/](?[^/]+)\\/(?[^/]+?)(?:\\.git)?$/i);\n if (m?.groups) return `${m.groups.owner}/${m.groups.repo}`;\n die(\"Could not determine GitHub repo from 'origin' remote.\");\n}\nfunction revList(range, paths) {\n const args = [\"rev-list\", range];\n if (paths.length) args.push(\"--\", ...paths);\n const out = execGit(args);\n return out.split(/\\r?\\n/).filter(Boolean);\n}\nfunction parseCoAuthorLines(message) {\n const out = [];\n const re = /^[ \\t]*Co-authored-by:\\s*(.+?)\\s*<([^>]+)>/gim;\n let m;\n while ((m = re.exec(message))) out.push({ name: m[1].trim(), email: m[2].trim() });\n return out;\n}\nfunction loginFromNoreply(email) {\n const m = email.toLowerCase().match(/^(?:\\d+\\+)?([a-z0-9-]+)@users\\.noreply\\.github\\.com$/i);\n return m ? m[1] : \"\";\n}\nfunction candidateHandlesFromEmailAndName(email, name) {\n const cands = new Set();\n const local = email.split(\"@\")[0];\n const bare = local.replace(/[._]/g, \"\");\n const bareNoDigits = bare.replace(/\\d+$/, \"\");\n cands.add(bare); cands.add(bareNoDigits);\n const parts = local.split(/[._-]+/).filter(Boolean);\n if (parts.length >= 2) {\n const first = parts[0], last = parts[parts.length - 1];\n cands.add(`${first}${last}`);\n cands.add(`${first}-${last}`);\n cands.add(`${first}_${last}`);\n cands.add(`${first[0]}${last}`);\n if (last.length >= 3) cands.add(`${first}${last.slice(0, 3)}`);\n }\n const nameParts = name.split(/\\s+/).filter(Boolean);\n if (nameParts.length >= 2) {\n const f = nameParts[0].replace(/[^A-Za-z0-9-]/g, \"\");\n const l = nameParts[nameParts.length - 1].replace(/[^A-Za-z0-9-]/g, \"\");\n if (f && l) {\n cands.add(`${f}${l}`);\n cands.add(`${f}-${l}`);\n cands.add(`${f[0]}${l}`);\n }\n }\n const q = name.match(/'([^']{1,39})'/); if (q) cands.add(q[1]);\n const p = name.match(/\\(([^) ]{1,39})\\)/); if (p) cands.add(p[1]);\n return Array.from(cands).filter(s => /^[A-Za-z0-9-]{2,39}$/.test(s));\n}\n\n// ---------- GraphQL\nconst REPO = repoNameWithOwner();\nconst [OWNER, NAME] = REPO.split(\"/\");\nfunction getToken() {\n const env = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || \"\";\n if (env) return env;\n try { return execFileSync(\"gh\", [\"auth\", \"token\"], { encoding: \"utf8\" }).trim(); } catch { return \"\"; }\n}\nconst TOKEN = getToken();\nif (!TOKEN) console.error(\"Warning: no GITHUB_TOKEN/GH_TOKEN (or gh auth token). Resolution will be limited.\");\n\nasync function graphql(query, variables) {\n const body = JSON.stringify(variables ? { query, variables } : { query });\n const options = {\n hostname: \"api.github.com\",\n path: \"/graphql\",\n method: \"POST\",\n headers: {\n \"User-Agent\": \"contributors-table-graphql\",\n \"Authorization\": `Bearer ${TOKEN}`,\n \"Content-Type\": \"application/json\",\n \"Content-Length\": Buffer.byteLength(body),\n },\n };\n return await new Promise((resolve) => {\n const req = https.request(options, (res) => {\n let data = \"\";\n res.setEncoding(\"utf8\");\n res.on(\"data\", (c) => (data += c));\n res.on(\"end\", () => {\n try {\n const json = JSON.parse(data || \"{}\");\n if (json.errors && DEBUG) console.error(\"GraphQL errors:\", JSON.stringify(json.errors, null, 2));\n resolve(json);\n } catch { resolve({}); }\n });\n });\n req.on(\"error\", () => resolve({}));\n req.write(body);\n req.end();\n });\n}\n\n// Batch fetch commit author + message for SHAs; count primary-author occurrences per login\nasync function fetchCommitsByOidBatch(oids) {\n const out = new Map(); // oid -> { login | \"\", name, email, message }\n const authorCount = new Map(); // login -> # of primary authored commits in range\n const chunkSize = 40;\n for (let i = 0; i < oids.length; i += chunkSize) {\n const chunk = oids.slice(i, i + chunkSize);\n const fields = chunk.map((oid, idx) => `\n c${idx}: object(oid: \"${oid}\") {\n ... on Commit {\n message\n author { user { login } name email }\n }\n }`).join(\"\\n\");\n const q = `query($owner:String!, $name:String!) { repository(owner:$owner, name:$name) { ${fields} } }`;\n const res = await graphql(q, { owner: OWNER, name: NAME });\n const repo = res?.data?.repository || {};\n for (let idx = 0; idx < chunk.length; idx++) {\n const node = repo[`c${idx}`];\n if (!node) continue;\n const info = {\n login: node?.author?.user?.login || \"\",\n name: node?.author?.name || \"\",\n email: node?.author?.email || \"\",\n message: node?.message || \"\",\n };\n out.set(chunk[idx], info);\n const L = info.login;\n if (L) authorCount.set(L, (authorCount.get(L) || 0) + 1);\n }\n }\n return { commitInfo: out, authorCount };\n}\n\n// GraphQL user search helpers (users only)\nasync function searchUsersByNameExact(name) {\n if (!TOKEN) return \"\";\n const queryStr = `\"${name.replace(/\"/g, '\\\\\"')}\" in:name type:user`;\n const q = `query($q:String!){ search(type: USER, query: $q, first: 25) { nodes { ... on User { login name } } } }`;\n const r = await graphql(q, { q: queryStr });\n const nodes = r?.data?.search?.nodes ?? [];\n const target = normalizeName(name);\n for (const it of nodes) {\n if (!it?.login) continue;\n if (normalizeName(it.name || \"\") === target) return it.login;\n }\n return \"\";\n}\nasync function searchUsersByLoginToken(token) {\n if (!TOKEN) return \"\";\n const q = `query($q:String!){ search(type: USER, query: $q, first: 5) { nodes { ... on User { login name } } } }`;\n const r = await graphql(q, { q: `${token} in:login type:user` });\n const items = r?.data?.search?.nodes ?? [];\n if (items.length === 1) return items[0]?.login || \"\";\n return \"\";\n}\nasync function fetchProfileNames(logins) {\n const out = new Map();\n const chunkSize = 40;\n for (let i = 0; i < logins.length; i += chunkSize) {\n const chunk = logins.slice(i, i + chunkSize);\n const fields = chunk.map((login, idx) => `u${idx}: user(login: \"${login}\") { login name }`).join(\"\\n\");\n const q = `query { ${fields} }`;\n const r = await graphql(q);\n const data = r?.data || {};\n for (let idx = 0; idx < chunk.length; idx++) {\n const u = data[`u${idx}`];\n out.set(chunk[idx], (u?.name || \"\").trim());\n }\n }\n return out;\n}\n\n// ---------- main\nasync function main() {\n const { range, paths } = parseArgs();\n\n const shas = revList(range, paths);\n if (!shas.length) die(\"No commits in the specified range/path.\");\n\n // 1) Commit info + primary author counts\n const { commitInfo, authorCount } = await fetchCommitsByOidBatch(shas);\n\n // 2) Collect authors and co-authors\n const loginBestName = new Map(); // login -> name hint\n const pool = []; // [{ name, email }] to resolve (co-authors + primaries with missing login)\n\n for (const sha of shas) {\n const info = commitInfo.get(sha);\n if (!info) continue;\n const { login, name, email, message } = info;\n\n if (login) {\n loginBestName.set(login, pickBetterName(loginBestName.get(login) || \"\", name));\n } else {\n const guess = loginFromNoreply(email);\n if (guess) loginBestName.set(guess, pickBetterName(loginBestName.get(guess) || \"\", name));\n else pool.push({ name, email });\n }\n for (const ca of parseCoAuthorLines(message)) pool.push(ca);\n }\n\n // 3) Resolve pool (GraphQL users search only)\n const emailToLogin = new Map(); // emailLower -> login\n const concurrency = 8;\n let idx = 0;\n\n async function worker() {\n while (idx < pool.length) {\n const i = idx++;\n const { name, email } = pool[i];\n const ekey = toLower(email);\n if (emailToLogin.has(ekey)) continue;\n\n let login = loginFromNoreply(email);\n if (!login) login = await searchUsersByNameExact(name);\n if (!login) {\n const cands = candidateHandlesFromEmailAndName(email, name);\n for (const cand of cands) {\n const solo = await searchUsersByLoginToken(cand);\n if (solo) { login = solo; break; }\n }\n }\n if (!login && DEBUG) logd(`Unresolved: \"${name}\" <${email}>`);\n emailToLogin.set(ekey, login || \"\");\n if (login) loginBestName.set(login, pickBetterName(loginBestName.get(login) || \"\", name));\n\n if (i % 10 === 0) await sleep(60);\n }\n }\n await Promise.all(Array.from({ length: concurrency }, worker));\n\n // 4) Build candidate rows (resolved only), fetch profile names\n const resolvedLogins = Array.from(loginBestName.keys());\n const profileNames = await fetchProfileNames(resolvedLogins);\n\n const candidates = resolvedLogins.map(login => {\n const prof = (profileNames.get(login) || \"\").trim();\n const hint = (loginBestName.get(login) || \"\").trim();\n const display = sanitizeDisplayName(prof || hint || login, prof || login);\n return { login, display, authorCommits: authorCount.get(login) || 0 };\n });\n\n // 5) Collapse duplicate people with the same display name\n const byDisplay = new Map(); // normName -> best candidate\n const score = (x) => (x.authorCommits > 0 ? 2 : 0) + (x.display.toLowerCase() !== x.login.toLowerCase() ? 1 : 0);\n for (const c of candidates) {\n const key = normalizeName(c.display);\n if (!byDisplay.has(key)) { byDisplay.set(key, c); continue; }\n const cur = byDisplay.get(key);\n if (score(c) > score(cur) || (score(c) === score(cur) && c.login.toLowerCase() < cur.login.toLowerCase())) {\n if (DEBUG) logd(`Collapsed duplicate \"${c.display}\": keeping ${c.login} over ${cur.login}`);\n byDisplay.set(key, c);\n }\n }\n const resolvedRows = Array.from(byDisplay.values())\n .filter((v, i, arr) => arr.findIndex(x => x.login.toLowerCase() === v.login.toLowerCase()) === i)\n .map(({ display, login }) => ({ name: display, gh: `[@${login}](https://github.com/${login})`, login }));\n\n // 6) Unmatched → show email (dedupe by name+email)\n const unmatched = [];\n const seenUnk = new Set();\n for (const { name, email } of pool) {\n const login = emailToLogin.get(toLower(email));\n if (login) continue;\n const nm = sanitizeDisplayName(name || \"(Unknown)\", name || \"(Unknown)\");\n const key = normalizeName(nm) + \"|\" + email.toLowerCase();\n if (seenUnk.has(key)) continue;\n seenUnk.add(key);\n unmatched.push({ name: nm, gh: email, login: \"\" });\n }\n\n // 7) Merge, sort, output\n const allRows = [...resolvedRows, ...unmatched];\n allRows.sort((a, b) => cmp(a.name, b.name));\n\n console.log(\"| Author | Github\");\n console.log(\"| ----------------------------- | ---------------------------------\");\n for (const r of allRows) {\n console.log(`| ${r.name} | ${r.gh}`);\n }\n}\n\nmain().catch((e) => die(String(e)));\n" }, { "path": "scripts/update-appendix-specified-definitions.mjs", "content": "import prettier from \"prettier\";\nimport { writeFile } from \"node:fs/promises\";\nimport {\n printIntrospectionSchema,\n buildSchema,\n specifiedScalarTypes,\n printType,\n parse,\n print,\n visit,\n Kind\n} from \"graphql\";\n\nfunction stripDescriptions(sdl) {\n const ast = parse(sdl);\n const noDescAst = visit(ast, {\n enter: (node) => {\n // Not in spec yet\n if (node.name?.value === \"FRAGMENT_VARIABLE_DEFINITION\") {\n return null\n }\n },\n leave: (node) => ({ ...node, description: undefined })\n });\n return print(noDescAst);\n}\n\nfunction printSpecifiedScalars() {\n return specifiedScalarTypes\n .map((type) => stripDescriptions(printType(type)))\n .join(\"\\n\\n\");\n}\n\nconst introspectionSchema = stripDescriptions(\n printIntrospectionSchema(buildSchema(`type Query { i: Int }`))\n);\n\nconst allSpecifiedTypesSDL = prettier\n .format(printSpecifiedScalars() + \"\\n\\n\" + introspectionSchema, {\n parser: \"graphql\"\n })\n .trimEnd();\n\nawait writeFile(\n \"./spec/Appendix D -- Specified Definitions.md\",\n `# D. Appendix: Type System Definitions\n\nThis appendix lists all type system definitions specified in this document.\n\nThe order of types, fields, arguments, values and directives is non-normative.\n\n\\`\\`\\`graphql\n${allSpecifiedTypesSDL}\n\\`\\`\\`\n`\n);\n" }, { "path": "signed-agreements/README.md", "content": "# Legacy Signed Agreements\n\nThe signed agreement found in this directory was contributed when this\nspecification was licensed under OWFa 1.0 on September 26, 2017 by Facebook.\n\nSince then the [GraphQL Foundation](https://graphql.org/foundation/) was formed\nin 2019, at which point the GraphQL Specification Project became a\n[Joint Development Foundation](https://www.jointdevelopment.org/) project.\n\nThe charter and legal documents currently governing this specification and other\nGraphQL projects can be found in the\n[GraphQL Foundation repository](https://github.com/graphql/foundation).\n" }, { "path": "spec/Appendix A -- Conformance.md", "content": "# A. Appendix: Conformance\n\nA conforming implementation of GraphQL must fulfill all normative requirements.\nConformance requirements are described in this document via both descriptive\nassertions and key words with clearly defined meanings.\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\",\n\"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in the normative portions of\nthis document are to be interpreted as described in\n[IETF RFC 2119](https://tools.ietf.org/html/rfc2119). These key words may appear\nin lowercase and still retain their meaning unless explicitly declared as\nnon-normative.\n\nA conforming implementation of GraphQL may provide additional functionality, but\nmust not do so where explicitly disallowed or where it would otherwise result in\nnon-conformance.\n\n**Conforming Algorithms**\n\nAlgorithm steps phrased in imperative grammar (e.g. \"Return the result of\ncalling resolver\") are to be interpreted with the same level of requirement as\nthe algorithm it is contained within. Any algorithm referenced within an\nalgorithm step (e.g. \"Let completedResult be the result of calling\nCompleteValue()\") is to be interpreted as having at least the same level of\nrequirement as the algorithm containing that step.\n\nConformance requirements expressed as algorithms and data collections can be\nfulfilled by an implementation of this specification in any way as long as the\nperceived result is equivalent. Algorithms described in this document are\nwritten to be easy to understand. Implementers are encouraged to include\nequivalent but optimized implementations.\n\nSee [Appendix A](#sec-Appendix-Notation-Conventions) for more details about the\ndefinition of algorithms, data collections, and other notational conventions\nused in this document.\n\n**Non-Normative Portions**\n\nAll contents of this document are normative except portions explicitly declared\nas non-normative.\n\nExamples in this document are non-normative, and are presented to aid\nunderstanding of introduced concepts and the behavior of normative portions of\nthe specification. Examples are either introduced explicitly in prose (e.g. \"for\nexample\") or are set apart in example or counterexample blocks, like this:\n\n```example\nThis is an example of a non-normative example.\n```\n\n```counter-example\nThis is an example of a non-normative counterexample.\n```\n\nNotes in this document are non-normative, and are presented to clarify intent,\ndraw attention to potential edge cases and pitfalls, and answer common questions\nthat arise during implementation. Notes are either introduced explicitly in\nprose (e.g. \"Note: \") or are set apart in a note block, like this:\n\nNote: This is an example of a non-normative note.\n" }, { "path": "spec/Appendix B -- Notation Conventions.md", "content": "# B. Appendix: Notation Conventions\n\nThis specification document contains a number of notation conventions used to\ndescribe technical concepts such as language grammar and semantics as well as\nruntime algorithms.\n\nThis appendix seeks to explain these notations in greater detail to avoid\nambiguity.\n\n## Context-Free Grammar\n\nA context-free grammar consists of a number of productions. Each production has\nan abstract symbol called a \"non-terminal\" as its left-hand side, and zero or\nmore possible sequences of non-terminal symbols and/or terminal characters as\nits right-hand side.\n\nStarting from a single goal non-terminal symbol, a context-free grammar\ndescribes a language: the set of possible sequences of characters that can be\ndescribed by repeatedly replacing any non-terminal in the goal sequence with one\nof the sequences it is defined by, until all non-terminal symbols have been\nreplaced by terminal characters.\n\nTerminals are represented in this document in a monospace font in two forms: a\nspecific Unicode character or sequence of Unicode characters (i.e. {`=`} or\n{`terminal`}), and prose typically describing a specific Unicode code point\n{\"Space (U+0020)\"}. Sequences of Unicode characters only appear in syntactic\ngrammars and represent a {Name} token of that specific sequence.\n\nNon-terminal production rules are represented in this document using the\nfollowing notation for a non-terminal with a single definition:\n\nNonTerminalWithSingleDefinition : NonTerminal `terminal`\n\nWhile using the following notation for a production with a list of definitions:\n\nNonTerminalWithManyDefinitions :\n\n- OtherNonTerminal `terminal`\n- `terminal`\n\nA definition may refer to itself, which describes repetitive sequences, for\nexample:\n\nListOfLetterA :\n\n- ListOfLetterA `a`\n- `a`\n\n## Lexical and Syntactic Grammar\n\nThe GraphQL language is defined in a syntactic grammar where terminal symbols\nare tokens. Tokens are defined in a lexical grammar which matches patterns of\nsource characters. The result of parsing a source text sequence of Unicode\ncharacters first produces a sequence of lexical tokens according to the lexical\ngrammar which then produces abstract syntax tree (AST) according to the\nsyntactic grammar.\n\nA lexical grammar production describes non-terminal \"tokens\" by patterns of\nterminal Unicode characters. No \"whitespace\" or other ignored characters may\nappear between any terminal Unicode characters in the lexical grammar\nproduction. A lexical grammar production is distinguished by a two colon `::`\ndefinition.\n\nWord :: Letter+\n\nA Syntactic grammar production describes non-terminal \"rules\" by patterns of\nterminal Tokens. {Whitespace} and other {Ignored} sequences may appear before or\nafter any terminal {Token}. A syntactic grammar production is distinguished by a\none colon `:` definition.\n\nSentence : Word+ `.`\n\n## Grammar Notation\n\nThis specification uses some additional notation to describe common patterns,\nsuch as optional or repeated patterns, or parameterized alterations of the\ndefinition of a non-terminal. This section explains these shorthand notations\nand their expanded definitions in the context-free grammar.\n\n**Constraints**\n\nA grammar production may specify that certain expansions are not permitted by\nusing the phrase \"but not\" and then indicating the expansions to be excluded.\n\nFor example, the following production means that the non-terminal {SafeWord} may\nbe replaced by any sequence of characters that could replace {Word} provided\nthat the same sequence of characters could not replace {SevenCarlinWords}.\n\nSafeWord : Word but not SevenCarlinWords\n\nA grammar may also list a number of restrictions after \"but not\" separated by\n\"or\".\n\nFor example:\n\nNonBooleanName : Name but not `true` or `false`\n\n**Lookahead Restrictions**\n\nA grammar production may specify that certain characters or tokens are not\npermitted to follow it by using the pattern {[lookahead != NotAllowed]}.\nLookahead restrictions are often used to remove ambiguity from the grammar.\n\nThe following example makes it clear that {Letter+} must be greedy, since {Word}\ncannot be followed by yet another {Letter}.\n\nWord :: Letter+ [lookahead != Letter]\n\n**Optionality and Lists**\n\nA subscript suffix \"{Symbol?}\" is shorthand for two possible sequences, one\nincluding that symbol and one excluding it.\n\nAs an example:\n\nSentence : Noun Verb Adverb?\n\nis shorthand for\n\nSentence :\n\n- Noun Verb Adverb\n- Noun Verb\n\nA subscript suffix \"{Symbol+}\" is shorthand for a list of one or more of that\nsymbol, represented as an additional recursive production.\n\nAs an example:\n\nBook : Cover Page+ Cover\n\nis shorthand for\n\nBook : Cover Page_list Cover\n\nPage_list :\n\n- Page_list Page\n- Page\n\n**Parameterized Grammar Productions**\n\nA symbol definition subscript suffix parameter in braces \"{Symbol[Param]}\" is\nshorthand for two symbol definitions, one appended with that parameter name, the\nother without. The same subscript suffix on a symbol is shorthand for that\nvariant of the definition. If the parameter starts with \"?\", that form of the\nsymbol is used if in a symbol definition with the same parameter. Some possible\nsequences can be included or excluded conditionally when respectively prefixed\nwith \"\\[+Param]\" and \"\\[~Param]\".\n\nAs an example:\n\nExample[Param] :\n\n- A\n- B[Param]\n- C[?Param]\n- [+Param] D\n- [~Param] E\n\nis shorthand for\n\nExample :\n\n- A\n- B_param\n- C\n- E\n\nExample_param :\n\n- A\n- B_param\n- C_param\n- D\n\n## Grammar Semantics\n\nThis specification describes the semantic value of many grammar productions in\nthe form of a list of algorithmic steps.\n\nFor example, this describes how a parser should interpret a string literal:\n\nStringValue :: `\"\"`\n\n- Return an empty Unicode character sequence.\n\nStringValue :: `\"` StringCharacter+ `\"`\n\n- Return the Unicode character sequence of all {StringCharacter} Unicode\n character values.\n\n## Algorithms\n\nThis specification describes some algorithms used by the static and runtime\nsemantics, they're defined in the form of a function-like syntax with the\nalgorithm's name and the arguments it accepts along with a list of algorithmic\nsteps to take in the order listed. Each step may establish references to other\nvalues, check various conditions, call other algorithms, and eventually return a\nvalue representing the outcome of the algorithm for the provided arguments.\n\nFor example, the following example describes an algorithm named {Fibonacci}\nwhich accepts a single argument {number}. The algorithm's steps produce the next\nnumber in the Fibonacci sequence:\n\nFibonacci(number):\n\n- If {number} is {0}:\n - Return {1}.\n- If {number} is {1}:\n - Return {2}.\n- Let {previousNumber} be {number} - {1}.\n- Let {previousPreviousNumber} be {number} - {2}.\n- Return {Fibonacci(previousNumber)} + {Fibonacci(previousPreviousNumber)}.\n\nNote: Algorithms described in this document are written to be easy to\nunderstand. Implementers are encouraged to include observably equivalent but\noptimized implementations.\n\n## Data Collections\n\nAlgorithms within this specification refer to abstract data collection types to\nexpress normative structural, uniqueness, and ordering requirements. Temporary\ndata collections internal to an algorithm use these types to best describe\nexpected behavior, but implementers are encouraged to provide observably\nequivalent but optimized implementations. Implementations may use any data\nstructure as long as the expected requirements are met.\n\n**List**\n\n:: A _list_ is an ordered collection of values which may contain duplicates. A\nvalue added to a list is ordered after existing values.\n\n**Set**\n\n:: A _set_ is a collection of values which must not contain duplicates.\n\n:: An _ordered set_ is a set which has a defined order. A value added to an\nordered set, which does not already contain that value, is ordered after\nexisting values.\n\n**Map**\n\n:: A _map_ is a collection of entries, each of which has a key and value. Each\nentry has a unique key, and can be directly referenced by that key.\n\n:: An _ordered map_ is a map which has a defined order. An entry added to an\nordered map, which does not have an entry with that key, is ordered after\nexisting entries.\n\nNote: This specification defines ordered data collection only when strictly\nrequired. When an order is observable, implementations should preserve it to\nimprove output legibility and stability. For example if applying a grammar to an\ninput string yields a _set_ of elements, serialization should emit those\nelements in the same source order.\n" }, { "path": "spec/Appendix C -- Grammar Summary.md", "content": "# C. Appendix: Grammar Summary\n\n## Source Text\n\nSourceCharacter :: \"Any Unicode scalar value\"\n\n## Ignored Tokens\n\nIgnored ::\n\n- UnicodeBOM\n- Whitespace\n- LineTerminator\n- Comment\n- Comma\n\nUnicodeBOM :: \"Byte Order Mark (U+FEFF)\"\n\nWhitespace ::\n\n- \"Horizontal Tab (U+0009)\"\n- \"Space (U+0020)\"\n\nLineTerminator ::\n\n- \"New Line (U+000A)\"\n- \"Carriage Return (U+000D)\" [lookahead != \"New Line (U+000A)\"]\n- \"Carriage Return (U+000D)\" \"New Line (U+000A)\"\n\nComment :: `#` CommentChar\\* [lookahead != CommentChar]\n\nCommentChar :: SourceCharacter but not LineTerminator\n\nComma :: ,\n\n## Lexical Tokens\n\nToken ::\n\n- Punctuator\n- Name\n- IntValue\n- FloatValue\n- StringValue\n\nPunctuator :: one of ! $ & ( ) ... : = @ [ ] { | }\n\nName ::\n\n- NameStart NameContinue\\* [lookahead != NameContinue]\n\nNameStart ::\n\n- Letter\n- `_`\n\nNameContinue ::\n\n- Letter\n- Digit\n- `_`\n\nLetter :: one of\n\n- `A` `B` `C` `D` `E` `F` `G` `H` `I` `J` `K` `L` `M`\n- `N` `O` `P` `Q` `R` `S` `T` `U` `V` `W` `X` `Y` `Z`\n- `a` `b` `c` `d` `e` `f` `g` `h` `i` `j` `k` `l` `m`\n- `n` `o` `p` `q` `r` `s` `t` `u` `v` `w` `x` `y` `z`\n\nDigit :: one of\n\n- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`\n\nIntValue :: IntegerPart [lookahead != {Digit, `.`, NameStart}]\n\nIntegerPart ::\n\n- NegativeSign? 0\n- NegativeSign? NonZeroDigit Digit\\*\n\nNegativeSign :: -\n\nNonZeroDigit :: Digit but not `0`\n\nFloatValue ::\n\n- IntegerPart FractionalPart ExponentPart [lookahead != {Digit, `.`, NameStart}]\n- IntegerPart FractionalPart [lookahead != {Digit, `.`, NameStart}]\n- IntegerPart ExponentPart [lookahead != {Digit, `.`, NameStart}]\n\nFractionalPart :: . Digit+\n\nExponentPart :: ExponentIndicator Sign? Digit+\n\nExponentIndicator :: one of `e` `E`\n\nSign :: one of + -\n\nStringValue ::\n\n- `\"\"` [lookahead != `\"`]\n- `\"` StringCharacter+ `\"`\n- BlockString\n\nStringCharacter ::\n\n- SourceCharacter but not `\"` or `\\` or LineTerminator\n- `\\u` EscapedUnicode\n- `\\` EscapedCharacter\n\nEscapedUnicode ::\n\n- `{` HexDigit+ `}`\n- HexDigit HexDigit HexDigit HexDigit\n\nHexDigit :: one of\n\n- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`\n- `A` `B` `C` `D` `E` `F`\n- `a` `b` `c` `d` `e` `f`\n\nEscapedCharacter :: one of `\"` `\\` `/` `b` `f` `n` `r` `t`\n\nBlockString :: `\"\"\"` BlockStringCharacter\\* `\"\"\"`\n\nBlockStringCharacter ::\n\n- SourceCharacter but not `\"\"\"` or `\\\"\"\"`\n- `\\\"\"\"`\n\nNote: Block string values are interpreted to exclude blank initial and trailing\nlines and uniform indentation with {BlockStringValue()}.\n\n## Document Syntax\n\nDescription : StringValue\n\nDocument : Definition+\n\nDefinition :\n\n- ExecutableDefinition\n- TypeSystemDefinitionOrExtension\n\nExecutableDocument : ExecutableDefinition+\n\nExecutableDefinition :\n\n- OperationDefinition\n- FragmentDefinition\n\nOperationDefinition :\n\n- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet\n- SelectionSet\n\nOperationType : one of `query` `mutation` `subscription`\n\nSelectionSet : { Selection+ }\n\nSelection :\n\n- Field\n- FragmentSpread\n- InlineFragment\n\nField : Alias? Name Arguments? Directives? SelectionSet?\n\nAlias : Name :\n\nArguments[Const] : ( Argument[?Const]+ )\n\nArgument[Const] : Name : Value[?Const]\n\nFragmentSpread : ... FragmentName Directives?\n\nInlineFragment : ... TypeCondition? Directives? SelectionSet\n\nFragmentDefinition : Description? fragment FragmentName TypeCondition\nDirectives? SelectionSet\n\nFragmentName : Name but not `on`\n\nTypeCondition : on NamedType\n\nValue[Const] :\n\n- [~Const] Variable\n- IntValue\n- FloatValue\n- StringValue\n- BooleanValue\n- NullValue\n- EnumValue\n- ListValue[?Const]\n- ObjectValue[?Const]\n\nBooleanValue : one of `true` `false`\n\nNullValue : `null`\n\nEnumValue : Name but not `true`, `false` or `null`\n\nListValue[Const] :\n\n- [ ]\n- [ Value[?Const]+ ]\n\nObjectValue[Const] :\n\n- { }\n- { ObjectField[?Const]+ }\n\nObjectField[Const] : Name : Value[?Const]\n\nVariablesDefinition : ( VariableDefinition+ )\n\nVariableDefinition : Description? Variable : Type DefaultValue?\nDirectives[Const]?\n\nVariable : $ Name\n\nDefaultValue : = Value[Const]\n\nType :\n\n- NamedType\n- ListType\n- NonNullType\n\nNamedType : Name\n\nListType : [ Type ]\n\nNonNullType :\n\n- NamedType !\n- ListType !\n\nDirectives[Const] : Directive[?Const]+\n\nDirective[Const] : @ Name Arguments[?Const]?\n\nTypeSystemDocument : TypeSystemDefinition+\n\nTypeSystemDefinition :\n\n- SchemaDefinition\n- TypeDefinition\n- DirectiveDefinition\n\nTypeSystemExtensionDocument : TypeSystemDefinitionOrExtension+\n\nTypeSystemDefinitionOrExtension :\n\n- TypeSystemDefinition\n- TypeSystemExtension\n\nTypeSystemExtension :\n\n- SchemaExtension\n- TypeExtension\n\nSchemaDefinition : Description? schema Directives[Const]? {\nRootOperationTypeDefinition+ }\n\nSchemaExtension :\n\n- extend schema Directives[Const]? { RootOperationTypeDefinition+ }\n- extend schema Directives[Const] [lookahead != `{`]\n\nRootOperationTypeDefinition : OperationType : NamedType\n\nTypeDefinition :\n\n- ScalarTypeDefinition\n- ObjectTypeDefinition\n- InterfaceTypeDefinition\n- UnionTypeDefinition\n- EnumTypeDefinition\n- InputObjectTypeDefinition\n\nTypeExtension :\n\n- ScalarTypeExtension\n- ObjectTypeExtension\n- InterfaceTypeExtension\n- UnionTypeExtension\n- EnumTypeExtension\n- InputObjectTypeExtension\n\nScalarTypeDefinition : Description? scalar Name Directives[Const]?\n\nScalarTypeExtension :\n\n- extend scalar Name Directives[Const]\n\nObjectTypeDefinition :\n\n- Description? type Name ImplementsInterfaces? Directives[Const]?\n FieldsDefinition\n- Description? type Name ImplementsInterfaces? Directives[Const]? [lookahead !=\n `{`]\n\nObjectTypeExtension :\n\n- extend type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition\n- extend type Name ImplementsInterfaces? Directives[Const] [lookahead != `{`]\n- extend type Name ImplementsInterfaces [lookahead != `{`]\n\nImplementsInterfaces :\n\n- ImplementsInterfaces & NamedType\n- implements `&`? NamedType\n\nFieldsDefinition : { FieldDefinition+ }\n\nFieldDefinition : Description? Name ArgumentsDefinition? : Type\nDirectives[Const]?\n\nArgumentsDefinition : ( InputValueDefinition+ )\n\nInputValueDefinition : Description? Name : Type DefaultValue? Directives[Const]?\n\nInterfaceTypeDefinition :\n\n- Description? interface Name ImplementsInterfaces? Directives[Const]?\n FieldsDefinition\n- Description? interface Name ImplementsInterfaces? Directives[Const]?\n [lookahead != `{`]\n\nInterfaceTypeExtension :\n\n- extend interface Name ImplementsInterfaces? Directives[Const]?\n FieldsDefinition\n- extend interface Name ImplementsInterfaces? Directives[Const] [lookahead !=\n `{`]\n- extend interface Name ImplementsInterfaces [lookahead != `{`]\n\nUnionTypeDefinition : Description? union Name Directives[Const]?\nUnionMemberTypes?\n\nUnionMemberTypes :\n\n- UnionMemberTypes | NamedType\n- = `|`? NamedType\n\nUnionTypeExtension :\n\n- extend union Name Directives[Const]? UnionMemberTypes\n- extend union Name Directives[Const]\n\nEnumTypeDefinition :\n\n- Description? enum Name Directives[Const]? EnumValuesDefinition\n- Description? enum Name Directives[Const]? [lookahead != `{`]\n\nEnumValuesDefinition : { EnumValueDefinition+ }\n\nEnumValueDefinition : Description? EnumValue Directives[Const]?\n\nEnumTypeExtension :\n\n- extend enum Name Directives[Const]? EnumValuesDefinition\n- extend enum Name Directives[Const] [lookahead != `{`]\n\nInputObjectTypeDefinition :\n\n- Description? input Name Directives[Const]? InputFieldsDefinition\n- Description? input Name Directives[Const]? [lookahead != `{`]\n\nInputFieldsDefinition : { InputValueDefinition+ }\n\nInputObjectTypeExtension :\n\n- extend input Name Directives[Const]? InputFieldsDefinition\n- extend input Name Directives[Const] [lookahead != `{`]\n\nDirectiveDefinition : Description? directive @ Name ArgumentsDefinition?\n`repeatable`? on DirectiveLocations\n\nDirectiveLocations :\n\n- DirectiveLocations | DirectiveLocation\n- `|`? DirectiveLocation\n\nDirectiveLocation :\n\n- ExecutableDirectiveLocation\n- TypeSystemDirectiveLocation\n\nExecutableDirectiveLocation : one of\n\n- `QUERY`\n- `MUTATION`\n- `SUBSCRIPTION`\n- `FIELD`\n- `FRAGMENT_DEFINITION`\n- `FRAGMENT_SPREAD`\n- `INLINE_FRAGMENT`\n- `VARIABLE_DEFINITION`\n\nTypeSystemDirectiveLocation : one of\n\n- `SCHEMA`\n- `SCALAR`\n- `OBJECT`\n- `FIELD_DEFINITION`\n- `ARGUMENT_DEFINITION`\n- `INTERFACE`\n- `UNION`\n- `ENUM`\n- `ENUM_VALUE`\n- `INPUT_OBJECT`\n- `INPUT_FIELD_DEFINITION`\n\n## Schema Coordinate Syntax\n\nNote: Schema coordinates must not contain {Ignored}.\n\nSchemaCoordinateToken ::\n\n- SchemaCoordinatePunctuator\n- Name\n\nSchemaCoordinatePunctuator :: one of ( ) . : @\n\nSchemaCoordinate ::\n\n- TypeCoordinate\n- MemberCoordinate\n- ArgumentCoordinate\n- DirectiveCoordinate\n- DirectiveArgumentCoordinate\n\nTypeCoordinate :: Name\n\nMemberCoordinate :: Name . Name\n\nArgumentCoordinate :: Name . Name ( Name : )\n\nDirectiveCoordinate :: @ Name\n\nDirectiveArgumentCoordinate :: @ Name ( Name : )\n" }, { "path": "spec/Appendix D -- Specified Definitions.md", "content": "# D. Appendix: Type System Definitions\n\nThis appendix lists all type system definitions specified in this document.\n\nThe order of types, fields, arguments, values and directives is non-normative.\n\n```graphql\nscalar String\n\nscalar Int\n\nscalar Float\n\nscalar Boolean\n\nscalar ID\n\ndirective @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT\n\ndirective @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT\n\ndirective @deprecated(\n reason: String! = \"No longer supported\"\n) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE\n\ndirective @specifiedBy(url: String!) on SCALAR\n\ndirective @oneOf on INPUT_OBJECT\n\ntype __Schema {\n description: String\n types: [__Type!]!\n queryType: __Type!\n mutationType: __Type\n subscriptionType: __Type\n directives: [__Directive!]!\n}\n\ntype __Type {\n kind: __TypeKind!\n name: String\n description: String\n specifiedByURL: String\n fields(includeDeprecated: Boolean! = false): [__Field!]\n interfaces: [__Type!]\n possibleTypes: [__Type!]\n enumValues(includeDeprecated: Boolean! = false): [__EnumValue!]\n inputFields(includeDeprecated: Boolean! = false): [__InputValue!]\n ofType: __Type\n isOneOf: Boolean\n}\n\nenum __TypeKind {\n SCALAR\n OBJECT\n INTERFACE\n UNION\n ENUM\n INPUT_OBJECT\n LIST\n NON_NULL\n}\n\ntype __Field {\n name: String!\n description: String\n args(includeDeprecated: Boolean! = false): [__InputValue!]!\n type: __Type!\n isDeprecated: Boolean!\n deprecationReason: String\n}\n\ntype __InputValue {\n name: String!\n description: String\n type: __Type!\n defaultValue: String\n isDeprecated: Boolean!\n deprecationReason: String\n}\n\ntype __EnumValue {\n name: String!\n description: String\n isDeprecated: Boolean!\n deprecationReason: String\n}\n\ntype __Directive {\n name: String!\n description: String\n isRepeatable: Boolean!\n locations: [__DirectiveLocation!]!\n args(includeDeprecated: Boolean! = false): [__InputValue!]!\n}\n\nenum __DirectiveLocation {\n QUERY\n MUTATION\n SUBSCRIPTION\n FIELD\n FRAGMENT_DEFINITION\n FRAGMENT_SPREAD\n INLINE_FRAGMENT\n VARIABLE_DEFINITION\n SCHEMA\n SCALAR\n OBJECT\n FIELD_DEFINITION\n ARGUMENT_DEFINITION\n INTERFACE\n UNION\n ENUM\n ENUM_VALUE\n INPUT_OBJECT\n INPUT_FIELD_DEFINITION\n}\n```\n" }, { "path": "spec/GraphQL.md", "content": "# GraphQL\n\n_Current Working Draft_\n\n**Introduction**\n\nThis is the specification for GraphQL, a query language and execution engine for\ndescribing and performing the capabilities and requirements of data models for\nclient-server applications.\n\nA conforming implementation of GraphQL must fulfill all normative requirements\ndescribed in this specification (see [Conformance](#sec-Appendix-Conformance)).\nThe GraphQL specification is provided under the OWFa 1.0 license (see\n[Copyright and Licensing](#sec-Appendix-Copyright-and-Licensing)).\n\nGraphQL was originally created in 2012 and the development of this open standard\nstarted in 2015. It is a deliverable of the\n[GraphQL Specification Project](https://graphql.org/community/), established in\n2019 with the [Joint Development Foundation](https://www.jointdevelopment.org/).\n\nThe [GraphQL Foundation](https://graphql.org/foundation/) was formed in 2019 as\na neutral focal point for organizations who support development of the GraphQL\necosystem. If your organization benefits from GraphQL, please consider\n[becoming a member](https://graphql.org/foundation/join/#graphql-foundation).\n\nThis specification is developed on GitHub at\n[graphql/graphql-spec](https://github.com/graphql/graphql-spec/). Contributions\nare managed by the\n[GraphQL Working Group](https://github.com/graphql/graphql-wg), hosted by the\n[GraphQL Technical Steering Committee](https://github.com/graphql/graphql-wg/blob/main/GraphQL-TSC.md).\nTo learn more see the\n[contribution guide](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md).\n\nGraphQL has evolved and may continue to evolve in future editions of this\nspecification. Previous editions of the GraphQL specification can be found at\npermalinks that match their\n[release tag](https://github.com/graphql/graphql-spec/releases). The latest\nworking draft release can be found at\n[https://spec.graphql.org/draft](https://spec.graphql.org/draft).\n\n# [Overview](Section%201%20--%20Overview.md)\n\n# [Language](Section%202%20--%20Language.md)\n\n# [Type System](Section%203%20--%20Type%20System.md)\n\n# [Introspection](Section%204%20--%20Introspection.md)\n\n# [Validation](Section%205%20--%20Validation.md)\n\n# [Execution](Section%206%20--%20Execution.md)\n\n# [Response](Section%207%20--%20Response.md)\n\n# [Appendix: Conformance](Appendix%20A%20--%20Conformance.md)\n\n# [Appendix: Notation Conventions](Appendix%20B%20--%20Notation%20Conventions.md)\n\n# [Appendix: Grammar Summary](Appendix%20C%20--%20Grammar%20Summary.md)\n\n# [Appendix: Specified Definitions](Appendix%20D%20--%20Specified%20Definitions.md)\n\n# [Appendix: Licensing](../LICENSE.md)\n" }, { "path": "spec/Section 1 -- Overview.md", "content": "# Overview\n\nGraphQL is a query language designed to build client applications by providing\nan intuitive and flexible syntax and system for describing their data\nrequirements and interactions.\n\nFor example, this GraphQL _request_ will receive the name of the user with id 4\nfrom the Facebook implementation of GraphQL.\n\n```graphql example\n{\n user(id: 4) {\n name\n }\n}\n```\n\nWhich produces the resulting data (in JSON):\n\n```json example\n{\n \"user\": {\n \"name\": \"Mark Zuckerberg\"\n }\n}\n```\n\nGraphQL is not a programming language capable of arbitrary computation, but is\ninstead a language used to make requests to application services that have\ncapabilities defined in this specification. GraphQL does not mandate a\nparticular programming language or storage system for application services that\nimplement it. Instead, application services take their capabilities and map them\nto a uniform language, type system, and philosophy that GraphQL encodes. This\nprovides a unified interface friendly to product development and a powerful\nplatform for tool-building.\n\nGraphQL has a number of design principles:\n\n- **Product-centric**: GraphQL is unapologetically driven by the requirements of\n views and the front-end engineers that write them. GraphQL starts with their\n way of thinking and requirements and builds the language and runtime necessary\n to enable that.\n\n- **Hierarchical**: Most product development today involves the creation and\n manipulation of view hierarchies. To achieve congruence with the structure of\n these applications, a GraphQL request itself is structured hierarchically. The\n request is shaped just like the data in its response. It is a natural way for\n clients to describe data requirements.\n\n- **Strong-typing**: Every GraphQL service defines an application-specific type\n system. Requests are executed within the context of that type system. Given a\n GraphQL operation, tools can ensure that it is both syntactically correct and\n valid within that type system before execution, i.e. at development time, and\n the service can make certain guarantees about the shape and nature of the\n response.\n\n- **Client-specified response**: Through its type system, a GraphQL service\n publishes the capabilities that its clients are allowed to consume. It is the\n client that is responsible for specifying exactly how it will consume those\n published capabilities. These requests are specified at field-level\n granularity. In the majority of client-server applications written without\n GraphQL, the service determines the shape of data returned from its various\n endpoints. A GraphQL response, on the other hand, contains exactly what a\n client asks for and no more.\n\n- **Self-describing**: GraphQL is self-describing and introspective. A GraphQL\n service's type system can be queryable by the GraphQL language itself, which\n includes readable documentation. GraphQL introspection serves as a powerful\n platform for building common developer tools and client software libraries.\n\nBecause of these principles, GraphQL is a powerful and productive environment\nfor building client applications. Product developers and designers building\napplications against working GraphQL services—supported with quality tools—can\nquickly become productive without reading extensive documentation and with\nlittle or no formal training. To enable that experience, there must be those\nthat build those services and tools.\n\nThe following formal specification serves as a reference for those builders. It\ndescribes the language and its grammar, the type system and the introspection\nsystem used to query it, and the execution and validation engines with the\nalgorithms to power them. The goal of this specification is to provide a\nfoundation and framework for an ecosystem of GraphQL tools, client libraries,\nand service implementations—spanning both organizations and platforms—that has\nyet to be built. We look forward to working with the community in order to do\nthat.\n" }, { "path": "spec/Section 2 -- Language.md", "content": "# Language\n\nClients use the GraphQL query language to make requests to a GraphQL service. We\nrefer to these _request_ sources as documents. A document may contain operations\n(queries, mutations, and subscriptions) as well as fragments, a common unit of\ncomposition allowing for data requirement reuse.\n\nA GraphQL document is defined as a syntactic grammar where terminal symbols are\ntokens (indivisible lexical units). These tokens are defined in a lexical\ngrammar which matches patterns of source characters. In this document, syntactic\ngrammar productions are distinguished with a colon `:` while lexical grammar\nproductions are distinguished with a double-colon `::`.\n\nThe source text of a GraphQL document must be a sequence of {SourceCharacter}.\nThe character sequence must be described by a sequence of {Token} and {Ignored}\nlexical grammars. The lexical token sequence, omitting {Ignored}, must be\ndescribed by a single {Document} syntactic grammar.\n\nNote: See [Appendix A](#sec-Appendix-Notation-Conventions) for more information\nabout the lexical and syntactic grammar and other notational conventions used\nthroughout this document.\n\n**Lexical Analysis & Syntactic Parse**\n\nThe source text of a GraphQL document is first converted into a sequence of\nlexical tokens ({Token}) and ignored tokens ({Ignored}). The source text is\nscanned from left to right, repeatedly taking the next possible sequence of code\npoints allowed by the lexical grammar productions as the next token. This\nsequence of lexical tokens is then scanned from left to right to produce an\nabstract syntax tree (AST) according to the {Document} syntactic grammar.\n\nLexical grammar productions in this document use _lookahead restrictions_ to\nremove ambiguity and ensure a single valid lexical analysis. A lexical token is\nonly valid if not followed by a character in its lookahead restriction.\n\nFor example, an {IntValue} has the restriction {[lookahead != Digit]}, so cannot\nbe followed by a {Digit}. Because of this, the sequence {`123`} cannot represent\nthe tokens ({`12`}, {`3`}) since {`12`} is followed by the {Digit} {`3`} and so\nmust only represent a single token. Use {Whitespace} or other {Ignored} between\ncharacters to represent multiple tokens.\n\nNote: This typically has the same behavior as a\n\"[maximal munch](https://en.wikipedia.org/wiki/Maximal_munch)\" longest possible\nmatch, however some lookahead restrictions include additional constraints.\n\n## Source Text\n\nSourceCharacter :: \"Any Unicode scalar value\"\n\nGraphQL documents are interpreted from a source text, which is a sequence of\n{SourceCharacter}, each {SourceCharacter} being a _Unicode scalar value_ which\nmay be any Unicode code point from U+0000 to U+D7FF or U+E000 to U+10FFFF\n(informally referred to as _\"characters\"_ through most of this specification).\n\nA GraphQL document may be expressed only in the ASCII range to be as widely\ncompatible with as many existing tools, languages, and serialization formats as\npossible and avoid display issues in text editors and source control. Non-ASCII\nUnicode scalar values may appear within {StringValue} and {Comment}.\n\nNote: An implementation which uses _UTF-16_ to represent GraphQL documents in\nmemory (for example, JavaScript or Java) may encounter a _surrogate pair_. This\nencodes one _supplementary code point_ and is a single valid source character,\nhowever an unpaired _surrogate code point_ is not a valid source character.\n\n### White Space\n\nWhitespace ::\n\n- \"Horizontal Tab (U+0009)\"\n- \"Space (U+0020)\"\n\nWhitespace is used to improve legibility of source text and separates other\ntokens. Any amount of whitespace may appear before or after any token.\nWhitespace between tokens is not significant to the semantic meaning of a\nGraphQL document, however whitespace characters may appear within a {String} or\n{Comment} token.\n\nNote: GraphQL intentionally does not consider Unicode \"Zs\" category characters\nas whitespace, avoiding misinterpretation by text editors and source control\ntools.\n\n### Line Terminators\n\nLineTerminator ::\n\n- \"New Line (U+000A)\"\n- \"Carriage Return (U+000D)\" [lookahead != \"New Line (U+000A)\"]\n- \"Carriage Return (U+000D)\" \"New Line (U+000A)\"\n\nLike whitespace, line terminators are used to improve the legibility of source\ntext and separate lexical tokens, any amount may appear before or after any\nother token and have no significance to the semantic meaning of a GraphQL\nDocument.\n\nNote: Any error reporting which provides the line number in the source of the\noffending syntax should use the preceding amount of {LineTerminator} to produce\nthe line number.\n\n### Comments\n\nComment :: `#` CommentChar\\* [lookahead != CommentChar]\n\nCommentChar :: SourceCharacter but not LineTerminator\n\nGraphQL source documents may contain single-line comments, starting with the\n{`#`} marker.\n\nA comment may contain any {SourceCharacter} except {LineTerminator} so a comment\nalways consists of all {SourceCharacter} starting with the {`#`} character up to\nbut not including the {LineTerminator} (or end of the source).\n\nComments are {Ignored} like whitespace and may appear after any token, or before\na {LineTerminator}, and have no significance to the semantic meaning of a\nGraphQL document.\n\n### Insignificant Commas\n\nComma :: ,\n\nSimilar to whitespace and line terminators, commas ({`,`}) are used to improve\nthe legibility of source text and separate lexical tokens but are otherwise\nsyntactically and semantically insignificant within GraphQL documents.\n\nNon-significant comma characters ensure that the absence or presence of a comma\ndoes not meaningfully alter the interpreted syntax of the document, as this can\nbe a common user error in other languages. It also allows for the stylistic use\nof either trailing commas or line terminators as list delimiters which are both\noften desired for legibility and maintainability of source code.\n\n### Lexical Tokens\n\nToken ::\n\n- Punctuator\n- Name\n- IntValue\n- FloatValue\n- StringValue\n\nA GraphQL document is composed of several kinds of indivisible lexical tokens\ndefined here in a lexical grammar by patterns of source Unicode characters.\nLexical tokens may be separated by {Ignored} tokens.\n\nTokens are later used as terminal symbols in GraphQL syntactic grammar rules.\n\n### Ignored Tokens\n\nIgnored ::\n\n- UnicodeBOM\n- Whitespace\n- LineTerminator\n- Comment\n- Comma\n\n{Ignored} tokens are used to improve readability and provide separation between\nlexical tokens, but are otherwise insignificant and not referenced in syntactic\ngrammar productions.\n\nAny amount of {Ignored} may appear before and after every lexical token. No\nignored regions of a source document are significant, however {SourceCharacter}\nwhich appear in {Ignored} may also appear within a lexical {Token} in a\nsignificant way, for example a {StringValue} may contain whitespace characters.\nNo {Ignored} may appear _within_ a {Token}, for example no whitespace characters\nare permitted between the characters defining a {FloatValue}.\n\n**Byte Order Mark**\n\nUnicodeBOM :: \"Byte Order Mark (U+FEFF)\"\n\nThe _Byte Order Mark_ is a special Unicode code point which may appear at the\nbeginning of a file which programs may use to determine the fact that the text\nstream is Unicode, and what specific encoding has been used. As files are often\nconcatenated, a _Byte Order Mark_ may appear before or after any lexical token\nand is {Ignored}.\n\n### Punctuators\n\nPunctuator :: one of ! $ & ( ) ... : = @ [ ] { | }\n\nGraphQL documents include punctuation in order to describe structure. GraphQL is\na data description language and not a programming language; therefore, GraphQL\nlacks the punctuation often used to describe mathematical expressions.\n\n### Names\n\nName ::\n\n- NameStart NameContinue\\* [lookahead != NameContinue]\n\nNameStart ::\n\n- Letter\n- `_`\n\nNameContinue ::\n\n- Letter\n- Digit\n- `_`\n\nLetter :: one of\n\n- `A` `B` `C` `D` `E` `F` `G` `H` `I` `J` `K` `L` `M`\n- `N` `O` `P` `Q` `R` `S` `T` `U` `V` `W` `X` `Y` `Z`\n- `a` `b` `c` `d` `e` `f` `g` `h` `i` `j` `k` `l` `m`\n- `n` `o` `p` `q` `r` `s` `t` `u` `v` `w` `x` `y` `z`\n\nDigit :: one of\n\n- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`\n\nGraphQL documents are full of named things: operations, fields, arguments,\ntypes, directives, fragments, and variables. All names must follow the same\ngrammatical form.\n\nNames in GraphQL are case-sensitive. That is to say `name`, `Name`, and `NAME`\nall refer to different names. Underscores are significant, which means\n`other_name` and `othername` are two different names.\n\nA {Name} must not be followed by a {NameContinue}. In other words, a {Name}\ntoken is always the longest possible valid sequence. The source characters\n{`a1`} cannot be interpreted as two tokens since {`a`} is followed by the\n{NameContinue} {`1`}.\n\nNote: Names in GraphQL are limited to the Latin ASCII subset\nof {SourceCharacter} in order to support interoperation with as many other\nsystems as possible.\n\n**Reserved Names**\n\nAny {Name} within a GraphQL type system must not start with two underscores\n{\"\\_\\_\"} unless it is part of the [introspection system](#sec-Introspection) as\ndefined by this specification.\n\n## Descriptions\n\nDescription : StringValue\n\nDocumentation is a first-class feature of GraphQL by including written\ndescriptions on all named definitions in executable {Document} and GraphQL type\nsystems, which is also made available via introspection ensuring the\ndocumentation of a GraphQL service remains consistent with its capabilities (see\n[Type System Descriptions](#sec-Type-System-Descriptions)).\n\nGraphQL descriptions are provided as Markdown (as specified by\n[CommonMark](https://commonmark.org/)). Description strings (often\n{BlockString}) occur immediately before the definition they describe.\n\nDescriptions in GraphQL executable documents are purely for documentation\npurposes. They MUST NOT affect the execution, validation, or response of a\nGraphQL document. It is safe to remove all descriptions and comments from\nexecutable documents without changing their behavior or results.\n\nThis is an example of a well-described operation:\n\n```graphql example\n\"\"\"\nRequest the current status of a time machine and its operator.\nYou can also check the status for a particular year.\n**Warning:** certain years may trigger an anomaly in the space-time continuum.\n\"\"\"\nquery GetTimeMachineStatus(\n \"The unique serial number of the time machine to inspect.\"\n $machineId: ID!\n \"The year to check the status for.\"\n $year: Int\n) {\n timeMachine(id: $machineId) {\n ...TimeMachineDetails\n status(year: $year)\n }\n}\n\n\"Details about a time machine and its operator.\"\nfragment TimeMachineDetails on TimeMachine {\n id\n model\n lastMaintenance\n operator {\n name\n licenseLevel\n }\n}\n```\n\n## Document\n\nDocument : Definition+\n\nDefinition :\n\n- ExecutableDefinition\n- TypeSystemDefinitionOrExtension\n\nExecutableDocument : ExecutableDefinition+\n\nExecutableDefinition :\n\n- OperationDefinition\n- FragmentDefinition\n\nA GraphQL document describes a complete file or request string operated on by a\nGraphQL service or client. A document contains multiple definitions, either\nexecutable or representative of a GraphQL type system.\n\nDocuments are only executable by a GraphQL service if they are\n{ExecutableDocument} and contain at least one {OperationDefinition}. A Document\nwhich contains {TypeSystemDefinitionOrExtension} must not be executed; GraphQL\nexecution services which receive a Document containing these should return a\ndescriptive error.\n\nGraphQL services which only seek to execute GraphQL requests and not construct a\nnew GraphQL schema may choose to only permit {ExecutableDocument}.\n\nDocuments which do not contain {OperationDefinition} or do contain\n{TypeSystemDefinitionOrExtension} may still be parsed and validated to allow\nclient tools to represent many GraphQL uses which may appear across many\nindividual files.\n\nIf a Document contains only one operation, that operation may be unnamed. If\nthat operation is a query without variables or directives then it may also be\nrepresented in the shorthand form, omitting both the {`query`} keyword as well\nas the operation name. Otherwise, if a GraphQL document contains multiple\noperations, each operation must be named. When submitting a Document with\nmultiple operations to a GraphQL service, the name of the desired operation to\nbe executed must also be provided.\n\n## Operations\n\nOperationDefinition :\n\n- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet\n- SelectionSet\n\nOperationType : one of `query` `mutation` `subscription`\n\nThere are three types of operations that GraphQL models:\n\n- query - a read-only fetch.\n- mutation - a write followed by a fetch.\n- subscription - a long-lived request that fetches data in response to a\n sequence of events over time.\n\nEach operation is represented by an optional operation name and a _selection\nset_.\n\nFor example, this mutation operation might \"like\" a story and then retrieve the\nnew number of likes:\n\n```graphql example\n\"\"\"\nMark story 12345 as \"liked\"\nand return the updated number of likes on the story\n\"\"\"\nmutation {\n likeStory(storyID: 12345) {\n story {\n likeCount\n }\n }\n}\n```\n\n**Query Shorthand**\n\nIf a document contains only one operation and that operation is a query which\ndefines no variables and has no directives applied to it then that operation may\nbe represented in a shorthand form which omits the {`query`} keyword and\noperation name.\n\nFor example, this unnamed query operation is written via query shorthand.\n\n```graphql example\n{\n field\n}\n```\n\nDescriptions are not permitted on query shorthand.\n\nNote: many examples below will use the query shorthand syntax.\n\n## Selection Sets\n\nSelectionSet : { Selection+ }\n\nSelection :\n\n- Field\n- FragmentSpread\n- InlineFragment\n\nAn operation selects the set of information it needs, and will receive exactly\nthat information and nothing more, avoiding over-fetching and under-fetching\ndata.\n\n:: A _selection set_ defines an ordered set of selections (fields, fragment\nspreads and inline fragments) against an object, union or interface type.\n\n```graphql example\n{\n id\n firstName\n lastName\n}\n```\n\nIn this query operation, the `id`, `firstName`, and `lastName` fields form a\n_selection set_. Selection sets may also contain fragment references.\n\n## Fields\n\nField : Alias? Name Arguments? Directives? SelectionSet?\n\nA _selection set_ is primarily composed of fields. A field describes one\ndiscrete piece of information available to request within a selection set.\n\nSome fields describe complex data or relationships to other data. In order to\nfurther explore this data, a field may itself contain a selection set, allowing\nfor deeply nested requests. All GraphQL operations must specify their selections\ndown to fields which return scalar values to ensure an unambiguously shaped\nresponse.\n\nFor example, this operation selects fields of complex data and relationships\ndown to scalar values.\n\n```graphql example\n{\n me {\n id\n firstName\n lastName\n birthday {\n month\n day\n }\n friends {\n name\n }\n }\n}\n```\n\nFields in the top-level _selection set_ of an operation often represent some\ninformation that is globally accessible to your application and its current\nviewer. Some typical examples of these top fields include references to a\ncurrent logged-in viewer, or accessing certain types of data referenced by a\nunique identifier.\n\n```graphql example\n# `me` could represent the currently logged in viewer.\n{\n me {\n name\n }\n}\n\n# `user` represents one of many users in a graph of data, referred to by a\n# unique identifier.\n{\n user(id: 4) {\n name\n }\n}\n```\n\n## Arguments\n\nArguments[Const] : ( Argument[?Const]+ )\n\nArgument[Const] : Name : Value[?Const]\n\nFields are conceptually functions which return values, and occasionally accept\narguments which alter their behavior. These arguments often map directly to\nfunction arguments within a GraphQL service's implementation.\n\nIn this example, we want to query a specific user (requested via the `id`\nargument) and their profile picture of a specific `size`:\n\n```graphql example\n{\n user(id: 4) {\n id\n name\n profilePic(size: 100)\n }\n}\n```\n\nMany arguments can exist for a given field:\n\n```graphql example\n{\n user(id: 4) {\n id\n name\n profilePic(width: 100, height: 50)\n }\n}\n```\n\n**Arguments Are Unordered**\n\nArguments may be provided in any syntactic order and maintain identical semantic\nmeaning.\n\nThese two operations are semantically identical:\n\n```graphql example\n{\n picture(width: 200, height: 100)\n}\n```\n\n```graphql example\n{\n picture(height: 100, width: 200)\n}\n```\n\n## Field Alias\n\nAlias : Name :\n\n:: A _response name_ is the key in the response object which correlates with a\nfield's result. By default the response name will use the field's name; however,\nyou can define a different response name by specifying an alias.\n\nIn this example, we can fetch two profile pictures of different sizes and ensure\nthe resulting response object will not have duplicate keys:\n\n```graphql example\n{\n user(id: 4) {\n id\n name\n smallPic: profilePic(size: 64)\n bigPic: profilePic(size: 1024)\n }\n}\n```\n\nwhich returns the result:\n\n```json example\n{\n \"user\": {\n \"id\": 4,\n \"name\": \"Mark Zuckerberg\",\n \"smallPic\": \"https://cdn.site.io/pic-4-64.jpg\",\n \"bigPic\": \"https://cdn.site.io/pic-4-1024.jpg\"\n }\n}\n```\n\nThe fields at the top level of an operation can also be given an alias:\n\n```graphql example\n{\n zuck: user(id: 4) {\n id\n name\n }\n}\n```\n\nwhich returns the result:\n\n```json example\n{\n \"zuck\": {\n \"id\": 4,\n \"name\": \"Mark Zuckerberg\"\n }\n}\n```\n\n## Fragments\n\nFragmentSpread : ... FragmentName Directives?\n\nFragmentDefinition : Description? fragment FragmentName TypeCondition\nDirectives? SelectionSet\n\nFragmentName : Name but not `on`\n\nFragments are the primary unit of composition in GraphQL.\n\nEach data-consuming component (function, class, UI element, and so on) of a\nclient application should declare its data needs in a dedicated fragment. These\nfragments may then be composed, following the usage of the components\nthemselves, to form a GraphQL operation to issue to the server.\n\nFor example, if we have some logic that requires `id`, `name`, and `profilePic`\nto render a profile, and we want to apply that logic to the friends and mutual\nfriends of a user:\n\n```graphql example\nquery noFragments {\n user(id: 4) {\n friends(first: 10) {\n id\n name\n profilePic(size: 50)\n }\n mutualFriends(first: 10) {\n id\n name\n profilePic(size: 50)\n }\n }\n}\n```\n\nThe fields required to render a profile can be extracted into a fragment and\ncomposed by a parent fragment or operation.\n\n```graphql example\nquery withFragments {\n user(id: 4) {\n friends(first: 10) {\n ...friendProfile\n }\n mutualFriends(first: 10) {\n ...friendProfile\n }\n }\n}\n```\n\n```graphql example\n\"Fields required to render a friend's profile\"\nfragment friendProfile on User {\n id\n name\n profilePic(size: 50)\n}\n```\n\nIf the profile rendering logic no longer needs `name`, the `name` field can be\nremoved from the `friendProfile` fragment and it will no longer be fetched in\nboth locations the fragment is consumed.\n\nFragments are consumed by using the spread operator (`...`). All fields selected\nby the fragment will be added to the field selection at the same level as the\nfragment invocation. This happens through multiple levels of fragment spreads.\n\nFor example:\n\n```graphql example\nquery withNestedFragments {\n user(id: 4) {\n friends(first: 10) {\n ...friendFields\n }\n mutualFriends(first: 10) {\n ...friendFields\n }\n }\n}\n\nfragment friendFields on User {\n id\n name\n ...standardProfilePic\n}\n\nfragment standardProfilePic on User {\n profilePic(size: 50)\n}\n```\n\nThe operations `noFragments`, `withFragments`, and `withNestedFragments` all\nproduce the same response object.\n\n### Type Conditions\n\nTypeCondition : on NamedType\n\nFragments must specify the type they apply to. In this example, `friendFields`\ncan be used in the context of querying a `User`.\n\nFragments cannot be specified on any input value (scalar, enumeration, or input\nobject).\n\nFragments can be specified on object types, interfaces, and unions.\n\nSelections within fragments only return values when the concrete type of the\nobject it is operating on matches the type of the fragment.\n\nFor example in this operation using the Facebook data model:\n\n```graphql example\nquery FragmentTyping {\n profiles(handles: [\"zuck\", \"coca-cola\"]) {\n handle\n ...userFragment\n ...pageFragment\n }\n}\n\nfragment userFragment on User {\n friends {\n count\n }\n}\n\nfragment pageFragment on Page {\n likers {\n count\n }\n}\n```\n\nThe `profiles` root field returns a list where each element could be a `Page` or\na `User`. When the object in the `profiles` result is a `User`, `friends` will\nbe present and `likers` will not. Conversely when the result is a `Page`,\n`likers` will be present and `friends` will not.\n\n```json example\n{\n \"profiles\": [\n {\n \"handle\": \"zuck\",\n \"friends\": { \"count\": 1234 }\n },\n {\n \"handle\": \"coca-cola\",\n \"likers\": { \"count\": 90234512 }\n }\n ]\n}\n```\n\n### Inline Fragments\n\nInlineFragment : ... TypeCondition? Directives? SelectionSet\n\nFragments can also be defined inline within a _selection set_. This is useful\nfor conditionally including fields based on a type condition or applying a\ndirective to a selection set.\n\nThis feature of standard fragment inclusion was demonstrated in the\n`query FragmentTyping` example above. We could accomplish the same thing using\ninline fragments.\n\n```graphql example\nquery inlineFragmentTyping {\n profiles(handles: [\"zuck\", \"coca-cola\"]) {\n handle\n ... on User {\n friends {\n count\n }\n }\n ... on Page {\n likers {\n count\n }\n }\n }\n}\n```\n\nInline fragments may also be used to apply a directive to a group of fields. If\nthe TypeCondition is omitted, an inline fragment is considered to be of the same\ntype as the enclosing context.\n\n```graphql example\nquery inlineFragmentNoType($expandedInfo: Boolean) {\n user(handle: \"zuck\") {\n id\n name\n ... @include(if: $expandedInfo) {\n firstName\n lastName\n birthday\n }\n }\n}\n```\n\n## Input Values\n\nValue[Const] :\n\n- [~Const] Variable\n- IntValue\n- FloatValue\n- StringValue\n- BooleanValue\n- NullValue\n- EnumValue\n- ListValue[?Const]\n- ObjectValue[?Const]\n\nField and directive arguments accept input values of various literal primitives;\ninput values can be scalars, enumeration values, lists, or input objects.\n\nIf not defined as constant (for example, in {DefaultValue}), input values can be\nspecified as a variable. List and inputs objects may also contain variables\n(unless defined to be constant).\n\n### Int Value\n\nIntValue :: IntegerPart [lookahead != {Digit, `.`, NameStart}]\n\nIntegerPart ::\n\n- NegativeSign? 0\n- NegativeSign? NonZeroDigit Digit\\*\n\nNegativeSign :: -\n\nNonZeroDigit :: Digit but not `0`\n\nAn {IntValue} is specified without a decimal point or exponent but may be\nnegative (e.g. {-123}). It must not have any leading {0}.\n\nAn {IntValue} must not be followed by a {Digit}. In other words, an {IntValue}\ntoken is always the longest possible valid sequence. The source characters {12}\ncannot be interpreted as two tokens since {1} is followed by the {Digit} {2}.\nThis also means the source {00} is invalid since it can neither be interpreted\nas a single token nor two {0} tokens.\n\nAn {IntValue} must not be followed by a {`.`} or {NameStart}. If either {`.`} or\n{ExponentIndicator} follows then the token must only be interpreted as a\npossible {FloatValue}. No other {NameStart} character can follow. For example\nthe sequences `0x123` and `123L` have no valid lexical representations.\n\n### Float Value\n\nFloatValue ::\n\n- IntegerPart FractionalPart ExponentPart [lookahead != {Digit, `.`, NameStart}]\n- IntegerPart FractionalPart [lookahead != {Digit, `.`, NameStart}]\n- IntegerPart ExponentPart [lookahead != {Digit, `.`, NameStart}]\n\nFractionalPart :: . Digit+\n\nExponentPart :: ExponentIndicator Sign? Digit+\n\nExponentIndicator :: one of `e` `E`\n\nSign :: one of + -\n\nA {FloatValue} includes either a decimal point (e.g. {1.0}) or an exponent (e.g.\n{1e50}) or both (e.g. {6.0221413e23}) and may be negative. Like {IntValue}, it\nalso must not have any leading {0}.\n\nA {FloatValue} must not be followed by a {Digit}. In other words, a {FloatValue}\ntoken is always the longest possible valid sequence. The source characters\n{1.23} cannot be interpreted as two tokens since {1.2} is followed by the\n{Digit} {3}.\n\nA {FloatValue} must not be followed by a {.}. For example, the sequence {1.23.4}\ncannot be interpreted as two tokens ({1.2}, {3.4}).\n\nA {FloatValue} must not be followed by a {NameStart}. For example the sequence\n`0x1.2p3` has no valid lexical representation.\n\nNote: The numeric literals {IntValue} and {FloatValue} both restrict being\nimmediately followed by a letter (or other {NameStart}) to reduce confusion or\nunexpected behavior since GraphQL only supports decimal numbers.\n\n### Boolean Value\n\nBooleanValue : one of `true` `false`\n\nThe two keywords `true` and `false` represent the two boolean values.\n\n### String Value\n\nStringValue ::\n\n- `\"\"` [lookahead != `\"`]\n- `\"` StringCharacter+ `\"`\n- BlockString\n\nStringCharacter ::\n\n- SourceCharacter but not `\"` or `\\` or LineTerminator\n- `\\u` EscapedUnicode\n- `\\` EscapedCharacter\n\nEscapedUnicode ::\n\n- `{` HexDigit+ `}`\n- HexDigit HexDigit HexDigit HexDigit\n\nHexDigit :: one of\n\n- `0` `1` `2` `3` `4` `5` `6` `7` `8` `9`\n- `A` `B` `C` `D` `E` `F`\n- `a` `b` `c` `d` `e` `f`\n\nEscapedCharacter :: one of `\"` `\\` `/` `b` `f` `n` `r` `t`\n\nBlockString :: `\"\"\"` BlockStringCharacter\\* `\"\"\"`\n\nBlockStringCharacter ::\n\n- SourceCharacter but not `\"\"\"` or `\\\"\"\"`\n- `\\\"\"\"`\n\nA {StringValue} is evaluated to a _Unicode text_ value, a sequence of _Unicode\nscalar value_, by interpreting all escape sequences using the static semantics\ndefined below. Whitespace and other characters ignored between lexical tokens\nare significant within a string value.\n\nThe empty string {`\"\"`} must not be followed by another {`\"`} otherwise it would\nbe interpreted as the beginning of a block string. As an example, the source\n{`\"\"\"\"\"\"`} can only be interpreted as a single empty block string and not three\nempty strings.\n\n**Escape Sequences**\n\nIn a single-quoted {StringValue}, any _Unicode scalar value_ may be expressed\nusing an escape sequence. GraphQL strings allow both C-style escape sequences\n(for example `\\n`) and two forms of Unicode escape sequences: one with a\nfixed-width of 4 hexadecimal digits (for example `\\u000A`) and one with a\nvariable-width most useful for representing a _supplementary character_ such as\nan Emoji (for example `\\u{1F4A9}`).\n\nThe hexadecimal number encoded by a Unicode escape sequence must describe a\n_Unicode scalar value_, otherwise must result in a parse error. For example both\nsources `\"\\uDEAD\"` and `\"\\u{110000}\"` should not be considered valid\n{StringValue}.\n\nEscape sequences are only meaningful within a single-quoted string. Within a\nblock string, they are simply that sequence of characters (for example\n`\"\"\"\\n\"\"\"` represents the _Unicode text_ [U+005C, U+006E]). Within a comment an\nescape sequence is not a significant sequence of characters. They may not appear\nelsewhere in a GraphQL document.\n\nSince {StringCharacter} must not contain some code points directly (for example,\na {LineTerminator}), escape sequences must be used to represent them. All other\nescape sequences are optional and unescaped non-ASCII Unicode characters are\nallowed within strings. If using GraphQL within a system which only supports\nASCII, then escape sequences may be used to represent all Unicode characters\noutside of the ASCII range.\n\nFor legacy reasons, a _supplementary character_ may be escaped by two\nfixed-width unicode escape sequences forming a _surrogate pair_. For example the\ninput `\"\\uD83D\\uDCA9\"` is a valid {StringValue} which represents the same\n_Unicode text_ as `\"\\u{1F4A9}\"`. While this legacy form is allowed, it should be\navoided as a variable-width unicode escape sequence is a clearer way to encode\nsuch code points.\n\nWhen producing a {StringValue}, implementations should use escape sequences to\nrepresent non-printable control characters (U+0000 to U+001F and U+007F to\nU+009F). Other escape sequences are not necessary, however an implementation may\nuse escape sequences to represent any other range of code points (for example,\nwhen producing ASCII-only output). If an implementation chooses to escape a\n_supplementary character_, it should only use a variable-width unicode escape\nsequence.\n\n**Block Strings**\n\nBlock strings are sequences of characters wrapped in triple-quotes (`\"\"\"`).\nWhitespace, line terminators, quote, and backslash characters may all be used\nunescaped to enable verbatim text. Characters must all be valid\n{SourceCharacter}.\n\nSince block strings represent freeform text often used in indented positions,\nthe string value semantics of a block string excludes uniform indentation and\nblank initial and trailing lines via {BlockStringValue()}.\n\nFor example, the following operation containing a block string:\n\n```raw graphql example\nmutation {\n sendEmail(message: \"\"\"\n Hello,\n World!\n\n Yours,\n GraphQL.\n \"\"\")\n}\n```\n\nIs identical to the standard quoted string:\n\n```graphql example\nmutation {\n sendEmail(message: \"Hello,\\n World!\\n\\nYours,\\n GraphQL.\")\n}\n```\n\nSince block string values strip leading and trailing empty lines, there is no\nsingle canonical printed block string for a given value. Because block strings\ntypically represent freeform text, it is considered easier to read if they begin\nand end with an empty line.\n\n```graphql example\n\"\"\"\nThis starts with and ends with an empty line,\nwhich makes it easier to read.\n\"\"\"\n```\n\n```graphql counter-example\n\"\"\"This does not start with or end with any empty lines,\nwhich makes it a little harder to read.\"\"\"\n```\n\nNote: If non-printable ASCII characters are needed in a string value, a standard\nquoted string with appropriate escape sequences must be used instead of a block\nstring.\n\n**Static Semantics**\n\n:: A {StringValue} describes a _Unicode text_ value, which is a sequence of\n_Unicode scalar value_.\n\nThese semantics describe how to apply the {StringValue} grammar to a source text\nto evaluate a _Unicode text_. Errors encountered during this evaluation are\nconsidered a failure to apply the {StringValue} grammar to a source and must\nresult in a parsing error.\n\nStringValue :: `\"\"`\n\n- Return an empty sequence.\n\nStringValue :: `\"` StringCharacter+ `\"`\n\n- Return the _Unicode text_ by concatenating the evaluation of all\n {StringCharacter}.\n\nStringCharacter :: SourceCharacter but not `\"` or `\\` or LineTerminator\n\n- Return the _Unicode scalar value_ {SourceCharacter}.\n\nStringCharacter :: `\\u` EscapedUnicode\n\n- Let {value} be the hexadecimal value represented by the sequence of {HexDigit}\n within {EscapedUnicode}.\n- Assert: {value} is a within the _Unicode scalar value_ range (>= 0x0000 and <=\n 0xD7FF or >= 0xE000 and <= 0x10FFFF).\n- Return the _Unicode scalar value_ {value}.\n\nStringCharacter :: `\\u` HexDigit HexDigit HexDigit HexDigit `\\u` HexDigit\nHexDigit HexDigit HexDigit\n\n- Let {leadingValue} be the hexadecimal value represented by the first sequence\n of {HexDigit}.\n- Let {trailingValue} be the hexadecimal value represented by the second\n sequence of {HexDigit}.\n- If {leadingValue} is >= 0xD800 and <= 0xDBFF (a _Leading Surrogate_):\n - Assert: {trailingValue} is >= 0xDC00 and <= 0xDFFF (a _Trailing Surrogate_).\n - Return ({leadingValue} - 0xD800) × 0x400 + ({trailingValue} - 0xDC00) +\n 0x10000.\n- Otherwise:\n - Assert: {leadingValue} is within the _Unicode scalar value_ range.\n - Assert: {trailingValue} is within the _Unicode scalar value_ range.\n - Return the sequence of the _Unicode scalar value_ {leadingValue} followed by\n the _Unicode scalar value_ {trailingValue}.\n\nNote: If both escape sequences encode a _Unicode scalar value_, then this\nsemantic is identical to applying the prior semantic on each fixed-width escape\nsequence. A variable-width escape sequence must only encode a _Unicode scalar\nvalue_.\n\nStringCharacter :: `\\` EscapedCharacter\n\n- Return the _Unicode scalar value_ represented by {EscapedCharacter} according\n to the table below.\n\n| Escaped Character | Scalar Value | Character Name |\n| ----------------- | ------------ | ---------------------------- |\n| {`\"`} | U+0022 | double quote |\n| {`\\`} | U+005C | reverse solidus (back slash) |\n| {`/`} | U+002F | solidus (forward slash) |\n| {`b`} | U+0008 | backspace |\n| {`f`} | U+000C | form feed |\n| {`n`} | U+000A | line feed (new line) |\n| {`r`} | U+000D | carriage return |\n| {`t`} | U+0009 | horizontal tab |\n\nStringValue :: BlockString\n\n- Return the _Unicode text_ by evaluating the {BlockString}.\n\nBlockString :: `\"\"\"` BlockStringCharacter\\* `\"\"\"`\n\n- Let {rawValue} be the _Unicode text_ by concatenating the evaluation of all\n {BlockStringCharacter} (which may be an empty sequence).\n- Return the result of {BlockStringValue(rawValue)}.\n\nBlockStringCharacter :: SourceCharacter but not `\"\"\"` or `\\\"\"\"`\n\n- Return the _Unicode scalar value_ {SourceCharacter}.\n\nBlockStringCharacter :: `\\\"\"\"`\n\n- Return the character sequence `\"\"\"`.\n\nBlockStringValue(rawValue):\n\n- Let {lines} be the result of splitting {rawValue} by {LineTerminator}.\n- Let {commonIndent} be {null}.\n- For each {line} in {lines}:\n - If {line} is the first item in {lines}, continue to the next {line}.\n - Let {length} be the number of characters in {line}.\n - Let {indent} be the number of leading consecutive {Whitespace} characters in\n {line}.\n - If {indent} is less than {length}:\n - If {commonIndent} is {null} or {indent} is less than {commonIndent}:\n - Let {commonIndent} be {indent}.\n- If {commonIndent} is not {null}:\n - For each {line} in {lines}:\n - If {line} is the first item in {lines}, continue to the next line.\n - Remove {commonIndent} characters from the beginning of {line}.\n- While the first item {line} in {lines} contains only {Whitespace}:\n - Remove the first item from {lines}.\n- While the last item {line} in {lines} contains only {Whitespace}:\n - Remove the last item from {lines}.\n- Let {formatted} be the empty character sequence.\n- For each {line} in {lines}:\n - If {line} is the first item in {lines}:\n - Append {formatted} with {line}.\n - Otherwise:\n - Append {formatted} with a line feed character (U+000A).\n - Append {formatted} with {line}.\n- Return {formatted}.\n\n### Null Value\n\nNullValue : `null`\n\nNull values are represented as the keyword {null}.\n\nGraphQL has two semantically different ways to represent the lack of a value:\n\n- Explicitly providing the literal value: {null}.\n- Implicitly not providing a value at all.\n\nFor example, these two field calls are similar, but are not identical:\n\n```graphql example\n{\n field(arg: null)\n field\n}\n```\n\nThe first has explicitly provided {null} to the argument \"arg\", while the second\nhas implicitly not provided a value to the argument \"arg\". These two forms may\nbe interpreted differently. For example, a mutation representing deleting a\nfield vs not altering a field, respectively. Neither form may be used for an\ninput expecting a Non-Null type.\n\nNote: The same two methods of representing the lack of a value are possible via\nvariables by either providing the variable value as {null} or not providing a\nvariable value at all.\n\n### Enum Value\n\nEnumValue : Name but not `true`, `false` or `null`\n\nEnum values are represented as unquoted names (e.g. `MOBILE_WEB`). It is\nrecommended that Enum values be \"all caps\". Enum values are only used in\ncontexts where the precise enumeration type is known. Therefore it is not\nnecessary to supply an enumeration type name in the literal.\n\n### List Value\n\nListValue[Const] :\n\n- [ ]\n- [ Value[?Const]+ ]\n\nLists are ordered sequences of values wrapped in square brackets `[ ]`. The\nvalues of a List literal may be any value literal or variable (e.g.\n`[1, 2, 3]`).\n\nCommas are optional throughout GraphQL so trailing commas are allowed and\nrepeated commas do not represent missing values.\n\n**Semantics**\n\nListValue : [ ]\n\n- Return a new empty list value.\n\nListValue : [ Value+ ]\n\n- Let {inputList} be a new empty list value.\n- For each {Value+}:\n - Let {value} be the result of evaluating {Value}.\n - Append {value} to {inputList}.\n- Return {inputList}.\n\n### Input Object Values\n\nObjectValue[Const] :\n\n- { }\n- { ObjectField[?Const]+ }\n\nObjectField[Const] : Name : Value[?Const]\n\nInput object literal values are unordered lists of keyed input values wrapped in\ncurly braces `{ }`. The values of an object literal may be any input value\nliteral or variable (e.g. `{ name: \"Hello world\", score: 1.0 }`). We refer to\nliteral representation of input objects as \"object literals.\"\n\n**Input Object Fields Are Unordered**\n\nInput object fields may be provided in any syntactic order and maintain\nidentical semantic meaning.\n\nThese two operations are semantically identical:\n\n```graphql example\n{\n nearestThing(location: { lon: 12.43, lat: -53.211 })\n}\n```\n\n```graphql example\n{\n nearestThing(location: { lat: -53.211, lon: 12.43 })\n}\n```\n\n**Semantics**\n\nObjectValue : { }\n\n- Return a new input object value with no fields.\n\nObjectValue : { ObjectField+ }\n\n- Let {inputObject} be a new input object value with no fields.\n- For each {field} in {ObjectField+}:\n - Let {name} be {Name} in {field}.\n - Let {value} be the result of evaluating {Value} in {field}.\n - Add a field to {inputObject} of name {name} containing value {value}.\n- Return {inputObject}.\n\n## Variables\n\nVariable : $ Name\n\nVariablesDefinition : ( VariableDefinition+ )\n\nVariableDefinition : Description? Variable : Type DefaultValue?\nDirectives[Const]?\n\nDefaultValue : = Value[Const]\n\nA GraphQL operation can be parameterized with variables, maximizing reuse, and\navoiding costly string building in clients at runtime.\n\nIf not defined as constant (for example, in {DefaultValue}), a {Variable} can be\nsupplied for an input value.\n\nVariables must be defined at the top of an operation and are in scope throughout\nthe execution of that operation. Values for those variables are provided to a\nGraphQL service as part of a request so they may be substituted in during\nexecution.\n\nIn this example, we want to fetch a profile picture size based on the size of a\nparticular device:\n\n```graphql example\nquery getZuckProfile(\n \"The size of the profile picture to fetch.\"\n $devicePicSize: Int\n) {\n user(id: 4) {\n id\n name\n profilePic(size: $devicePicSize)\n }\n}\n```\n\nIf providing JSON for the variables' values, we could request a `profilePic` of\nsize `60`:\n\n```json example\n{\n \"devicePicSize\": 60\n}\n```\n\n**Variable Use Within Fragments**\n\nVariables can be used within fragments. Variables have global scope with a given\noperation, so a variable used within a fragment must be declared in any\ntop-level operation that transitively consumes that fragment. If a variable is\nreferenced in a fragment and is included by an operation that does not define\nthat variable, that operation is invalid (see\n[All Variable Uses Defined](#sec-All-Variable-Uses-Defined)).\n\n## Type References\n\nType :\n\n- NamedType\n- ListType\n- NonNullType\n\nNamedType : Name\n\nListType : [ Type ]\n\nNonNullType :\n\n- NamedType !\n- ListType !\n\nGraphQL describes the types of data expected by arguments and variables. Input\ntypes may be lists of another input type, or a non-null variant of any other\ninput type.\n\n**Semantics**\n\nType : Name\n\n- Let {name} be the string value of {Name}.\n- Let {type} be the type defined in the Schema named {name}.\n- {type} must exist.\n- Return {type}.\n\nType : [ Type ]\n\n- Let {itemType} be the result of evaluating {Type}.\n- Let {type} be a List type where {itemType} is the contained type.\n- Return {type}.\n\nType : Type !\n\n- Let {nullableType} be the result of evaluating {Type}.\n- Let {type} be a Non-Null type where {nullableType} is the contained type.\n- Return {type}.\n\n## Directives\n\nDirectives[Const] : Directive[?Const]+\n\nDirective[Const] : @ Name Arguments[?Const]?\n\nDirectives provide a way to describe alternate runtime execution and type\nvalidation behavior in a GraphQL document.\n\nIn some cases, you need to provide options to alter GraphQL's execution behavior\nin ways field arguments will not suffice, such as conditionally including or\nskipping a field. Directives provide this by describing additional information\nto the executor.\n\nDirectives have a name along with a list of arguments which may accept values of\nany input type.\n\nDirectives can be used to describe additional information for types, fields,\nfragments and operations.\n\nAs future versions of GraphQL adopt new configurable execution capabilities,\nthey may be exposed via directives. GraphQL services and tools may also provide\nany additional _custom directive_ beyond those described here.\n\n**Directive Order Is Significant**\n\nDirectives may be provided in a specific syntactic order which may have semantic\ninterpretation.\n\nThese two type definitions may have different semantic meaning:\n\n```graphql example\ntype Person\n @addExternalFields(source: \"profiles\")\n @excludeField(name: \"photo\") {\n name: String\n}\n```\n\n```graphql example\ntype Person\n @excludeField(name: \"photo\")\n @addExternalFields(source: \"profiles\") {\n name: String\n}\n```\n\n## Schema Coordinates\n\nSchemaCoordinate ::\n\n- TypeCoordinate\n- MemberCoordinate\n- ArgumentCoordinate\n- DirectiveCoordinate\n- DirectiveArgumentCoordinate\n\nTypeCoordinate :: Name\n\nMemberCoordinate :: Name . Name\n\nArgumentCoordinate :: Name . Name ( Name : )\n\nDirectiveCoordinate :: @ Name\n\nDirectiveArgumentCoordinate :: @ Name ( Name : )\n\n:: A _schema coordinate_ is a human readable string that uniquely identifies a\n_schema element_ within a GraphQL Schema, intended to be used by tools to\nreference types, fields, and other _schema element_. Examples include:\nreferences within documentation to refer to types and fields in a schema, a\nlookup key that can be used in logging tools to track how often particular\nfields are queried in production.\n\n:: A _schema element_ can be a named type, a field, an input field, an enum\nvalue, a field argument, a directive, or a directive argument defined within a\nschema (including built-in types and directives).\n\nNote: Meta-fields are not defined within a schema, and thus are not _schema\nelement_. By extension, an introspection type is not a _schema element_.\n\n:: The _containing element_ of a _schema element_ is the schema element with one\nfewer {Name} token that syntactically contains it. Specifically:\n\n- The containing element of an {ArgumentCoordinate} is a {MemberCoordinate}.\n- The containing element of a {MemberCoordinate} is a {TypeCoordinate}.\n- The containing element of a {DirectiveArgumentCoordinate} is a\n {DirectiveCoordinate}.\n- {TypeCoordinate} and {DirectiveCoordinate} have no containing element.\n\nA _schema coordinate_ is always unique. Each _schema element_ can be referenced\nby exactly one possible schema coordinate.\n\nA _schema coordinate_ may refer to either a defined or built-in _schema\nelement_. For example, `String` and `@deprecated(reason:)` are both valid schema\ncoordinates which refer to built-in schema elements.\n\nNote: A union member references a type in the schema. A type in the schema is\nidentified by a {TypeCoordinate}. There is no schema coordinate which indicates\na union member; this preserves the uniqueness property of a _schema coordinate_\nas stated above.\n\n**Parsing a Schema Coordinate**\n\nSchemaCoordinateToken ::\n\n- SchemaCoordinatePunctuator\n- Name\n\nSchemaCoordinatePunctuator :: one of ( ) . : @\n\nA {SchemaCoordinate} is a self-contained grammar with its own set of lexical\ntokens, it is not contained within a {Document}. The source text of a\nSchemaCoordinate must be a sequence of {SourceCharacter}.\n\nUnlike other [GraphQL documents](#sec-Language), {SchemaCoordinate} must not\ncontain {Whitespace} or other {Ignored} grammars within the character sequence.\nThis ensures that every schema coordinates has a single unambiguous and unique\nlexical form.\n\n**Resolving a Schema Coordinate**\n\nTo refer to a _schema element_, a _schema coordinate_ must be interpreted in the\ncontext of a GraphQL {schema}.\n\nIf the _schema element_ cannot be found, the resolve function will not yield a\nvalue (without raising an error). However, an error will be raised if any\nnon-leaf nodes within a _schema coordinate_ cannot be found in the {schema}.\n\nNote: Although it is syntactically possible to describe a meta-field or element\nof the introspection schema with a schema coordinate (e.g. `Business.__typename`\nor `__Type.fields(includeDeprecated:)`), they are not _schema element_ and\ntherefore resolving such coordinates does not have a defined behavior.\n\nTypeCoordinate :: Name\n\n1. Let {typeName} be the value of {Name}.\n2. Return the type in {schema} named {typeName} if it exists.\n\nMemberCoordinate :: Name . Name\n\n1. Let {typeName} be the value of the first {Name}.\n2. Let {type} be the type in {schema} named {typeName}.\n3. Assert: {type} must exist, and must be an Enum, Input Object, Object or\n Interface type.\n4. If {type} is an Enum type:\n 1. Let {enumValueName} be the value of the second {Name}.\n 2. Return the enum value of {type} named {enumValueName} if it exists.\n5. Otherwise, if {type} is an Input Object type:\n 1. Let {inputFieldName} be the value of the second {Name}.\n 2. Return the input field of {type} named {inputFieldName} if it exists.\n6. Otherwise:\n 1. Let {fieldName} be the value of the second {Name}.\n 2. Return the field of {type} named {fieldName} if it exists.\n\nArgumentCoordinate :: Name . Name ( Name : )\n\n1. Let {typeName} be the value of the first {Name}.\n2. Let {type} be the type in {schema} named {typeName}.\n3. Assert: {type} must exist, and be an Object or Interface type.\n4. Let {fieldName} be the value of the second {Name}.\n5. Let {field} be the field of {type} named {fieldName}.\n6. Assert: {field} must exist.\n7. Let {fieldArgumentName} be the value of the third {Name}.\n8. Return the argument of {field} named {fieldArgumentName} if it exists.\n\nDirectiveCoordinate :: @ Name\n\n1. Let {directiveName} be the value of {Name}.\n2. Return the directive in {schema} named {directiveName} if it exists.\n\nDirectiveArgumentCoordinate :: @ Name ( Name : )\n\n1. Let {directiveName} be the value of the first {Name}.\n2. Let {directive} be the directive in {schema} named {directiveName}.\n3. Assert: {directive} must exist.\n4. Let {directiveArgumentName} be the value of the second {Name}.\n5. Return the argument of {directive} named {directiveArgumentName} if it\n exists.\n\n**Examples**\n\n| Element Kind | Schema Coordinate | Schema Element |\n| ------------------ | --------------------------------- | --------------------------------------------------------------------- |\n| Named Type | `Business` | `Business` type |\n| Field | `Business.name` | `name` field on the `Business` type |\n| Input Field | `SearchCriteria.filter` | `filter` input field on the `SearchCriteria` input object type |\n| Enum Value | `SearchFilter.OPEN_NOW` | `OPEN_NOW` value of the `SearchFilter` enum |\n| Field Argument | `Query.searchBusiness(criteria:)` | `criteria` argument on the `searchBusiness` field on the `Query` type |\n| Directive | `@private` | `@private` directive |\n| Directive Argument | `@private(scope:)` | `scope` argument on the `@private` directive |\n\nThe table above shows an example of a _schema coordinate_ for every kind of\n_schema element_ based on the schema below.\n\n```graphql\ntype Query {\n searchBusiness(criteria: SearchCriteria!): [Business]\n}\n\ninput SearchCriteria {\n name: String\n filter: SearchFilter\n}\n\nenum SearchFilter {\n OPEN_NOW\n DELIVERS_TAKEOUT\n VEGETARIAN_MENU\n}\n\ntype Business {\n id: ID\n name: String\n email: String @private(scope: \"loggedIn\")\n}\n\ndirective @private(scope: String!) on FIELD_DEFINITION\n```\n" }, { "path": "spec/Section 3 -- Type System.md", "content": "# Type System\n\nThe GraphQL Type system describes the capabilities of a GraphQL service and is\nused to determine if a requested operation is valid, to guarantee the type of\nresponse results, and describes the input types of variables to determine if\nvalues provided at request time are valid.\n\nTypeSystemDocument : TypeSystemDefinition+\n\nTypeSystemDefinition :\n\n- SchemaDefinition\n- TypeDefinition\n- DirectiveDefinition\n\nThe GraphQL language includes an\n[IDL](https://en.wikipedia.org/wiki/Interface_description_language) used to\ndescribe a GraphQL service's type system. Tools may use this definition language\nto provide utilities such as client code generation or service bootstrapping.\n\nGraphQL tools or services which only seek to execute GraphQL requests and not\nconstruct a new GraphQL schema may choose not to allow {TypeSystemDefinition}.\nTools which only seek to produce schema and not execute requests may choose to\nonly allow {TypeSystemDocument} and not allow {ExecutableDefinition} or\n{TypeSystemExtension} but should provide a descriptive error if present.\n\nNote: The type system definition language is used throughout the remainder of\nthis specification document when illustrating example type systems.\n\n## Type System Extensions\n\nTypeSystemExtensionDocument : TypeSystemDefinitionOrExtension+\n\nTypeSystemDefinitionOrExtension :\n\n- TypeSystemDefinition\n- TypeSystemExtension\n\nTypeSystemExtension :\n\n- SchemaExtension\n- TypeExtension\n\nType system extensions are used to represent a GraphQL type system which has\nbeen extended from some previous type system. For example, this might be used by\na local service to represent data a GraphQL client only accesses locally, or by\na GraphQL service which is itself an extension of another GraphQL service.\n\nTools which only seek to produce and extend schema and not execute requests may\nchoose to only allow {TypeSystemExtensionDocument} and not allow\n{ExecutableDefinition} but should provide a descriptive error if present.\n\n## Type System Descriptions\n\nDocumentation is a first-class feature of GraphQL type systems, written\nimmediately alongside definitions in a {TypeSystemDocument} and made available\nvia introspection.\n\n[Descriptions](#sec-Descriptions) allow GraphQL service designers to easily\nprovide documentation which remains consistent with the capabilities of a\nGraphQL service. Descriptions should be provided as Markdown (as specified by\n[CommonMark](https://commonmark.org/)) for every definition in a type system.\n\nGraphQL schema and all other definitions (e.g. types, fields, arguments, etc.)\nwhich can be described should provide a {Description} unless they are considered\nself descriptive.\n\nAs an example, this simple GraphQL schema is well described:\n\n```raw graphql example\n\"\"\"\nA simple GraphQL schema which is well described.\n\"\"\"\nschema {\n query: Query\n}\n\n\"\"\"\nRoot type for all your query operations\n\"\"\"\ntype Query {\n \"\"\"\n Translates a string from a given language into a different language.\n \"\"\"\n translate(\n \"The original language that `text` is provided in.\"\n fromLanguage: Language\n\n \"The translated language to be returned.\"\n toLanguage: Language\n\n \"The text to be translated.\"\n text: String\n ): String\n}\n\n\"\"\"\nThe set of languages supported by `translate`.\n\"\"\"\nenum Language {\n \"English\"\n EN\n\n \"French\"\n FR\n\n \"Chinese\"\n CH\n}\n```\n\n## Schema\n\nSchemaDefinition : Description? schema Directives[Const]? {\nRootOperationTypeDefinition+ }\n\nRootOperationTypeDefinition : OperationType : NamedType\n\nA GraphQL service's collective type system capabilities are referred to as that\nservice's \"schema\". A schema is defined in terms of the types and directives it\nsupports as well as the _root operation type_ for each kind of operation: query,\nmutation, and subscription; this determines the place in the type system where\nthose operations begin.\n\nA GraphQL schema must itself be internally valid. This section describes the\nrules for this validation process where relevant.\n\nAll types within a GraphQL schema must have unique names. No two provided types\nmay have the same name. No provided type may have a name which conflicts with\nany built in types (including Scalar and Introspection types).\n\nAll directives within a GraphQL schema must have unique names.\n\nAll types and directives defined within a schema must not have a name which\nbegins with {\"\\_\\_\"} (two underscores), as this is used exclusively by GraphQL's\nintrospection system.\n\n### Root Operation Types\n\n:: A schema defines the initial _root operation type_ for each kind of operation\nit supports: query, mutation, and subscription; this determines the place in the\ntype system where those operations begin.\n\nThe {`query`} _root operation type_ must be provided and must be an Object type.\n\nThe {`mutation`} _root operation type_ is optional; if it is not provided, the\nservice does not support mutations. If it is provided, it must be an Object\ntype.\n\nSimilarly, the {`subscription`} _root operation type_ is also optional; if it is\nnot provided, the service does not support subscriptions. If it is provided, it\nmust be an Object type.\n\nThe {`query`}, {`mutation`}, and {`subscription`} root types must all be\ndifferent types if provided.\n\nThe fields on the {`query`} _root operation type_ indicate what fields are\navailable at the top level of a GraphQL query operation.\n\nFor example, this example operation:\n\n```graphql example\nquery {\n myName\n}\n```\n\nis only valid when the {`query`} _root operation type_ has a field named\n\"myName\":\n\n```graphql example\ntype Query {\n myName: String\n}\n```\n\nSimilarly, the following mutation is only valid if the {`mutation`} _root\noperation type_ has a field named \"setName\".\n\n```graphql example\nmutation {\n setName(name: \"Zuck\") {\n newName\n }\n}\n```\n\nWhen using the type system definition language, a document must include at most\none {`schema`} definition.\n\nIn this example, a GraphQL schema is defined with both a query and mutation\n_root operation type_:\n\n```graphql example\nschema {\n query: MyQueryRootType\n mutation: MyMutationRootType\n}\n\ntype MyQueryRootType {\n someField: String\n}\n\ntype MyMutationRootType {\n setSomeField(to: String): String\n}\n```\n\n**Default Root Operation Type Names**\n\n:: The _default root type name_ for each {`query`}, {`mutation`}, and\n{`subscription`} _root operation type_ are {\"Query\"}, {\"Mutation\"}, and\n{\"Subscription\"} respectively.\n\nThe type system definition language can omit the schema definition when each\n_root operation type_ uses its respective _default root type name_, no other\ntype uses any _default root type name_, and the schema does not have a\ndescription.\n\nLikewise, when representing a GraphQL schema using the type system definition\nlanguage, a schema definition should be omitted if each _root operation type_\nuses its respective _default root type name_, no other type uses any _default\nroot type name_, and the schema does not have a description.\n\nThis example describes a valid complete GraphQL schema, despite not explicitly\nincluding a {`schema`} definition. The {\"Query\"} type is presumed to be the\n{`query`} _root operation type_ of the schema.\n\n```graphql example\ntype Query {\n someField: String\n}\n```\n\nThis example describes a valid GraphQL schema without a {`mutation`} _root\noperation type_, even though it contains a type named {\"Mutation\"}. The schema\ndefinition must be included, otherwise the {\"Mutation\"} type would be\nincorrectly presumed to be the {`mutation`} _root operation type_ of the schema.\n\n```graphql example\nschema {\n query: Query\n}\n\ntype Query {\n latestVirus: Virus\n}\n\ntype Virus {\n name: String\n mutations: [Mutation]\n}\n\ntype Mutation {\n name: String\n}\n```\n\nThis example describes a valid GraphQL schema with a description and both a\n{`query`} and {`mutation`} operation type:\n\n```graphql example\n\"\"\"\nExample schema\n\"\"\"\nschema {\n query: Query\n mutation: Mutation\n}\n\ntype Query {\n someField: String\n}\n\ntype Mutation {\n someMutation: String\n}\n```\n\n### Schema Extension\n\nSchemaExtension :\n\n- extend schema Directives[Const]? { RootOperationTypeDefinition+ }\n- extend schema Directives[Const] [lookahead != `{`]\n\nSchema extensions are used to represent a schema which has been extended from a\nprevious schema. For example, this might be used by a GraphQL service which adds\nadditional operation types, or additional directives to an existing schema.\n\nNote: Schema extensions without additional operation type definitions must not\nbe followed by a {`{`} (such as a query shorthand) to avoid parsing ambiguity.\nThe same limitation applies to the type definitions and extensions below.\n\n**Schema Validation**\n\nSchema extensions have the potential to be invalid if incorrectly defined.\n\n1. The Schema must already be defined.\n2. Any non-repeatable directives provided must not already apply to the previous\n Schema.\n\n## Types\n\nTypeDefinition :\n\n- ScalarTypeDefinition\n- ObjectTypeDefinition\n- InterfaceTypeDefinition\n- UnionTypeDefinition\n- EnumTypeDefinition\n- InputObjectTypeDefinition\n\nThe fundamental unit of any GraphQL Schema is the type. There are six kinds of\nnamed type definitions in GraphQL, and two wrapping types.\n\nThe most basic type is a `Scalar`. A scalar represents a primitive value, like a\nstring or an integer. Oftentimes, the possible responses for a scalar field are\nenumerable. GraphQL offers an `Enum` type in those cases, where the type\nspecifies the space of valid responses.\n\nScalars and Enums form the leaves in response trees; the intermediate levels are\n`Object` types, which define a set of fields, where each field is another type\nin the system, allowing the definition of arbitrary type hierarchies.\n\nGraphQL supports two abstract types: interfaces and unions.\n\nAn `Interface` defines a list of fields; `Object` types and other Interface\ntypes which implement this Interface are guaranteed to implement those fields.\nWhenever a field claims it will return an Interface type, it will return a valid\nimplementing Object type during execution.\n\nA `Union` defines a list of possible types; similar to interfaces, whenever the\ntype system claims a union will be returned, one of the possible types will be\nreturned.\n\nFinally, oftentimes it is useful to provide complex structs as inputs to GraphQL\nfield arguments or variables; the `Input Object` type allows the schema to\ndefine exactly what data is expected.\n\n### Wrapping Types\n\nAll of the types so far are assumed to be both nullable and singular: e.g. a\nscalar string returns either null or a singular string.\n\nA GraphQL schema may describe that a field represents a list of another type;\nthe `List` type is provided for this reason, and wraps another type.\n\nSimilarly, the `Non-Null` type wraps another type, and denotes that the\nresulting value will never be {null} (and that an _execution error_ cannot\nresult in a {null} value).\n\nThese two types are referred to as \"wrapping types\"; non-wrapping types are\nreferred to as \"named types\". A wrapping type has an underlying named type,\nfound by continually unwrapping the type until a named type is found.\n\n### Input and Output Types\n\nTypes are used throughout GraphQL to describe both the values accepted as input\nto arguments and variables as well as the values output by fields. These two\nuses categorize types as _input types_ and _output types_. Some kinds of types,\nlike Scalar and Enum types, can be used as both input types and output types;\nother kinds of types can only be used in one or the other. Input Object types\ncan only be used as input types. Object, Interface, and Union types can only be\nused as output types. Lists and Non-Null types may be used as input types or\noutput types depending on how the wrapped type may be used.\n\nIsInputType(type):\n\n- If {type} is a List type or Non-Null type:\n - Let {unwrappedType} be the unwrapped type of {type}.\n - Return {IsInputType(unwrappedType)}.\n- If {type} is a Scalar, Enum, or Input Object type:\n - Return {true}.\n- Return {false}.\n\nIsOutputType(type):\n\n- If {type} is a List type or Non-Null type:\n - Let {unwrappedType} be the unwrapped type of {type}.\n - Return {IsOutputType(unwrappedType)}.\n- If {type} is a Scalar, Object, Interface, Union, or Enum type:\n - Return {true}.\n- Return {false}.\n\n### Type Extensions\n\nTypeExtension :\n\n- ScalarTypeExtension\n- ObjectTypeExtension\n- InterfaceTypeExtension\n- UnionTypeExtension\n- EnumTypeExtension\n- InputObjectTypeExtension\n\nType extensions are used to represent a GraphQL type which has been extended\nfrom some previous type. For example, this might be used by a local service to\nrepresent additional fields a GraphQL client only accesses locally.\n\n## Scalars\n\nScalarTypeDefinition : Description? scalar Name Directives[Const]?\n\nScalar types represent primitive leaf values in a GraphQL type system. GraphQL\nresponses take the form of a hierarchical tree; the leaves of this tree are\ntypically GraphQL Scalar types (but may also be Enum types or {null} values).\n\nGraphQL provides a number of built-in scalars which are fully defined in the\nsections below, however type systems may also add additional custom scalars to\nintroduce additional semantic meaning.\n\n**Built-in Scalars**\n\nGraphQL specifies a basic set of well-defined Scalar types: {Int}, {Float},\n{String}, {Boolean}, and {ID}. A GraphQL framework should support all of these\ntypes, and a GraphQL service which provides a type by these names must adhere to\nthe behavior described for them in this document. As an example, a service must\nnot include a type called {Int} and use it to represent 64-bit numbers,\ninternationalization information, or anything other than what is defined in this\ndocument.\n\nWhen returning the set of types from the `__Schema` introspection type, all\nreferenced built-in scalars must be included. If a built-in scalar type is not\nreferenced anywhere in a schema (there is no field, argument, or input field of\nthat type) then it must not be included.\n\nWhen representing a GraphQL schema using the type system definition language,\nall built-in scalars must be omitted for brevity.\n\n**Custom Scalars**\n\nGraphQL services may use custom scalar types in addition to the built-in\nscalars. For example, a GraphQL service could define a scalar called `UUID`\nwhich, while serialized as a string, conforms to\n[RFC 4122](https://tools.ietf.org/html/rfc4122). When querying a field of type\n`UUID`, you can then rely on the ability to parse the result with an RFC 4122\ncompliant parser. Another example of a potentially useful custom scalar is\n`URL`, which serializes as a string, but is guaranteed by the service to be a\nvalid URL.\n\n:: When defining a custom scalar, GraphQL services should provide a _scalar\nspecification URL_ via the `@specifiedBy` directive or the `specifiedByURL`\nintrospection field. This URL must link to a human-readable specification of the\ndata format, serialization, and coercion rules for the scalar.\n\nFor example, a GraphQL service providing a `UUID` scalar may link to RFC 4122,\nor some custom document defining a reasonable subset of that RFC. If a _scalar\nspecification URL_ is present, systems and tools that are aware of it should\nconform to its described rules.\n\n```graphql example\nscalar UUID @specifiedBy(url: \"https://tools.ietf.org/html/rfc4122\")\nscalar URL @specifiedBy(url: \"https://tools.ietf.org/html/rfc3986\")\nscalar DateTime\n @specifiedBy(url: \"https://scalars.graphql.org/andimarek/date-time\")\n```\n\nCustom *scalar specification URL*s should provide a single, stable format to\navoid ambiguity. If the linked specification is in flux, the service should link\nto a fixed version rather than to a resource which might change.\n\nNote: Some community-maintained custom scalar specifications are hosted at\n[scalars.graphql.org](https://scalars.graphql.org/).\n\nCustom *scalar specification URL*s should not be changed once defined. Doing so\nwould likely disrupt tooling or could introduce breaking changes within the\nlinked specification's contents.\n\nBuilt-in scalar types must not provide a _scalar specification URL_ as they are\nspecified by this document.\n\nNote: Custom scalars should also summarize the specified format and provide\nexamples in their description; see the GraphQL scalars\n[implementation guide](https://scalars.graphql.org/implementation-guide) for\nmore guidance.\n\n**Result Coercion and Serialization**\n\nA GraphQL service, when preparing a field of a given scalar type, must uphold\nthe contract the scalar type describes, either by coercing the value or\nproducing an _execution error_ if a value cannot be coerced or if coercion may\nresult in data loss.\n\nA GraphQL service may decide to allow coercing different internal types to the\nexpected return type. For example when coercing a field of type {Int} a boolean\n{true} value may produce {1} or a string value {\"123\"} may be parsed as base-10\n{123}. However if internal type coercion cannot be reasonably performed without\nlosing information, then it must raise an _execution error_.\n\nSince this coercion behavior is not observable to clients of the GraphQL\nservice, the precise rules of coercion are left to the implementation. The only\nrequirement is that the service must yield values which adhere to the expected\nScalar type.\n\nGraphQL scalars are serialized according to the serialization format being used.\nThere may be a most appropriate serialized primitive for each given scalar type,\nand the service should produce each primitive where appropriate.\n\nSee [Serialization Format](#sec-Serialization-Format) for more detailed\ninformation on the serialization of scalars in common JSON and other formats.\n\n**Input Coercion**\n\nIf a GraphQL service expects a scalar type as input to an argument, coercion is\nobservable and the rules must be well defined. If an input value does not match\na coercion rule, a _request error_ must be raised (input values are validated\nbefore execution begins).\n\nGraphQL has different constant literals to represent integer and floating-point\ninput values, and coercion rules may apply differently depending on which type\nof input value is encountered. GraphQL may be parameterized by variables, the\nvalues of which are often serialized when sent over a transport like HTTP. Since\nsome common serializations (e.g. JSON) do not discriminate between integer and\nfloating-point values, they are interpreted as an integer input value if they\nhave an empty fractional part (e.g. `1.0`) and otherwise as floating-point input\nvalue.\n\nFor all types below, with the exception of Non-Null, if the explicit value\n{null} is provided, then the result of input coercion is {null}.\n\n### Int\n\nThe Int scalar type represents a signed 32-bit numeric non-fractional value.\nResponse formats that support a 32-bit integer or a number type should use that\ntype to represent this scalar.\n\n**Result Coercion**\n\nFields returning the type {Int} expect to encounter 32-bit integer internal\nvalues.\n\nGraphQL services may coerce non-integer internal values to integers when\nreasonable without losing information, otherwise they must raise an _execution\nerror_. Examples of this may include returning `1` for the floating-point number\n`1.0`, or returning `123` for the string `\"123\"`. In scenarios where coercion\nmay lose data, raising an execution error is more appropriate. For example, a\nfloating-point number `1.2` should raise an execution error instead of being\ntruncated to `1`.\n\nIf the integer internal value represents a value less than -231 or\ngreater than or equal to 231, an _execution error_ should be raised.\n\n**Input Coercion**\n\nWhen expected as an input type, only integer input values are accepted. All\nother input values, including strings with numeric content, must raise a request\nerror indicating an incorrect type. If the integer input value represents a\nvalue less than -231 or greater than or equal to 231, a\n_request error_ should be raised.\n\nNote: Numeric integer values larger than 32-bit should either use String or a\ncustom-defined Scalar type, as not all platforms and transports support encoding\ninteger numbers larger than 32-bit.\n\n### Float\n\nThe Float scalar type represents signed double-precision finite values as\nspecified by [IEEE 754](https://en.wikipedia.org/wiki/IEEE_floating_point).\nResponse formats that support an appropriate double-precision number type should\nuse that type to represent this scalar.\n\n**Result Coercion**\n\nFields returning the type {Float} expect to encounter double-precision\nfloating-point internal values.\n\nGraphQL services may coerce non-floating-point internal values to {Float} when\nreasonable without losing information, otherwise they must raise an _execution\nerror_. Examples of this may include returning `1.0` for the integer number `1`,\nor `123.0` for the string `\"123\"`.\n\nNon-finite floating-point internal values ({NaN} and {Infinity}) cannot be\ncoerced to {Float} and must raise an _execution error_.\n\n**Input Coercion**\n\nWhen expected as an input type, both integer and float input values are\naccepted. Integer input values are coerced to Float by adding an empty\nfractional part, for example `1.0` for the integer input value `1`. All other\ninput values, including strings with numeric content, must raise a _request\nerror_ indicating an incorrect type. If the input value otherwise represents a\nvalue not representable by finite IEEE 754 (e.g. {NaN}, {Infinity}, or a value\noutside the available precision), a _request error_ must be raised.\n\n### String\n\nThe String scalar type represents textual data, represented as a sequence of\nUnicode code points. The String type is most often used by GraphQL to represent\nfree-form human-readable text. How the String is encoded internally (for example\nUTF-8) is left to the service implementation. All response serialization formats\nmust support a string representation (for example, JSON Unicode strings), and\nthat representation must be used to serialize this type.\n\n**Result Coercion**\n\nFields returning the type {String} expect to encounter Unicode string values.\n\nGraphQL services may coerce non-string raw values to {String} when reasonable\nwithout losing information, otherwise they must raise an _execution error_.\nExamples of this may include returning the string `\"true\"` for a boolean true\nvalue, or the string `\"1\"` for the integer `1`.\n\n**Input Coercion**\n\nWhen expected as an input type, only valid Unicode string input values are\naccepted. All other input values must raise a _request error_ indicating an\nincorrect type.\n\n### Boolean\n\nThe Boolean scalar type represents `true` or `false`. Response formats should\nuse a built-in boolean type if supported; otherwise, they should use their\nrepresentation of the integers `1` and `0`.\n\n**Result Coercion**\n\nFields returning the type {Boolean} expect to encounter boolean internal values.\n\nGraphQL services may coerce non-boolean raw values to {Boolean} when reasonable\nwithout losing information, otherwise they must raise an _execution error_.\nExamples of this may include returning `true` for non-zero numbers.\n\n**Input Coercion**\n\nWhen expected as an input type, only boolean input values are accepted. All\nother input values must raise a _request error_ indicating an incorrect type.\n\n### ID\n\nThe ID scalar type represents a unique identifier, often used to refetch an\nobject or as the key for a cache. The ID type is serialized in the same way as a\n{String}; however, it is not intended to be human-readable. While it is often\nnumeric, it must always serialize as a {String}.\n\n**Result Coercion**\n\nGraphQL is agnostic to ID format, and serializes to string to ensure consistency\nacross many formats ID could represent, from small auto-increment numbers, to\nlarge 128-bit random numbers, to base64 encoded values, or string values of a\nformat like [GUID](https://en.wikipedia.org/wiki/Globally_unique_identifier).\n\nGraphQL services should coerce as appropriate given the ID formats they expect.\nWhen coercion is not possible they must raise an _execution error_.\n\n**Input Coercion**\n\nWhen expected as an input type, any string (such as `\"4\"`) or integer (such as\n`4` or `-4`) input value should be coerced to ID as appropriate for the ID\nformats a given GraphQL service expects. Any other input value, including float\ninput values (such as `4.0`), must raise a _request error_ indicating an\nincorrect type.\n\n### Scalar Extensions\n\nScalarTypeExtension :\n\n- extend scalar Name Directives[Const]\n\nScalar type extensions are used to represent a scalar type which has been\nextended from some previous scalar type. For example, this might be used by a\nGraphQL tool or service which adds directives to an existing scalar.\n\n**Type Validation**\n\nScalar type extensions have the potential to be invalid if incorrectly defined.\n\n1. The named type must already be defined and must be a Scalar type.\n2. Any non-repeatable directives provided must not already apply to the previous\n Scalar type.\n\n## Objects\n\nObjectTypeDefinition :\n\n- Description? type Name ImplementsInterfaces? Directives[Const]?\n FieldsDefinition\n- Description? type Name ImplementsInterfaces? Directives[Const]? [lookahead !=\n `{`]\n\nImplementsInterfaces :\n\n- ImplementsInterfaces & NamedType\n- implements `&`? NamedType\n\nFieldsDefinition : { FieldDefinition+ }\n\nFieldDefinition : Description? Name ArgumentsDefinition? : Type\nDirectives[Const]?\n\nGraphQL operations are hierarchical and composed, describing a tree of\ninformation. While Scalar types describe the leaf values of these hierarchical\noperations, Objects describe the intermediate levels.\n\nGraphQL Objects represent a list of named fields, each of which yields a value\nof a specific type. Object values should be serialized as ordered maps, where\nthe selected field names (or aliases) are the keys and the result of evaluating\nthe field is the value, ordered by the order in which they appear in the\n_selection set_.\n\nAll fields defined within an Object type must not have a name which begins with\n{\"\\_\\_\"} (two underscores), as this is used exclusively by GraphQL's\nintrospection system.\n\nFor example, a type `Person` could be described as:\n\n```graphql example\ntype Person {\n name: String\n age: Int\n picture: Url\n}\n```\n\nWhere `name` is a field that will yield a {String} value, and `age` is a field\nthat will yield an {Int} value, and `picture` is a field that will yield a `Url`\nvalue.\n\nA query of an object value must select at least one field. This selection of\nfields will yield an ordered map containing exactly the subset of the object\nqueried, which should be represented in the order in which they were queried.\nOnly fields that are declared on the object type may validly be queried on that\nobject.\n\nFor example, selecting all the fields of `Person`:\n\n```graphql example\n{\n name\n age\n picture\n}\n```\n\nWould yield the object:\n\n```json example\n{\n \"name\": \"Mark Zuckerberg\",\n \"age\": 30,\n \"picture\": \"http://some.cdn/picture.jpg\"\n}\n```\n\nWhile selecting a subset of fields:\n\n```graphql example\n{\n age\n name\n}\n```\n\nMust only yield exactly that subset:\n\n```json example\n{\n \"age\": 30,\n \"name\": \"Mark Zuckerberg\"\n}\n```\n\nA field of an Object type may be a Scalar, Enum, another Object type, an\nInterface, or a Union. Additionally, it may be any wrapping type whose\nunderlying base type is one of those five.\n\nFor example, the `Person` type might include a `relationship`:\n\n```graphql example\ntype Person {\n name: String\n age: Int\n picture: Url\n relationship: Person\n}\n```\n\nValid operations must supply a _selection set_ for every field whose return type\nis an object type, so this operation is not valid:\n\n```graphql counter-example\n{\n name\n relationship\n}\n```\n\nHowever, this example is valid:\n\n```graphql example\n{\n name\n relationship {\n name\n }\n}\n```\n\nAnd will yield the subset of each object type queried:\n\n```json example\n{\n \"name\": \"Mark Zuckerberg\",\n \"relationship\": {\n \"name\": \"Priscilla Chan\"\n }\n}\n```\n\n**Field Ordering**\n\nWhen querying an Object, the resulting mapping of fields are conceptually\nordered in the same order in which they were encountered during execution,\nexcluding fragments for which the type does not apply and fields or fragments\nthat are skipped via `@skip` or `@include` directives. This ordering is\ncorrectly produced when using the {CollectFields()} algorithm.\n\nResponse serialization formats capable of representing ordered maps should\nmaintain this ordering. Serialization formats which can only represent unordered\nmaps (such as JSON) should retain this order textually. That is, if two fields\n`{foo, bar}` were queried in that order, the resulting JSON serialization should\ncontain `{\"foo\": \"...\", \"bar\": \"...\"}` in the same order.\n\nProducing a response where fields are represented in the same order in which\nthey appear in the request improves human readability during debugging and\nenables more efficient parsing of responses if the order of properties can be\nanticipated.\n\nIf a fragment is spread before other fields, the fields that fragment specifies\noccur in the response before the following fields.\n\n```graphql example\n{\n foo\n ...Frag\n qux\n}\n\nfragment Frag on Query {\n bar\n baz\n}\n```\n\nProduces the ordered result:\n\n```json example\n{\n \"foo\": 1,\n \"bar\": 2,\n \"baz\": 3,\n \"qux\": 4\n}\n```\n\nIf a field is queried multiple times in a selection, it is ordered by the first\ntime it is encountered. However fragments for which the type does not apply do\nnot affect ordering.\n\n```graphql example\n{\n foo\n ...Ignored\n ...Matching\n bar\n}\n\nfragment Ignored on UnknownType {\n qux\n baz\n}\n\nfragment Matching on Query {\n bar\n qux\n foo\n}\n```\n\nProduces the ordered result:\n\n```json example\n{\n \"foo\": 1,\n \"bar\": 2,\n \"qux\": 3\n}\n```\n\nAlso, if directives result in fields being excluded, they are not considered in\nthe ordering of fields.\n\n```graphql example\n{\n foo @skip(if: true)\n bar\n foo\n}\n```\n\nProduces the ordered result:\n\n```json example\n{\n \"bar\": 1,\n \"foo\": 2\n}\n```\n\n**Result Coercion**\n\nDetermining the result of coercing an object is the heart of the GraphQL\nexecutor, see [Value Completion](#sec-Value-Completion).\n\n**Input Coercion**\n\nObjects are never valid inputs.\n\n**Type Validation**\n\nObject types have the potential to be invalid if incorrectly defined. This set\nof rules must be adhered to by every Object type in a GraphQL schema.\n\n1. An Object type must define one or more fields.\n2. For each field of an Object type:\n 1. The field must have a unique name within that Object type; no two fields\n may share the same name.\n 2. The field must not have a name which begins with the characters {\"\\_\\_\"}\n (two underscores).\n 3. The field must return a type where {IsOutputType(fieldType)} returns\n {true}.\n 4. For each argument of the field:\n 1. The argument must not have a name which begins with the characters\n {\"\\_\\_\"} (two underscores).\n 2. The argument must have a unique name within that field; no two\n arguments may share the same name.\n 3. The argument must accept a type where {IsInputType(argumentType)}\n returns {true}.\n 4. If argument type is Non-Null and a default value is not defined:\n 1. The `@deprecated` directive must not be applied to this argument.\n 5. If the argument has a default value it must be compatible with\n {argumentType} as per the coercion rules for that type.\n3. An object type may declare that it implements one or more unique interfaces.\n4. An object type must be a super-set of all interfaces it implements:\n 1. Let this object type be {objectType}.\n 2. For each interface declared implemented as {interfaceType},\n {IsValidImplementation(objectType, interfaceType)} must be {true}.\n\nIsValidImplementation(type, implementedType):\n\n1. If {implementedType} declares it implements any interfaces, {type} must also\n declare it implements those interfaces.\n2. {type} must include a field of the same name for every field defined in\n {implementedType}.\n 1. Let {field} be that named field on {type}.\n 2. Let {implementedField} be that named field on {implementedType}.\n 3. {field} must include an argument of the same name for every argument\n defined in {implementedField}.\n 1. That named argument on {field} must accept the same type (invariant)\n as that named argument on {implementedField}.\n 4. {field} may include additional arguments not defined in\n {implementedField}, but any additional argument must not be required,\n e.g. must not be of a non-nullable type.\n 5. {field} must return a type which is equal to or a sub-type of (covariant)\n the return type of {implementedField} field's return type:\n 1. Let {fieldType} be the return type of {field}.\n 2. Let {implementedFieldType} be the return type of {implementedField}.\n 3. {IsValidImplementationFieldType(fieldType, implementedFieldType)} must\n be {true}.\n 6. If {field} is deprecated then {implementedField} must also be deprecated.\n\nIsValidImplementationFieldType(fieldType, implementedFieldType):\n\n1. If {fieldType} is a Non-Null type:\n 1. Let {nullableType} be the unwrapped nullable type of {fieldType}.\n 2. Let {implementedNullableType} be the unwrapped nullable type of\n {implementedFieldType} if it is a Non-Null type, otherwise let it be\n {implementedFieldType} directly.\n 3. Return {IsValidImplementationFieldType(nullableType,\n implementedNullableType)}.\n2. If {fieldType} is a List type and {implementedFieldType} is also a List type:\n 1. Let {itemType} be the unwrapped item type of {fieldType}.\n 2. Let {implementedItemType} be the unwrapped item type of\n {implementedFieldType}.\n 3. Return {IsValidImplementationFieldType(itemType, implementedItemType)}.\n3. Return {IsSubType(fieldType, implementedFieldType)}.\n\nIsSubType(possibleSubType, superType):\n\n1. If {possibleSubType} is the same type as {superType} then return {true}.\n2. If {possibleSubType} is an Object type and {superType} is a Union type and\n {possibleSubType} is a possible type of {superType} then return {true}.\n3. If {possibleSubType} is an Object or Interface type and {superType} is an\n Interface type and {possibleSubType} declares it implements {superType} then\n return {true}.\n4. Otherwise return {false}.\n\n### Field Arguments\n\nArgumentsDefinition : ( InputValueDefinition+ )\n\nInputValueDefinition : Description? Name : Type DefaultValue? Directives[Const]?\n\nObject fields are conceptually functions which yield values. Occasionally object\nfields can accept arguments to further specify the return value. Object field\narguments are defined as a list of all possible argument names and their\nexpected input types.\n\nAll arguments defined within a field must not have a name which begins with\n{\"\\_\\_\"} (two underscores), as this is used exclusively by GraphQL's\nintrospection system.\n\nFor example, a `Person` type with a `picture` field could accept an argument to\ndetermine what size of an image to return.\n\n```graphql example\ntype Person {\n name: String\n picture(size: Int): Url\n}\n```\n\nOperations can optionally specify arguments to their fields to provide these\narguments.\n\nThis example operation:\n\n```graphql example\n{\n name\n picture(size: 600)\n}\n```\n\nMay return the result:\n\n```json example\n{\n \"name\": \"Mark Zuckerberg\",\n \"picture\": \"http://some.cdn/picture_600.jpg\"\n}\n```\n\nThe type of an object field argument must be an input type (any type except an\nObject, Interface, or Union type).\n\n### Field Deprecation\n\nFields in an object may be marked as deprecated as deemed necessary by the\napplication. It is still legal to include these fields in a _selection set_ (to\nensure existing clients are not broken by the change), but the fields should be\nappropriately treated in documentation and tooling.\n\nWhen using the type system definition language, `@deprecated` directives are\nused to indicate that a field is deprecated:\n\n```graphql example\ntype ExampleType {\n oldField: String @deprecated\n}\n```\n\n### Object Extensions\n\nObjectTypeExtension :\n\n- extend type Name ImplementsInterfaces? Directives[Const]? FieldsDefinition\n- extend type Name ImplementsInterfaces? Directives[Const] [lookahead != `{`]\n- extend type Name ImplementsInterfaces [lookahead != `{`]\n\nObject type extensions are used to represent a type which has been extended from\nsome previous type. For example, this might be used to represent local data, or\nby a GraphQL service which is itself an extension of another GraphQL service.\n\nIn this example, a local data field is added to a `Story` type:\n\n```graphql example\nextend type Story {\n isHiddenLocally: Boolean\n}\n```\n\nObject type extensions may choose not to add additional fields, instead only\nadding interfaces or directives.\n\nIn this example, a directive is added to a `User` type without adding fields:\n\n```graphql example\nextend type User @addedDirective\n```\n\n**Type Validation**\n\nObject type extensions have the potential to be invalid if incorrectly defined.\n\n1. The named type must already be defined and must be an Object type.\n2. The fields of an Object type extension must have unique names; no two fields\n may share the same name.\n3. Any fields of an Object type extension must not be already defined on the\n previous Object type.\n4. Any non-repeatable directives provided must not already apply to the previous\n Object type.\n5. Any interfaces provided must not be already implemented by the previous\n Object type.\n6. The resulting extended object type must be a super-set of all interfaces it\n implements.\n\n## Interfaces\n\nInterfaceTypeDefinition :\n\n- Description? interface Name ImplementsInterfaces? Directives[Const]?\n FieldsDefinition\n- Description? interface Name ImplementsInterfaces? Directives[Const]?\n [lookahead != `{`]\n\nGraphQL interfaces represent a list of named fields and their arguments. GraphQL\nobjects and interfaces can then implement these interfaces which requires the\nimplementing type to define all fields defined by those interfaces.\n\nFields on a GraphQL interface have the same rules as fields on a GraphQL object;\ntheir type can be Scalar, Object, Enum, Interface, or Union, or any wrapping\ntype whose base type is one of those five.\n\nFor example, an interface `NamedEntity` may describe a required field and types\nsuch as `Person` or `Business` may then implement this interface to guarantee\nthis field will always exist.\n\nTypes may also implement multiple interfaces. For example, `Business` implements\nboth the `NamedEntity` and `ValuedEntity` interfaces in the example below.\n\n```graphql example\ninterface NamedEntity {\n name: String\n}\n\ninterface ValuedEntity {\n value: Int\n}\n\ntype Person implements NamedEntity {\n name: String\n age: Int\n}\n\ntype Business implements NamedEntity & ValuedEntity {\n name: String\n value: Int\n employeeCount: Int\n}\n```\n\nFields which yield an interface are useful when one of many Object types are\nexpected, but some fields should be guaranteed.\n\nTo continue the example, a `Contact` might refer to `NamedEntity`.\n\n```graphql example\ntype Contact {\n entity: NamedEntity\n phoneNumber: String\n address: String\n}\n```\n\nThis allows us to write a _selection set_ for a `Contact` that can select the\ncommon fields.\n\n```graphql example\n{\n entity {\n name\n }\n phoneNumber\n}\n```\n\nWhen selecting fields on an interface type, only those fields declared on the\ninterface may be queried. In the above example, `entity` returns a\n`NamedEntity`, and `name` is defined on `NamedEntity`, so it is valid. However,\nthe following would not be a valid selection set against `Contact`:\n\n```graphql counter-example\n{\n entity {\n name\n age\n }\n phoneNumber\n}\n```\n\nbecause `entity` refers to a `NamedEntity`, and `age` is not defined on that\ninterface. Querying for `age` is only valid when the result of `entity` is a\n`Person`; this can be expressed using a fragment or an inline fragment:\n\n```graphql example\n{\n entity {\n name\n ... on Person {\n age\n }\n }\n phoneNumber\n}\n```\n\n**Interfaces Implementing Interfaces**\n\nWhen defining an interface that implements another interface, the implementing\ninterface must define each field that is specified by the implemented interface.\nFor example, the interface Resource must define the field id to implement the\nNode interface:\n\n```raw graphql example\ninterface Node {\n id: ID!\n}\n\ninterface Resource implements Node {\n id: ID!\n url: String\n}\n```\n\nTransitively implemented interfaces (interfaces implemented by the interface\nthat is being implemented) must also be defined on an implementing type or\ninterface. For example, `Image` cannot implement `Resource` without also\nimplementing `Node`:\n\n```raw graphql example\ninterface Node {\n id: ID!\n}\n\ninterface Resource implements Node {\n id: ID!\n url: String\n}\n\ninterface Image implements Resource & Node {\n id: ID!\n url: String\n thumbnail: String\n}\n```\n\nInterface definitions must not contain cyclic references nor implement\nthemselves. This example is invalid because `Node` and `Named` implement\nthemselves and each other:\n\n```graphql counter-example\ninterface Node implements Named & Node {\n id: ID!\n name: String\n}\n\ninterface Named implements Node & Named {\n id: ID!\n name: String\n}\n```\n\n**Result Coercion**\n\nThe interface type should have some way of determining which object a given\nresult corresponds to. Once it has done so, the result coercion of the interface\nis the same as the result coercion of the object.\n\n**Input Coercion**\n\nInterfaces are never valid inputs.\n\n**Type Validation**\n\nInterface types have the potential to be invalid if incorrectly defined.\n\n1. An Interface type must define one or more fields.\n2. For each field of an Interface type:\n 1. The field must have a unique name within that Interface type; no two\n fields may share the same name.\n 2. The field must not have a name which begins with the characters {\"\\_\\_\"}\n (two underscores).\n 3. The field must return a type where {IsOutputType(fieldType)} returns\n {true}.\n 4. For each argument of the field:\n 1. The argument must not have a name which begins with the characters\n {\"\\_\\_\"} (two underscores).\n 2. The argument must have a unique name within that field; no two\n arguments may share the same name.\n 3. The argument must accept a type where {IsInputType(argumentType)}\n returns {true}.\n3. An interface type may declare that it implements one or more unique\n interfaces, but may not implement itself.\n4. An interface type must be a super-set of all interfaces it implements:\n 1. Let this interface type be {implementingType}.\n 2. For each interface declared implemented as {implementedType},\n {IsValidImplementation(implementingType, implementedType)} must be {true}.\n\n### Interface Extensions\n\nInterfaceTypeExtension :\n\n- extend interface Name ImplementsInterfaces? Directives[Const]?\n FieldsDefinition\n- extend interface Name ImplementsInterfaces? Directives[Const] [lookahead !=\n `{`]\n- extend interface Name ImplementsInterfaces [lookahead != `{`]\n\nInterface type extensions are used to represent an interface which has been\nextended from some previous interface. For example, this might be used to\nrepresent common local data on many types, or by a GraphQL service which is\nitself an extension of another GraphQL service.\n\nIn this example, an extended data field is added to a `NamedEntity` type along\nwith the types which implement it:\n\n```graphql example\nextend interface NamedEntity {\n nickname: String\n}\n\nextend type Person {\n nickname: String\n}\n\nextend type Business {\n nickname: String\n}\n```\n\nInterface type extensions may choose not to add additional fields, instead only\nadding directives.\n\nIn this example, a directive is added to a `NamedEntity` type without adding\nfields:\n\n```graphql example\nextend interface NamedEntity @addedDirective\n```\n\n**Type Validation**\n\nInterface type extensions have the potential to be invalid if incorrectly\ndefined.\n\n1. The named type must already be defined and must be an Interface type.\n2. The fields of an Interface type extension must have unique names; no two\n fields may share the same name.\n3. Any fields of an Interface type extension must not be already defined on the\n previous Interface type.\n4. Any Object or Interface type which implemented the previous Interface type\n must also be a super-set of the fields of the Interface type extension (which\n may be due to Object type extension).\n5. Any non-repeatable directives provided must not already apply to the previous\n Interface type.\n6. The resulting extended Interface type must be a super-set of all Interfaces\n it implements.\n\n## Unions\n\nUnionTypeDefinition : Description? union Name Directives[Const]?\nUnionMemberTypes?\n\nUnionMemberTypes :\n\n- UnionMemberTypes | NamedType\n- = `|`? NamedType\n\nGraphQL Unions represent an object that could be one of a list of GraphQL Object\ntypes, but provides for no guaranteed fields between those types. They also\ndiffer from interfaces in that Object types declare what interfaces they\nimplement, but are not aware of what unions contain them.\n\nWith interfaces and objects, only those fields defined on the type can be\nqueried directly; to query other fields on an interface, typed fragments must be\nused. This is the same as for unions, but unions do not define any fields, so\n**no** fields may be queried on this type without the use of type refining\nfragments or inline fragments (with the exception of the meta-field\n{\\_\\_typename}).\n\nFor example, we might define the following types:\n\n```graphql example\nunion SearchResult = Photo | Person\n\ntype Person {\n name: String\n age: Int\n}\n\ntype Photo {\n height: Int\n width: Int\n}\n\ntype SearchQuery {\n firstSearchResult: SearchResult\n}\n```\n\nIn this example, a query operation wants the name if the result was a Person,\nand the height if it was a photo. However because a union itself defines no\nfields, this could be ambiguous and is invalid.\n\n```graphql counter-example\n{\n firstSearchResult {\n name\n height\n }\n}\n```\n\nA valid operation includes typed fragments (in this example, inline fragments):\n\n```graphql example\n{\n firstSearchResult {\n ... on Person {\n name\n }\n ... on Photo {\n height\n }\n }\n}\n```\n\nUnion members may be defined with an optional leading `|` character to aid\nformatting when representing a longer list of possible types:\n\n```raw graphql example\nunion SearchResult =\n | Photo\n | Person\n```\n\n**Result Coercion**\n\nThe union type should have some way of determining which object a given result\ncorresponds to. Once it has done so, the result coercion of the union is the\nsame as the result coercion of the object.\n\n**Input Coercion**\n\nUnions are never valid inputs.\n\n**Type Validation**\n\nUnion types have the potential to be invalid if incorrectly defined.\n\n1. A Union type must include one or more unique member types.\n2. The member types of a Union type must all be Object base types; Scalar,\n Interface and Union types must not be member types of a Union. Similarly,\n wrapping types must not be member types of a Union.\n\n### Union Extensions\n\nUnionTypeExtension :\n\n- extend union Name Directives[Const]? UnionMemberTypes\n- extend union Name Directives[Const]\n\nUnion type extensions are used to represent a union type which has been extended\nfrom some previous union type. For example, this might be used to represent\nadditional local data, or by a GraphQL service which is itself an extension of\nanother GraphQL service.\n\n**Type Validation**\n\nUnion type extensions have the potential to be invalid if incorrectly defined.\n\n1. The named type must already be defined and must be a Union type.\n2. The member types of a Union type extension must all be Object base types;\n Scalar, Interface and Union types must not be member types of a Union.\n Similarly, wrapping types must not be member types of a Union.\n3. All member types of a Union type extension must be unique.\n4. All member types of a Union type extension must not already be a member of\n the previous Union type.\n5. Any non-repeatable directives provided must not already apply to the previous\n Union type.\n\n## Enums\n\nEnumTypeDefinition :\n\n- Description? enum Name Directives[Const]? EnumValuesDefinition\n- Description? enum Name Directives[Const]? [lookahead != `{`]\n\nEnumValuesDefinition : { EnumValueDefinition+ }\n\nEnumValueDefinition : Description? EnumValue Directives[Const]?\n\nGraphQL Enum types, like Scalar types, also represent leaf values in a GraphQL\ntype system. However Enum types describe the set of possible values.\n\nEnums are not references for a numeric value, but are unique values in their own\nright. They may serialize as a string: the name of the represented value.\n\nIn this example, an Enum type called `Direction` is defined:\n\n```graphql example\nenum Direction {\n NORTH\n EAST\n SOUTH\n WEST\n}\n```\n\n**Result Coercion**\n\nGraphQL services must return one of the defined set of possible values. If a\nreasonable coercion is not possible they must raise an _execution error_.\n\n**Input Coercion**\n\nGraphQL has a constant literal to represent enum input values. GraphQL string\nliterals must not be accepted as an enum input and instead raise a request\nerror.\n\nVariable transport serializations which have a different representation for\nnon-string symbolic values (for example,\n[EDN](https://github.com/edn-format/edn)) should only allow such values as enum\ninput values. Otherwise, for most transport serializations that do not, strings\nmay be interpreted as the enum input value with the same name.\n\n**Type Validation**\n\nEnum types have the potential to be invalid if incorrectly defined.\n\n1. An Enum type must define one or more unique enum values.\n\n### Enum Extensions\n\nEnumTypeExtension :\n\n- extend enum Name Directives[Const]? EnumValuesDefinition\n- extend enum Name Directives[Const] [lookahead != `{`]\n\nEnum type extensions are used to represent an enum type which has been extended\nfrom some previous enum type. For example, this might be used to represent\nadditional local data, or by a GraphQL service which is itself an extension of\nanother GraphQL service.\n\n**Type Validation**\n\nEnum type extensions have the potential to be invalid if incorrectly defined.\n\n1. The named type must already be defined and must be an Enum type.\n2. All values of an Enum type extension must be unique.\n3. All values of an Enum type extension must not already be a value of the\n previous Enum.\n4. Any non-repeatable directives provided must not already apply to the previous\n Enum type.\n\n## Input Objects\n\nInputObjectTypeDefinition :\n\n- Description? input Name Directives[Const]? InputFieldsDefinition\n- Description? input Name Directives[Const]? [lookahead != `{`]\n\nInputFieldsDefinition : { InputValueDefinition+ }\n\nFields may accept arguments to configure their behavior. These inputs are often\nscalars or enums, but they sometimes need to represent more complex values.\n\n:: A GraphQL _Input Object_ defines a set of input fields; the input fields are\nscalars, enums, other input objects, or any wrapping type whose underlying base\ntype is one of those three. This allows arguments to accept arbitrarily complex\nstructs.\n\nIn this example, an Input Object called `Point2D` describes `x` and `y` inputs:\n\n```graphql example\ninput Point2D {\n x: Float\n y: Float\n}\n```\n\nNote: The GraphQL Object type ({ObjectTypeDefinition}) defined above is\ninappropriate for re-use here, because Object types can contain fields that\ndefine arguments or contain references to interfaces and unions, neither of\nwhich is appropriate for use as an input argument. For this reason, input\nobjects have a separate type in the system.\n\n**Circular References**\n\nInput Objects are allowed to reference other Input Objects as field types. A\ncircular reference occurs when an Input Object references itself either directly\nor through referenced Input Objects.\n\nCircular references are generally allowed, however they may not be defined as an\nunbroken chain of Non-Null singular fields. Such Input Objects are invalid\nbecause there is no way to provide a legal value for them.\n\nThis example of a circularly-referenced input type is valid as the field `self`\nmay be omitted or the value {null}.\n\n```graphql example\ninput Example {\n self: Example\n value: String\n}\n```\n\nThis example is also valid as the field `self` may be an empty List.\n\n```graphql example\ninput Example {\n self: [Example!]!\n value: String\n}\n```\n\nThis example of a circularly-referenced input type is invalid as the field\n`self` cannot be provided a finite value.\n\n```graphql counter-example\ninput Example {\n self: Example!\n value: String\n}\n```\n\nThis example is also invalid, as there is a non-null singular circular reference\nvia the `First.second` and `Second.first` fields.\n\n```graphql counter-example\ninput First {\n second: Second!\n value: String\n}\n\ninput Second {\n first: First!\n value: String\n}\n```\n\n**Result Coercion**\n\nAn input object is never a valid result. Input Object types cannot be the return\ntype of an Object or Interface field.\n\n**Input Coercion**\n\nThe value for an input object should be an input object literal or an unordered\nmap supplied by a variable, otherwise a _request error_ must be raised. In\neither case, the input object literal or unordered map must not contain any\nentries with names not defined by a field of this input object type, otherwise a\nrequest error must be raised.\n\nThe result of coercion is an unordered map with an entry for each field both\ndefined by the input object type and for which a value exists. The resulting map\nis constructed with the following rules:\n\n- If no value is provided for a defined input object field and that field\n definition provides a default value, the result of coercing the default value\n according to the coercion rules of the input field type should be used. If no\n default value is provided and the input object field's type is non-null, an\n error should be raised. Otherwise, if the field is not required, then no entry\n is added to the coerced unordered map.\n\n- If the value {null} was provided for an input object field, and the field's\n type is not a non-null type, an entry in the coerced unordered map is given\n the value {null}. In other words, there is a semantic difference between the\n explicitly provided value {null} versus having not provided a value.\n\n- If a literal value is provided for an input object field, an entry in the\n coerced unordered map is given the result of coercing that value according to\n the input coercion rules for the type of that field.\n\n- If a variable is provided for an input object field, the runtime value of that\n variable must be used. If the runtime value is {null} and the field type is\n non-null, an _execution error_ must be raised. If no runtime value is\n provided, the variable definition's default value should be used. If the\n variable definition does not provide a default value, the input object field\n definition's default value should be used.\n\nFollowing are examples of input coercion for an input object type with a\n`String` field `a` and a required (non-null) `Int!` field `b`:\n\n```graphql example\ninput ExampleInputObject {\n a: String\n b: Int!\n}\n```\n\n| Literal Value | Variables | Coerced Value |\n| ------------------------ | ----------------------- | ------------------------------------ |\n| `{ a: \"abc\", b: 123 }` | `{}` | `{ a: \"abc\", b: 123 }` |\n| `{ a: null, b: 123 }` | `{}` | `{ a: null, b: 123 }` |\n| `{ b: 123 }` | `{}` | `{ b: 123 }` |\n| `{ a: $var, b: 123 }` | `{ var: null }` | `{ a: null, b: 123 }` |\n| `{ a: $var, b: 123 }` | `{}` | `{ b: 123 }` |\n| `{ b: $var }` | `{ var: 123 }` | `{ b: 123 }` |\n| `$var` | `{ var: { b: 123 } }` | `{ b: 123 }` |\n| `\"abc123\"` | `{}` | Error: Incorrect value |\n| `$var` | `{ var: \"abc123\" }` | Error: Incorrect value |\n| `{ a: \"abc\", b: \"123\" }` | `{}` | Error: Incorrect value for field {b} |\n| `{ a: \"abc\" }` | `{}` | Error: Missing required field {b} |\n| `{ b: $var }` | `{}` | Error: Missing required field {b}. |\n| `$var` | `{ var: { a: \"abc\" } }` | Error: Missing required field {b} |\n| `{ a: \"abc\", b: null }` | `{}` | Error: {b} must be non-null. |\n| `{ b: $var }` | `{ var: null }` | Error: {b} must be non-null. |\n| `{ b: 123, c: \"xyz\" }` | `{}` | Error: Unexpected field {c} |\n\n**Type Validation**\n\n1. An Input Object type must define one or more input fields.\n2. For each input field of an Input Object type:\n 1. The input field must have a unique name within that Input Object type; no\n two input fields may share the same name.\n 2. The input field must not have a name which begins with the characters\n {\"\\_\\_\"} (two underscores).\n 3. The input field must accept a type where {IsInputType(inputFieldType)}\n returns {true}.\n 4. If input field type is Non-Null and a default value is not defined:\n 1. The `@deprecated` directive must not be applied to this input field.\n 5. If the Input Object is a _OneOf Input Object_ then:\n 1. The type of the input field must be nullable.\n 2. The input field must not have a default value.\n3. If an Input Object references itself either directly or through referenced\n Input Objects, at least one of the fields in the chain of references must be\n either a nullable or a List type.\n4. {InputObjectDefaultValueHasCycle(inputObject)} must be {false}.\n\nInputObjectDefaultValueHasCycle(inputObject, defaultValue, visitedFields):\n\n- If {defaultValue} is not provided, initialize it to an empty unordered map.\n- If {visitedFields} is not provided, initialize it to the empty set.\n- If {defaultValue} is a list:\n - For each {itemValue} in {defaultValue}:\n - If {InputObjectDefaultValueHasCycle(inputObject, itemValue,\n visitedFields)}, return {true}.\n- Otherwise, if {defaultValue} is an unordered map:\n - For each field {field} in {inputObject}:\n - If {InputFieldDefaultValueHasCycle(field, defaultValue, visitedFields)},\n return {true}.\n- Return {false}.\n\nInputFieldDefaultValueHasCycle(field, defaultValue, visitedFields):\n\n- Assert: {defaultValue} is an unordered map.\n- Let {fieldType} be the type of {field}.\n- Let {namedFieldType} be the underlying named type of {fieldType}.\n- If {namedFieldType} is not an input object type:\n - Return {false}.\n- Let {fieldName} be the name of {field}.\n- Let {fieldDefaultValue} be the value for {fieldName} in {defaultValue}.\n- If {fieldDefaultValue} exists:\n - Return {InputObjectDefaultValueHasCycle(namedFieldType, fieldDefaultValue,\n visitedFields)}.\n- Otherwise:\n - Let {fieldDefaultValue} be the default value of {field}.\n - If {fieldDefaultValue} does not exist:\n - Return {false}.\n - If {field} is within {visitedFields}:\n - Return {true}.\n - Let {nextVisitedFields} be a new set containing {field} and everything from\n {visitedFields}.\n - Return {InputObjectDefaultValueHasCycle(namedFieldType, fieldDefaultValue,\n nextVisitedFields)}.\n\n### OneOf Input Objects\n\n:: A _OneOf Input Object_ is a special variant of _Input Object_ where exactly\none field must be set and non-null, all others being omitted. This is useful for\nrepresenting situations where an input may be one of many different options.\n\nWhen using the type system definition language, the [`@oneOf`](#sec--oneOf)\ndirective is used to indicate that an Input Object is a OneOf Input Object (and\nthus requires exactly one of its fields be provided):\n\n```graphql\ninput UserUniqueCondition @oneOf {\n id: ID\n username: String\n organizationAndEmail: OrganizationAndEmailInput\n}\n```\n\nIn schema introspection, the `__Type.isOneOf` field will return {true} for OneOf\nInput Objects, and {false} for all other Input Objects.\n\n**Input Coercion**\n\nThe value of a OneOf Input Object, as a variant of Input Object, must also be an\ninput object literal or an unordered map supplied by a variable, otherwise a\n_request error_ must be raised.\n\n- Prior to construction of the coerced map via the input coercion rules of an\n _Input Object_: the value to be coerced must contain exactly one entry and\n that entry must not be {null} or the {null} literal, otherwise a _request\n error_ must be raised.\n\n- All _Input Object_ [input coercion rules](#sec-Input-Objects.Input-Coercion)\n must also apply to a _OneOf Input Object_.\n\n- The resulting coerced map must contain exactly one entry and the value for\n that entry must not be {null}, otherwise an _execution error_ must be raised.\n\nFollowing are additional examples of input coercion for a OneOf Input Object\ntype with a `String` member field `a` and an `Int` member field `b`:\n\n```graphql example\ninput ExampleOneOfInputObject @oneOf {\n a: String\n b: Int\n}\n```\n\n| Literal Value | Variables | Coerced Value |\n| ----------------------- | ------------------------------- | --------------------------------------------------- |\n| `{ a: \"abc\" }` | `{}` | `{ a: \"abc\" }` |\n| `{ b: 123 }` | `{}` | `{ b: 123 }` |\n| `$var` | `{ var: { a: \"abc\" } }` | `{ a: \"abc\" }` |\n| `{ a: null }` | `{}` | Error: Value for member field {a} must be non-null |\n| `$var` | `{ var: { a: null } }` | Error: Value for member field {a} must be non-null |\n| `{ a: $a }` | `{}` | Error: Value for member field {a} must be specified |\n| `{ a: \"abc\", b: 123 }` | `{}` | Error: Exactly one key must be specified |\n| `{ a: 456, b: \"xyz\" }` | `{}` | Error: Exactly one key must be specified |\n| `$var` | `{ var: { a: \"abc\", b: 123 } }` | Error: Exactly one key must be specified |\n| `{ a: \"abc\", b: null }` | `{}` | Error: Exactly one key must be specified |\n| `{ a: \"abc\", b: $b }` | `{}` | Error: Exactly one key must be specified |\n| `{ a: $a, b: $b }` | `{ a: \"abc\" }` | Error: Exactly one key must be specified |\n| `{}` | `{}` | Error: Exactly one key must be specified |\n| `$var` | `{ var: {} }` | Error: Exactly one key must be specified |\n\n### Input Object Extensions\n\nInputObjectTypeExtension :\n\n- extend input Name Directives[Const]? InputFieldsDefinition\n- extend input Name Directives[Const] [lookahead != `{`]\n\nInput object type extensions are used to represent an input object type which\nhas been extended from some previous input object type. For example, this might\nbe used by a GraphQL service which is itself an extension of another GraphQL\nservice.\n\n**Type Validation**\n\nInput object type extensions have the potential to be invalid if incorrectly\ndefined.\n\n1. The named type must already be defined and must be a Input Object type.\n2. All fields of an Input Object type extension must have unique names.\n3. All fields of an Input Object type extension must not already be a field of\n the previous Input Object.\n4. Any non-repeatable directives provided must not already apply to the previous\n Input Object type.\n5. The `@oneOf` directive must not be provided by an Input Object type\n extension.\n6. If the original Input Object is a _OneOf Input Object_ then:\n 1. All fields of the Input Object type extension must be nullable.\n 2. All fields of the Input Object type extension must not have default\n values.\n\n## List\n\nA GraphQL list is a special collection type which declares the type of each item\nin the List (referred to as the _item type_ of the list). List values are\nserialized as ordered lists, where each item in the list is serialized as per\nthe item type.\n\nTo denote that a field uses a List type the item type is wrapped in square\nbrackets like this: `pets: [Pet]`. Nesting lists is allowed: `matrix: [[Int]]`.\n\n**Result Coercion**\n\nGraphQL services must return an ordered list as the result of a list type. Each\nitem in the list must be the result of a result coercion of the item type. If a\nreasonable coercion is not possible it must raise an _execution error_. In\nparticular, if a non-list is returned, the coercion should fail, as this\nindicates a mismatch in expectations between the type system and the\nimplementation.\n\nIf a list's item type is nullable, then errors occurring during preparation or\ncoercion of an individual item in the list must result in the value {null} at\nthat position in the list along with an _execution error_ added to the response.\nIf a list's item type is non-null, an execution error occurring at an individual\nitem in the list must result in an execution error for the entire list.\n\nNote: See [Handling Execution Errors](#sec-Handling-Execution-Errors) for more\nabout this behavior.\n\n**Input Coercion**\n\nWhen expected as an input, list values are accepted only when each item in the\nlist can be accepted by the list's item type.\n\nIf the value passed as an input to a list type is _not_ a list and not the\n{null} value, then the result of input coercion is a list of size one, where the\nsingle item value is the result of input coercion for the list's item type on\nthe provided value (note this may apply recursively for nested lists).\n\nThis allows inputs which accept one or many arguments (sometimes referred to as\n\"var args\") to declare their input type as a list while for the common case of a\nsingle value, a client can just pass that value directly rather than\nconstructing the list.\n\nFollowing are examples of input coercion with various list types and values:\n\n| Expected Type | Provided Value | Coerced Value |\n| ------------- | ---------------- | --------------------------- |\n| `[Int]` | `[1, 2, 3]` | `[1, 2, 3]` |\n| `[Int]` | `[1, \"b\", true]` | Error: Incorrect item value |\n| `[Int]` | `1` | `[1]` |\n| `[Int]` | `null` | `null` |\n| `[[Int]]` | `[[1], [2, 3]]` | `[[1], [2, 3]]` |\n| `[[Int]]` | `[1, 2, 3]` | `[[1], [2], [3]]` |\n| `[[Int]]` | `[1, null, 3]` | `[[1], null, [3]]` |\n| `[[Int]]` | `[[1], [\"b\"]]` | Error: Incorrect item value |\n| `[[Int]]` | `1` | `[[1]]` |\n| `[[Int]]` | `null` | `null` |\n\n## Non-Null\n\nBy default, all types in GraphQL are nullable; the {null} value is a valid\nresponse for all of the above types. To declare a type that disallows null, the\nGraphQL Non-Null type can be used. This type wraps an underlying type, and this\ntype acts identically to that wrapped type, with the exception that {null} is\nnot a valid response for the wrapping type. A trailing exclamation mark is used\nto denote a field that uses a Non-Null type like this: `name: String!`.\n\n**Nullable vs. Optional**\n\nFields are _always_ optional within the context of a _selection set_, a field\nmay be omitted and the selection set is still valid (so long as the selection\nset does not become empty). However fields that return Non-Null types will never\nreturn the value {null} if queried.\n\nInputs (such as field arguments), are always optional by default. However a\nnon-null input type is required. In addition to not accepting the value {null},\nit also does not accept omission. For the sake of simplicity nullable types are\nalways optional and non-null types are always required.\n\n**Result Coercion**\n\nIn all of the above result coercions, {null} was considered a valid value. To\ncoerce the result of a Non-Null type, the coercion of the wrapped type should be\nperformed. If that result was not {null}, then the result of coercing the\nNon-Null type is that result. If that result was {null}, then an _execution\nerror_ must be raised.\n\nNote: When an _execution error_ is raised on a non-null _response position_, the\nerror propagates to the parent _response position_. For more information on this\nprocess, see\n[Errors and Non-Null Types](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Types)\nwithin the Execution section.\n\n**Input Coercion**\n\nIf an argument or input-object field of a Non-Null type is not provided, is\nprovided with the literal value {null}, or is provided with a variable that was\neither not provided a value at runtime, or was provided the value {null}, then a\n_request error_ must be raised.\n\nIf the value provided to the Non-Null type is provided with a literal value\nother than {null}, or a Non-Null variable value, it is coerced using the input\ncoercion for the wrapped type.\n\nA non-null argument cannot be omitted:\n\n```graphql counter-example\n{\n fieldWithNonNullArg\n}\n```\n\nThe value {null} cannot be provided to a non-null argument:\n\n```graphql counter-example\n{\n fieldWithNonNullArg(nonNullArg: null)\n}\n```\n\nA variable of a nullable type cannot be provided to a non-null argument:\n\n```graphql example\nquery withNullableVariable($var: String) {\n fieldWithNonNullArg(nonNullArg: $var)\n}\n```\n\nNote: The Validation section defines providing a nullable variable type to a\nnon-null input type as invalid.\n\n**Type Validation**\n\n1. A Non-Null type must not wrap another Non-Null type.\n\n### Combining List and Non-Null\n\nThe List and Non-Null wrapping types can compose, representing more complex\ntypes. The rules for result coercion and input coercion of Lists and Non-Null\ntypes apply in a recursive fashion.\n\nFor example if the inner item type of a List is Non-Null (e.g. `[T!]`), then\nthat List may not contain any {null} items. However if the inner type of a\nNon-Null is a List (e.g. `[T]!`), then {null} is not accepted however an empty\nlist is accepted.\n\nFollowing are examples of result coercion with various types and values:\n\n| Expected Type | Internal Value | Coerced Result |\n| ------------- | --------------- | ----------------------------------- |\n| `[Int]` | `[1, 2, 3]` | `[1, 2, 3]` |\n| `[Int]` | `null` | `null` |\n| `[Int]` | `[1, 2, null]` | `[1, 2, null]` |\n| `[Int]` | `[1, 2, Error]` | `[1, 2, null]` (With logged error) |\n| `[Int]!` | `[1, 2, 3]` | `[1, 2, 3]` |\n| `[Int]!` | `null` | Error: Value cannot be null |\n| `[Int]!` | `[1, 2, null]` | `[1, 2, null]` |\n| `[Int]!` | `[1, 2, Error]` | `[1, 2, null]` (With logged error) |\n| `[Int!]` | `[1, 2, 3]` | `[1, 2, 3]` |\n| `[Int!]` | `null` | `null` |\n| `[Int!]` | `[1, 2, null]` | `null` (With logged coercion error) |\n| `[Int!]` | `[1, 2, Error]` | `null` (With logged error) |\n| `[Int!]!` | `[1, 2, 3]` | `[1, 2, 3]` |\n| `[Int!]!` | `null` | Error: Value cannot be null |\n| `[Int!]!` | `[1, 2, null]` | Error: Item cannot be null |\n| `[Int!]!` | `[1, 2, Error]` | Error: Error occurred in item |\n\n## Directives\n\nDirectiveDefinition : Description? directive @ Name ArgumentsDefinition?\n`repeatable`? on DirectiveLocations\n\nDirectiveLocations :\n\n- DirectiveLocations | DirectiveLocation\n- `|`? DirectiveLocation\n\nDirectiveLocation :\n\n- ExecutableDirectiveLocation\n- TypeSystemDirectiveLocation\n\nExecutableDirectiveLocation : one of\n\n- `QUERY`\n- `MUTATION`\n- `SUBSCRIPTION`\n- `FIELD`\n- `FRAGMENT_DEFINITION`\n- `FRAGMENT_SPREAD`\n- `INLINE_FRAGMENT`\n- `VARIABLE_DEFINITION`\n\nTypeSystemDirectiveLocation : one of\n\n- `SCHEMA`\n- `SCALAR`\n- `OBJECT`\n- `FIELD_DEFINITION`\n- `ARGUMENT_DEFINITION`\n- `INTERFACE`\n- `UNION`\n- `ENUM`\n- `ENUM_VALUE`\n- `INPUT_OBJECT`\n- `INPUT_FIELD_DEFINITION`\n\nA GraphQL schema describes directives which are used to annotate various parts\nof a GraphQL document as an indicator that they should be evaluated differently\nby a validator, executor, or client tool such as a code generator.\n\n**Built-in Directives**\n\n:: A _built-in directive_ is any directive defined within this specification.\n\nGraphQL implementations should provide the `@skip` and `@include` directives.\n\nGraphQL implementations that support the type system definition language must\nprovide the `@deprecated` directive if representing deprecated portions of the\nschema.\n\nGraphQL implementations that support the type system definition language should\nprovide the `@specifiedBy` directive if representing custom scalar definitions.\n\nGraphQL implementations that support the type system definition language should\nprovide the `@oneOf` directive if representing OneOf Input Objects.\n\nWhen representing a GraphQL schema using the type system definition language any\n_built-in directive_ may be omitted for brevity.\n\nWhen introspecting a GraphQL service all provided directives, including any\n_built-in directive_, must be included in the set of returned directives.\n\n**Custom Directives**\n\n:: GraphQL services and client tooling may provide any additional _custom\ndirective_ beyond those defined in this document. Directives are the preferred\nway to extend GraphQL with custom or experimental behavior.\n\nNote: When defining a _custom directive_, it is recommended to prefix the\ndirective's name to make its scope of usage clear and to prevent a collision\nwith _built-in directive_ which may be specified by future versions of this\ndocument (which will not include `_` in their name). For example, a _custom\ndirective_ used by Facebook's GraphQL service should be named `@fb_auth` instead\nof `@auth`. This is especially recommended for proposed additions to this\nspecification which can change during the\n[RFC process](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md).\nFor example a work in progress version of `@live` should be named `@rfc_live`.\n\nDirectives must only be used in the locations they are declared to belong in. In\nthis example, a directive is defined which can be used to annotate a field:\n\n```graphql example\ndirective @example on FIELD\n\nfragment SomeFragment on SomeType {\n field @example\n}\n```\n\nDirective locations may be defined with an optional leading `|` character to aid\nformatting when representing a longer list of possible locations:\n\n```raw graphql example\ndirective @example on\n | FIELD\n | FRAGMENT_SPREAD\n | INLINE_FRAGMENT\n```\n\nDirectives can also be used to annotate the type system definition language as\nwell, which can be a useful tool for supplying additional metadata in order to\ngenerate GraphQL execution services, produce client generated runtime code, or\nmany other useful extensions of the GraphQL semantics.\n\nIn this example, the directive `@example` annotates field and argument\ndefinitions:\n\n```graphql example\ndirective @example on FIELD_DEFINITION | ARGUMENT_DEFINITION\n\ntype SomeType {\n field(arg: Int @example): String @example\n}\n```\n\nA directive may be defined as repeatable by including the \"repeatable\" keyword.\nRepeatable directives are often useful when the same directive should be used\nwith different arguments at a single location, especially in cases where\nadditional information needs to be provided to a type or schema extension via a\ndirective:\n\n```graphql example\ndirective @delegateField(name: String!) repeatable on OBJECT | INTERFACE\n\ntype Book @delegateField(name: \"pageCount\") @delegateField(name: \"author\") {\n id: ID!\n}\n\nextend type Book @delegateField(name: \"index\")\n```\n\nWhile defining a directive, it must not reference itself directly or indirectly:\n\n```graphql counter-example\ndirective @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION\n```\n\nNote: The order in which directives appear may be significant, including\nrepeatable directives.\n\n**Type Validation**\n\n1. A Directive definition must include at least one DirectiveLocation.\n2. A Directive definition must not contain the use of a Directive which\n references itself directly.\n3. A Directive definition must not contain the use of a Directive which\n references itself indirectly by referencing a Type or Directive which\n transitively includes a reference to this Directive.\n4. The Directive must not have a name which begins with the characters {\"\\_\\_\"}\n (two underscores).\n5. For each argument of the Directive:\n 1. The argument must not have a name which begins with the characters\n {\"\\_\\_\"} (two underscores).\n 2. The argument must have a unique name within that Directive; no two\n arguments may share the same name.\n 3. The argument must accept a type where {IsInputType(argumentType)} returns\n {true}.\n\n### @skip\n\n```graphql\ndirective @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT\n```\n\nThe `@skip` _built-in directive_ may be provided for fields, fragment spreads,\nand inline fragments, and allows for conditional exclusion during execution as\ndescribed by the `if` argument.\n\nIn this example `experimentalField` will only be queried if the variable\n`$someTest` has the value `false`.\n\n```graphql example\nquery myQuery($someTest: Boolean!) {\n experimentalField @skip(if: $someTest)\n}\n```\n\n### @include\n\n```graphql\ndirective @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT\n```\n\nThe `@include` _built-in directive_ may be provided for fields, fragment\nspreads, and inline fragments, and allows for conditional inclusion during\nexecution as described by the `if` argument.\n\nIn this example `experimentalField` will only be queried if the variable\n`$someTest` has the value `true`\n\n```graphql example\nquery myQuery($someTest: Boolean!) {\n experimentalField @include(if: $someTest)\n}\n```\n\nNote: Neither `@skip` nor `@include` has precedence over the other. In the case\nthat both the `@skip` and `@include` directives are provided on the same field\nor fragment, it _must_ be queried only if the `@skip` condition is false _and_\nthe `@include` condition is true. Stated conversely, the field or fragment must\n_not_ be queried if either the `@skip` condition is true _or_ the `@include`\ncondition is false.\n\n### @deprecated\n\n```graphql\ndirective @deprecated(\n reason: String! = \"No longer supported\"\n) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE\n```\n\nThe `@deprecated` _built-in directive_ is used within the type system definition\nlanguage to indicate deprecated portions of a GraphQL service's schema, such as\ndeprecated fields on a type, arguments on a field, input fields on an input\ntype, or values of an enum type.\n\nDeprecations include a reason for why it is deprecated, which is formatted using\nMarkdown syntax (as specified by [CommonMark](https://commonmark.org/)).\n\nIn this example type definition, `oldField` is deprecated in favor of using\n`newField` and `oldArg` is deprecated in favor of using `newArg`.\n\n```graphql example\ntype ExampleType {\n newField: String\n oldField: String @deprecated(reason: \"Use `newField`.\")\n\n anotherField(\n newArg: String\n oldArg: String @deprecated(reason: \"Use `newArg`.\")\n ): String\n}\n```\n\nThe `@deprecated` directive must not appear on required (non-null without a\ndefault) arguments or input object field definitions.\n\n```graphql counter-example\ntype ExampleType {\n invalidField(\n newArg: String\n oldArg: String! @deprecated(reason: \"Use `newArg`.\")\n ): String\n}\n```\n\nTo deprecate a required argument or input field, it must first be made optional\nby either changing the type to nullable or adding a default value.\n\n### @specifiedBy\n\n```graphql\ndirective @specifiedBy(url: String!) on SCALAR\n```\n\nThe `@specifiedBy` _built-in directive_ is used within the type system\ndefinition language to provide a _scalar specification URL_ for specifying the\nbehavior of [custom scalar types](#sec-Scalars.Custom-Scalars). The URL should\npoint to a human-readable specification of the data format, serialization, and\ncoercion rules. It must not appear on built-in scalar types.\n\nNote: Details on implementing a GraphQL scalar specification can be found in the\n[scalars.graphql.org implementation guide](https://scalars.graphql.org/implementation-guide).\n\nIn this example, a custom scalar type for `UUID` is defined with a URL pointing\nto the relevant IETF specification.\n\n```graphql example\nscalar UUID @specifiedBy(url: \"https://tools.ietf.org/html/rfc4122\")\n```\n\n### @oneOf\n\n```graphql\ndirective @oneOf on INPUT_OBJECT\n```\n\nThe `@oneOf` _built-in directive_ is used within the type system definition\nlanguage to indicate an _Input Object_ is a _OneOf Input Object_.\n\n```graphql example\ninput UserUniqueCondition @oneOf {\n id: ID\n username: String\n organizationAndEmail: OrganizationAndEmailInput\n}\n```\n" }, { "path": "spec/Section 4 -- Introspection.md", "content": "# Introspection\n\nA GraphQL service supports introspection over its schema. This schema is queried\nusing GraphQL itself, creating a powerful platform for tool-building.\n\nTake an example request for a trivial app. In this case there is a User type\nwith three fields: id, name, and birthday.\n\nFor example, given a service with the following type definition:\n\n```graphql example\ntype User {\n id: String\n name: String\n birthday: Date\n}\n```\n\nA request containing the operation:\n\n```graphql example\n{\n __type(name: \"User\") {\n name\n fields {\n name\n type {\n name\n }\n }\n }\n}\n```\n\nwould produce the result:\n\n```json example\n{\n \"__type\": {\n \"name\": \"User\",\n \"fields\": [\n {\n \"name\": \"id\",\n \"type\": { \"name\": \"String\" }\n },\n {\n \"name\": \"name\",\n \"type\": { \"name\": \"String\" }\n },\n {\n \"name\": \"birthday\",\n \"type\": { \"name\": \"Date\" }\n }\n ]\n }\n}\n```\n\n**Reserved Names**\n\nTypes and fields required by the GraphQL introspection system that are used in\nthe same context as user defined types and fields are prefixed with {\"\\_\\_\"}\n(two underscores), in order to avoid naming collisions with user defined GraphQL\ntypes.\n\nOtherwise, any {Name} within a GraphQL type system must not start with two\nunderscores {\"\\_\\_\"}.\n\n## Type Name Introspection\n\nGraphQL supports type name introspection within any _selection set_ in an\noperation, with the single exception of selections at the root of a subscription\noperation. Type name introspection is accomplished via the meta-field\n`__typename: String!` on any Object, Interface, or Union. It returns the name of\nthe concrete Object type at that point during execution.\n\nThis is most often used when querying against Interface or Union types to\nidentify which actual Object type of the possible types has been returned.\n\nAs a meta-field, `__typename` is implicit and does not appear in the fields list\nin any defined type.\n\nNote: `__typename` may not be included as a root field in a subscription\noperation.\n\n## Schema Introspection\n\nThe schema introspection system is accessible from the meta-fields `__schema`\nand `__type` which are accessible from the type of the root of a query\noperation.\n\n```graphql\n__schema: __Schema!\n__type(name: String!): __Type\n```\n\nLike all meta-fields, these are implicit and do not appear in the fields list in\nthe root type of the query operation.\n\n**First Class Documentation**\n\nAll types in the introspection system provide a `description` field of type\n`String` to allow type designers to publish documentation in addition to\ncapabilities. A GraphQL service may return the `description` field using\nMarkdown syntax (as specified by [CommonMark](https://commonmark.org/)).\nTherefore it is recommended that any tool that displays `description` use a\nCommonMark-compliant Markdown renderer.\n\n**Deprecation**\n\nTo support the management of backwards compatibility, GraphQL fields, arguments,\ninput fields, and enum values can indicate whether or not they are deprecated\n(`isDeprecated: Boolean!`) along with a description of why it is deprecated\n(`deprecationReason: String`).\n\nTools built using GraphQL introspection should respect deprecation by\ndiscouraging deprecated use through information hiding or developer-facing\nwarnings.\n\n**Stable Ordering**\n\nThe observable order of all data collections should be preserved to improve\nschema legibility and stability. When a schema is produced from a\n{TypeSystemDocument}, introspection should return items in the same source order\nfor each element list: object fields, input object fields, arguments, enum\nvalues, directives, union member types, and implemented interfaces.\n\n**Schema Introspection Schema**\n\nThe schema introspection system is itself represented as a GraphQL schema. Below\nare the full set of type system definitions providing schema introspection,\nwhich are fully defined in the sections below.\n\n```graphql\ntype __Schema {\n description: String\n types: [__Type!]!\n queryType: __Type!\n mutationType: __Type\n subscriptionType: __Type\n directives: [__Directive!]!\n}\n\ntype __Type {\n kind: __TypeKind!\n name: String\n description: String\n # may be non-null for custom SCALAR, otherwise null.\n specifiedByURL: String\n # must be non-null for OBJECT and INTERFACE, otherwise null.\n fields(includeDeprecated: Boolean! = false): [__Field!]\n # must be non-null for OBJECT and INTERFACE, otherwise null.\n interfaces: [__Type!]\n # must be non-null for INTERFACE and UNION, otherwise null.\n possibleTypes: [__Type!]\n # must be non-null for ENUM, otherwise null.\n enumValues(includeDeprecated: Boolean! = false): [__EnumValue!]\n # must be non-null for INPUT_OBJECT, otherwise null.\n inputFields(includeDeprecated: Boolean! = false): [__InputValue!]\n # must be non-null for NON_NULL and LIST, otherwise null.\n ofType: __Type\n # must be non-null for INPUT_OBJECT, otherwise null.\n isOneOf: Boolean\n}\n\nenum __TypeKind {\n SCALAR\n OBJECT\n INTERFACE\n UNION\n ENUM\n INPUT_OBJECT\n LIST\n NON_NULL\n}\n\ntype __Field {\n name: String!\n description: String\n args(includeDeprecated: Boolean! = false): [__InputValue!]!\n type: __Type!\n isDeprecated: Boolean!\n deprecationReason: String\n}\n\ntype __InputValue {\n name: String!\n description: String\n type: __Type!\n defaultValue: String\n isDeprecated: Boolean!\n deprecationReason: String\n}\n\ntype __EnumValue {\n name: String!\n description: String\n isDeprecated: Boolean!\n deprecationReason: String\n}\n\ntype __Directive {\n name: String!\n description: String\n isRepeatable: Boolean!\n locations: [__DirectiveLocation!]!\n args(includeDeprecated: Boolean! = false): [__InputValue!]!\n}\n\nenum __DirectiveLocation {\n QUERY\n MUTATION\n SUBSCRIPTION\n FIELD\n FRAGMENT_DEFINITION\n FRAGMENT_SPREAD\n INLINE_FRAGMENT\n VARIABLE_DEFINITION\n SCHEMA\n SCALAR\n OBJECT\n FIELD_DEFINITION\n ARGUMENT_DEFINITION\n INTERFACE\n UNION\n ENUM\n ENUM_VALUE\n INPUT_OBJECT\n INPUT_FIELD_DEFINITION\n}\n```\n\n### The \\_\\_Schema Type\n\nThe `__Schema` type is returned from the `__schema` meta-field and provides all\ninformation about the schema of a GraphQL service.\n\nFields\\:\n\n- `description` may return a String or {null}.\n- `queryType` is the root type of a query operation.\n- `mutationType` is the root type of a mutation operation, if supported.\n Otherwise {null}.\n- `subscriptionType` is the root type of a subscription operation, if supported.\n Otherwise {null}.\n- `types` must return the set of all named types contained within this schema.\n Any named type which can be found through a field of any introspection type\n must be included in this set.\n- `directives` must return the set of all directives available within this\n schema including all built-in directives.\n\n### The \\_\\_Type Type\n\n`__Type` is at the core of the type introspection system. It represents all\ntypes in the system: both named types (e.g. Scalars and Object types) and type\nmodifiers (e.g. List and Non-Null types).\n\nType modifiers are used to modify the type presented in the field `ofType`. This\nmodified type may recursively be a modified type, representing a list or\nnon-null type, and combinations thereof, ultimately modifying a named type.\n\nThere are several different kinds of type. In each kind, different fields are\nactually valid. All possible kinds are listed in the `__TypeKind` enum.\n\nEach sub-section below defines the expected fields of `__Type` given each\npossible value of the `__TypeKind` enum:\n\n- {\"SCALAR\"}\n- {\"OBJECT\"}\n- {\"INTERFACE\"}\n- {\"UNION\"}\n- {\"ENUM\"}\n- {\"INPUT_OBJECT\"}\n- {\"LIST\"}\n- {\"NON_NULL\"}\n\n**Scalar**\n\nRepresents scalar types such as Int, String, and Boolean. Scalars cannot have\nfields.\n\nAlso represents [Custom scalars](#sec-Scalars.Custom-Scalars) which may provide\n`specifiedByURL` as a _scalar specification URL_.\n\nFields\\:\n\n- `kind` must return `__TypeKind.SCALAR`.\n- `name` must return a String.\n- `description` may return a String or {null}.\n- `specifiedByURL` may return a String (in the form of a URL) for custom\n scalars, otherwise must be {null}.\n- All other fields must return {null}.\n\n**Object**\n\nObject types represent concrete instantiations of sets of fields. The\nintrospection types (e.g. `__Type`, `__Field`, etc.) are examples of objects.\n\nFields\\:\n\n- `kind` must return `__TypeKind.OBJECT`.\n- `name` must return a String.\n- `description` may return a String or {null}.\n- `fields` must return the set of fields that can be selected for this type.\n - Accepts the argument `includeDeprecated` which defaults to {false}. If\n {true}, deprecated fields are also returned.\n- `interfaces` must return the set of interfaces that an object implements (if\n none, `interfaces` must return the empty set).\n- All other fields must return {null}.\n\n**Union**\n\nUnions are an abstract type where no common fields are declared. The possible\ntypes of a union are explicitly listed out in `possibleTypes`. An object type\ncan be a member of a union without modification to that type.\n\nFields\\:\n\n- `kind` must return `__TypeKind.UNION`.\n- `name` must return a String.\n- `description` may return a String or {null}.\n- `possibleTypes` returns the list of types that can be represented within this\n union. They must be object types.\n- All other fields must return {null}.\n\n**Interface**\n\nInterfaces are an abstract type where there are common fields declared. Any type\nthat implements an interface must define all the named fields where each\nimplementing field type is equal to or a sub-type of (covariant) the interface\ntype. The implementations of this interface are explicitly listed out in\n`possibleTypes`.\n\nFields\\:\n\n- `kind` must return `__TypeKind.INTERFACE`.\n- `name` must return a String.\n- `description` may return a String or {null}.\n- `fields` must return the set of fields required by this interface.\n - Accepts the argument `includeDeprecated` which defaults to {false}. If\n {true}, deprecated fields are also returned.\n- `interfaces` must return the set of interfaces that an interface implements\n (if none, `interfaces` must return the empty set).\n- `possibleTypes` returns the list of types that implement this interface. They\n must be object types.\n- All other fields must return {null}.\n\n**Enum**\n\nEnums are special scalars that can only have a defined set of values.\n\nFields\\:\n\n- `kind` must return `__TypeKind.ENUM`.\n- `name` must return a String.\n- `description` may return a String or {null}.\n- `enumValues` must return the set of enum values as a list of `__EnumValue`.\n There must be at least one and they must have unique names.\n - Accepts the argument `includeDeprecated` which defaults to {false}. If\n {true}, deprecated enum values are also returned.\n- All other fields must return {null}.\n\n**Input Object**\n\nInput objects are composite types defined as a list of named input values. They\nare only used as inputs to arguments and variables and cannot be a field return\ntype.\n\nFor example the input object `Point` could be defined as:\n\n```graphql example\ninput Point {\n x: Int\n y: Int\n}\n```\n\nFields\\:\n\n- `kind` must return `__TypeKind.INPUT_OBJECT`.\n- `name` must return a String.\n- `description` may return a String or {null}.\n- `inputFields` must return the set of input fields as a list of `__InputValue`.\n - Accepts the argument `includeDeprecated` which defaults to {false}. If\n {true}, deprecated input fields are also returned.\n- `isOneOf` must return {true} when representing a _OneOf Input Object_,\n otherwise {false}.\n- All other fields must return {null}.\n\n**List**\n\nLists represent sequences of values in GraphQL. A List type is a type modifier:\nit wraps another type instance in the `ofType` field, which defines the type of\neach item in the list.\n\nThe modified type in the `ofType` field may itself be a modified type, allowing\nthe representation of Lists of Lists, or Lists of Non-Nulls.\n\nFields\\:\n\n- `kind` must return `__TypeKind.LIST`.\n- `ofType` must return a type of any kind.\n- All other fields must return {null}.\n\n**Non-Null**\n\nGraphQL types are nullable. The value {null} is a valid response for field type.\n\nA Non-Null type is a type modifier: it wraps another type instance in the\n`ofType` field. Non-null types do not allow {null} as a response, and indicate\nrequired inputs for arguments and input object fields.\n\nThe modified type in the `ofType` field may itself be a modified List type,\nallowing the representation of Non-Null of Lists. However it must not be a\nmodified Non-Null type to avoid a redundant Non-Null of Non-Null.\n\nFields\\:\n\n- `kind` must return `__TypeKind.NON_NULL`.\n- `ofType` must return a type of any kind except Non-Null.\n- All other fields must return {null}.\n\n### The \\_\\_Field Type\n\nThe `__Field` type represents each field in an Object or Interface type.\n\nFields\\:\n\n- `name` must return a String.\n- `description` may return a String or {null}.\n- `args` returns a List of `__InputValue` representing the arguments this field\n accepts.\n - Accepts the argument `includeDeprecated` which defaults to {false}. If\n {true}, deprecated arguments are also returned.\n- `type` must return a `__Type` that represents the type of value returned by\n this field.\n- `isDeprecated` returns {true} if this field should no longer be used,\n otherwise {false}.\n- `deprecationReason` returns the reason why this field is deprecated, or null\n if this field is not deprecated.\n\n### The \\_\\_InputValue Type\n\nThe `__InputValue` type represents field and directive arguments as well as the\n`inputFields` of an input object.\n\nFields\\:\n\n- `name` must return a String.\n- `description` may return a String or {null}.\n- `type` must return a `__Type` that represents the type this input value\n expects.\n- `defaultValue` may return a String encoding (using the GraphQL language) of\n the default value used by this input value in the condition a value is not\n provided at runtime. If this input value has no default value, returns {null}.\n- `isDeprecated` returns {true} if this input field or argument should no longer\n be used, otherwise {false}.\n- `deprecationReason` returns the reason why this input field or argument is\n deprecated, or null if the input field or argument is not deprecated.\n\n### The \\_\\_EnumValue Type\n\nThe `__EnumValue` type represents one of possible values of an enum.\n\nFields\\:\n\n- `name` must return a String.\n- `description` may return a String or {null}.\n- `isDeprecated` returns {true} if this enum value should no longer be used,\n otherwise {false}.\n- `deprecationReason` returns the reason why this enum value is deprecated, or\n null if the enum value is not deprecated.\n\n### The \\_\\_Directive Type\n\nThe `__Directive` type represents a directive that a service supports.\n\nThis includes both any _built-in directive_ and any _custom directive_.\n\nIndividual directives may only be used in locations that are explicitly\nsupported. All possible locations are listed in the `__DirectiveLocation` enum:\n\n- {\"QUERY\"}\n- {\"MUTATION\"}\n- {\"SUBSCRIPTION\"}\n- {\"FIELD\"}\n- {\"FRAGMENT_DEFINITION\"}\n- {\"FRAGMENT_SPREAD\"}\n- {\"INLINE_FRAGMENT\"}\n- {\"VARIABLE_DEFINITION\"}\n- {\"SCHEMA\"}\n- {\"SCALAR\"}\n- {\"OBJECT\"}\n- {\"FIELD_DEFINITION\"}\n- {\"ARGUMENT_DEFINITION\"}\n- {\"INTERFACE\"}\n- {\"UNION\"}\n- {\"ENUM\"}\n- {\"ENUM_VALUE\"}\n- {\"INPUT_OBJECT\"}\n- {\"INPUT_FIELD_DEFINITION\"}\n\nFields\\:\n\n- `name` must return a String.\n- `description` may return a String or {null}.\n- `locations` returns a List of `__DirectiveLocation` representing the valid\n locations this directive may be placed.\n- `args` returns a List of `__InputValue` representing the arguments this\n directive accepts.\n - Accepts the argument `includeDeprecated` which defaults to {false}. If\n {true}, deprecated arguments are also returned.\n- `isRepeatable` must return a Boolean that indicates if the directive may be\n used repeatedly at a single location.\n" }, { "path": "spec/Section 5 -- Validation.md", "content": "# Validation\n\nA GraphQL service does not just verify if a request is syntactically correct,\nbut also ensures that it is unambiguous and mistake-free in the context of a\ngiven GraphQL schema.\n\nAn invalid request is still technically executable, and will always produce a\nstable result as defined by the algorithms in the Execution section, however\nthat result may be ambiguous, surprising, or unexpected relative to a request\ncontaining validation errors, so execution should only occur for valid requests.\n\nTypically validation is performed in the context of a request immediately before\nexecution, however a GraphQL service may execute a request without explicitly\nvalidating it if that exact same request is known to have been validated before.\nFor example: the request may be validated during development, provided it does\nnot later change, or a service may validate a request once and memoize the\nresult to avoid validating the same request again in the future. Any client-side\nor development-time tool should report validation errors and not allow the\nformulation or execution of requests known to be invalid at that given point in\ntime.\n\n**Type System Evolution**\n\nAs GraphQL type system schema evolves over time by adding new types and new\nfields, it is possible that a request which was previously valid could later\nbecome invalid. Any change that can cause a previously valid request to become\ninvalid is considered a _breaking change_. GraphQL services and schema\nmaintainers are encouraged to avoid breaking changes, however in order to be\nmore resilient to these breaking changes, sophisticated GraphQL systems may\nstill allow for the execution of requests which _at some point_ were known to be\nfree of any validation errors, and have not changed since.\n\n**Examples**\n\nThe examples in this section will use the following types:\n\n```graphql example\ntype Query {\n dog: Dog\n findDog(searchBy: FindDogInput): Dog\n}\n\ntype Mutation {\n addPet(pet: PetInput!): Pet\n addPets(pets: [PetInput!]!): [Pet]\n}\n\nenum DogCommand {\n SIT\n DOWN\n HEEL\n}\n\ntype Dog implements Pet {\n name: String!\n nickname: String\n barkVolume: Int\n doesKnowCommand(dogCommand: DogCommand!): Boolean!\n isHouseTrained(atOtherHomes: Boolean): Boolean!\n owner: Human\n}\n\ninterface Sentient {\n name: String!\n}\n\ninterface Pet {\n name: String!\n}\n\ntype Alien implements Sentient {\n name: String!\n homePlanet: String\n}\n\ntype Human implements Sentient {\n name: String!\n pets: [Pet!]\n}\n\nenum CatCommand {\n JUMP\n}\n\ntype Cat implements Pet {\n name: String!\n nickname: String\n doesKnowCommand(catCommand: CatCommand!): Boolean!\n meowVolume: Int\n}\n\nunion CatOrDog = Cat | Dog\nunion DogOrHuman = Dog | Human\nunion HumanOrAlien = Human | Alien\n\ninput FindDogInput {\n name: String\n owner: String\n}\n\ninput CatInput {\n name: String!\n nickname: String\n meowVolume: Int\n}\n\ninput DogInput {\n name: String!\n nickname: String\n barkVolume: Int\n}\n\ninput PetInput @oneOf {\n cat: CatInput\n dog: DogInput\n}\n```\n\n## Documents\n\n### Executable Definitions\n\n**Formal Specification**\n\n- For each definition {definition} in the document:\n - {definition} must be {ExecutableDefinition} (it must not be\n {TypeSystemDefinitionOrExtension}).\n\n**Explanatory Text**\n\nGraphQL execution will only consider the executable definitions Operation and\nFragment. Type system definitions and extensions are not executable, and are not\nconsidered during execution.\n\nTo avoid ambiguity, a document containing {TypeSystemDefinitionOrExtension} is\ninvalid for execution.\n\nGraphQL documents not intended to be directly executed may include\n{TypeSystemDefinitionOrExtension}.\n\nFor example, the following document is invalid for execution since the original\nexecuting schema may not know about the provided type extension:\n\n```graphql counter-example\nquery getDogName {\n dog {\n name\n color\n }\n}\n\nextend type Dog {\n color: String\n}\n```\n\n## Operations\n\n### All Operation Definitions\n\n#### Operation Type Existence\n\n**Formal Specification**\n\n- For each operation definition {operation} in the document:\n - Let {rootOperationType} be the _root operation type_ in {schema}\n corresponding to the kind of {operation}.\n - {rootOperationType} must exist.\n\n**Explanatory Text**\n\nA schema defines the _root operation type_ for each kind of operation that it\nsupports. Every schema must support `query` operations, however support for\n`mutation` and `subscription` operations is optional.\n\nIf the schema does not include the necessary _root operation type_ for the kind\nof an operation defined in the document, that operation is invalid since it\ncannot be executed.\n\nFor example given the following schema:\n\n```graphql example\ntype Query {\n hello: String\n}\n```\n\nThe following operation is valid:\n\n```graphql example\nquery helloQuery {\n hello\n}\n```\n\nWhile the following operation is invalid:\n\n```graphql counter-example\nmutation goodbyeMutation {\n goodbye\n}\n```\n\n### Named Operation Definitions\n\n#### Operation Name Uniqueness\n\n**Formal Specification**\n\n- For each operation definition {operation} in the document:\n - Let {operationName} be the name of {operation}.\n - If {operationName} exists:\n - Let {operations} be all operation definitions in the document named\n {operationName}.\n - {operations} must be a set of one.\n\n**Explanatory Text**\n\nEach named operation definition must be unique within a document when referred\nto by its name.\n\nFor example the following document is valid:\n\n```graphql example\nquery getDogName {\n dog {\n name\n }\n}\n\nquery getOwnerName {\n dog {\n owner {\n name\n }\n }\n}\n```\n\nWhile this document is invalid:\n\n```graphql counter-example\nquery getName {\n dog {\n name\n }\n}\n\nquery getName {\n dog {\n owner {\n name\n }\n }\n}\n```\n\nIt is invalid even if the type of each operation is different:\n\n```graphql counter-example\nquery dogOperation {\n dog {\n name\n }\n}\n\nmutation dogOperation {\n mutateDog {\n id\n }\n}\n```\n\n### Anonymous Operation Definitions\n\n#### Lone Anonymous Operation\n\n**Formal Specification**\n\n- Let {operations} be all operation definitions in the document.\n- Let {anonymous} be all anonymous operation definitions in the document.\n- If {operations} is a set of more than 1:\n - {anonymous} must be empty.\n\n**Explanatory Text**\n\nGraphQL allows a shorthand form for defining query operations when only that one\noperation exists in the document.\n\nFor example the following document is valid:\n\n```graphql example\n{\n dog {\n name\n }\n}\n```\n\nWhile this document is invalid:\n\n```graphql counter-example\n{\n dog {\n name\n }\n}\n\nquery getName {\n dog {\n owner {\n name\n }\n }\n}\n```\n\n### Subscription Operation Definitions\n\n#### Single Root Field\n\n**Formal Specification**\n\n- Let {subscriptionType} be the root Subscription type in {schema}.\n- For each subscription operation definition {subscription} in the document:\n - Let {selectionSet} be the top level selection set on {subscription}.\n - Let {collectedFieldsMap} be the result of\n {CollectSubscriptionFields(subscriptionType, selectionSet)}.\n - {collectedFieldsMap} must have exactly one entry, which must not be an\n introspection field.\n\nCollectSubscriptionFields(objectType, selectionSet, visitedFragments):\n\n- If {visitedFragments} is not provided, initialize it to the empty set.\n- Initialize {collectedFieldsMap} to an empty ordered map of ordered sets.\n- For each {selection} in {selectionSet}:\n - {selection} must not provide the `@skip` directive.\n - {selection} must not provide the `@include` directive.\n - If {selection} is a {Field}:\n - Let {responseName} be the _response name_ of {selection} (the alias if\n defined, otherwise the field name).\n - Let {fieldsForResponseKey} be the _field set_ value in\n {collectedFieldsMap} for the key {responseName}; otherwise create the\n entry with an empty ordered set.\n - Add {selection} to the {fieldsForResponseKey}.\n - If {selection} is a {FragmentSpread}:\n - Let {fragmentSpreadName} be the name of {selection}.\n - If {fragmentSpreadName} is in {visitedFragments}, continue with the next\n {selection} in {selectionSet}.\n - Add {fragmentSpreadName} to {visitedFragments}.\n - Let {fragment} be the Fragment in the current Document whose name is\n {fragmentSpreadName}.\n - If no such {fragment} exists, continue with the next {selection} in\n {selectionSet}.\n - Let {fragmentType} be the type condition on {fragment}.\n - If {DoesFragmentTypeApply(objectType, fragmentType)} is {false}, continue\n with the next {selection} in {selectionSet}.\n - Let {fragmentSelectionSet} be the top-level selection set of {fragment}.\n - Let {fragmentCollectedFieldsMap} be the result of calling\n {CollectSubscriptionFields(objectType, fragmentSelectionSet,\n visitedFragments)}.\n - For each {responseName} and {fragmentFields} in\n {fragmentCollectedFieldsMap}:\n - Let {fieldsForResponseKey} be the _field set_ value in\n {collectedFieldsMap} for the key {responseName}; otherwise create the\n entry with an empty ordered set.\n - Add each item from {fragmentFields} to {fieldsForResponseKey}.\n - If {selection} is an {InlineFragment}:\n - Let {fragmentType} be the type condition on {selection}.\n - If {fragmentType} is not {null} and {DoesFragmentTypeApply(objectType,\n fragmentType)} is {false}, continue with the next {selection} in\n {selectionSet}.\n - Let {fragmentSelectionSet} be the top-level selection set of {selection}.\n - Let {fragmentCollectedFieldsMap} be the result of calling\n {CollectSubscriptionFields(objectType, fragmentSelectionSet,\n visitedFragments)}.\n - For each {responseName} and {fragmentFields} in\n {fragmentCollectedFieldsMap}:\n - Let {fieldsForResponseKey} be the _field set_ value in\n {collectedFieldsMap} for the key {responseName}; otherwise create the\n entry with an empty ordered set.\n - Add each item from {fragmentFields} to {fieldsForResponseKey}.\n- Return {collectedFieldsMap}.\n\nNote: This algorithm is very similar to {CollectFields()}, it differs in that it\ndoes not have access to runtime variables and thus the `@skip` and `@include`\ndirectives cannot be used.\n\n**Explanatory Text**\n\nSubscription operations must have exactly one root field.\n\nTo enable us to determine this without access to runtime variables, we must\nforbid the `@skip` and `@include` directives in the root selection set.\n\nValid examples:\n\n```graphql example\nsubscription sub {\n newMessage {\n body\n sender\n }\n}\n```\n\n```graphql example\nsubscription sub {\n ...newMessageFields\n}\n\nfragment newMessageFields on Subscription {\n newMessage {\n body\n sender\n }\n}\n```\n\nInvalid:\n\n```graphql counter-example\nsubscription sub {\n newMessage {\n body\n sender\n }\n disallowedSecondRootField\n}\n```\n\n```graphql counter-example\nsubscription sub {\n ...multipleSubscriptions\n}\n\nfragment multipleSubscriptions on Subscription {\n newMessage {\n body\n sender\n }\n disallowedSecondRootField\n}\n```\n\nWe do not allow the `@skip` and `@include` directives at the root of the\nsubscription operation. The following example is also invalid:\n\n```graphql counter-example\nsubscription requiredRuntimeValidation($bool: Boolean!) {\n newMessage @include(if: $bool) {\n body\n sender\n }\n disallowedSecondRootField @skip(if: $bool)\n}\n```\n\nThe root field of a subscription operation must not be an introspection field.\nThe following example is also invalid:\n\n```graphql counter-example\nsubscription sub {\n __typename\n}\n```\n\nNote: While each subscription must have exactly one root field, a document may\ncontain any number of operations, each of which may contain different root\nfields. When executed, a document containing multiple subscription operations\nmust provide the operation name as described in {GetOperation()}.\n\n## Fields\n\n### Field Selections\n\nField selections must exist on Object, Interface, and Union types.\n\n**Formal Specification**\n\n- For each {selection} in the document:\n - Let {fieldName} be the target field of {selection}.\n - {fieldName} must be defined on type in scope.\n\n**Explanatory Text**\n\nThe target field of a field selection must be defined on the scoped type of the\nselection set. There are no limitations on alias names.\n\nFor example the following fragment would not pass validation:\n\n```graphql counter-example\nfragment fieldNotDefined on Dog {\n meowVolume\n}\n\nfragment aliasedLyingFieldTargetNotDefined on Dog {\n barkVolume: kawVolume\n}\n```\n\nFor interfaces, direct field selection can only be done on fields. Fields of\nconcrete implementers are not relevant to the validity of the given\ninterface-typed selection set.\n\nFor example, the following is valid:\n\n```graphql example\nfragment interfaceFieldSelection on Pet {\n name\n}\n```\n\nand the following is invalid:\n\n```graphql counter-example\nfragment definedOnImplementersButNotInterface on Pet {\n nickname\n}\n```\n\nBecause unions do not define fields, fields may not be directly selected from a\nunion-typed selection set, with the exception of the meta-field {\\_\\_typename}.\nFields from a union-typed selection set must only be queried indirectly via a\nfragment.\n\nFor example the following is valid:\n\n```graphql example\nfragment inDirectFieldSelectionOnUnion on CatOrDog {\n __typename\n ... on Pet {\n name\n }\n ... on Dog {\n barkVolume\n }\n}\n```\n\nBut the following is invalid:\n\n```graphql counter-example\nfragment directFieldSelectionOnUnion on CatOrDog {\n name\n barkVolume\n}\n```\n\n### Field Selection Merging\n\n**Formal Specification**\n\n- Let {set} be any selection set defined in the GraphQL document.\n- {FieldsInSetCanMerge(set)} must be true.\n\nFieldsInSetCanMerge(set):\n\n- Let {fieldsForName} be the set of selections with a given _response name_ in\n {set} including visiting fragments and inline fragments.\n- Given each pair of distinct members {fieldA} and {fieldB} in {fieldsForName}:\n - {SameResponseShape(fieldA, fieldB)} must be true.\n - If the parent types of {fieldA} and {fieldB} are equal or if either is not\n an Object Type:\n - {fieldA} and {fieldB} must have identical field names.\n - {fieldA} and {fieldB} must have identical sets of arguments.\n - Let {mergedSet} be the result of adding the selection set of {fieldA} and\n the selection set of {fieldB}.\n - {FieldsInSetCanMerge(mergedSet)} must be true.\n\nSameResponseShape(fieldA, fieldB):\n\n- Let {typeA} be the return type of {fieldA}.\n- Let {typeB} be the return type of {fieldB}.\n- If {typeA} or {typeB} is Non-Null:\n - If {typeA} or {typeB} is nullable, return {false}.\n - Let {typeA} be the nullable type of {typeA}.\n - Let {typeB} be the nullable type of {typeB}.\n- If {typeA} or {typeB} is List:\n - If {typeA} or {typeB} is not List, return {false}.\n - Let {typeA} be the item type of {typeA}.\n - Let {typeB} be the item type of {typeB}.\n - Repeat from step 3.\n- If {typeA} or {typeB} is Scalar or Enum:\n - If {typeA} and {typeB} are the same type return {true}, otherwise return\n {false}.\n- Assert: {typeA} is an object, union or interface type.\n- Assert: {typeB} is an object, union or interface type.\n- Let {mergedSet} be the result of adding the selection set of {fieldA} and the\n selection set of {fieldB}.\n- Let {fieldsForName} be the set of selections with a given _response name_ in\n {mergedSet} including visiting fragments and inline fragments.\n- Given each pair of distinct members {subfieldA} and {subfieldB} in\n {fieldsForName}:\n - If {SameResponseShape(subfieldA, subfieldB)} is {false}, return {false}.\n- Return {true}.\n\nNote: In prior versions of the spec the term \"composite\" was used to signal a\ntype that is either an Object, Interface or Union type.\n\n**Explanatory Text**\n\nIf multiple field selections with the same _response name_ are encountered\nduring execution, the field and arguments to execute and the resulting value\nshould be unambiguous. Therefore any two field selections which might both be\nencountered for the same object are only valid if they are equivalent.\n\nDuring execution, the simultaneous execution of fields with the same response\nname is accomplished by performing {CollectSubfields()} before their execution.\n\nFor simple hand-written GraphQL, this rule is obviously a clear developer error,\nhowever nested fragments can make this difficult to detect manually.\n\nThe following selections correctly merge:\n\n```graphql example\nfragment mergeIdenticalFields on Dog {\n name\n name\n}\n\nfragment mergeIdenticalAliasesAndFields on Dog {\n otherName: name\n otherName: name\n}\n```\n\nThe following is not able to merge:\n\n```graphql counter-example\nfragment conflictingBecauseAlias on Dog {\n name: nickname\n name\n}\n```\n\nIdentical fields are also merged if they have identical arguments. Both values\nand variables can be correctly merged.\n\nFor example the following correctly merge:\n\n```graphql example\nfragment mergeIdenticalFieldsWithIdenticalArgs on Dog {\n doesKnowCommand(dogCommand: SIT)\n doesKnowCommand(dogCommand: SIT)\n}\n\nfragment mergeIdenticalFieldsWithIdenticalValues on Dog {\n doesKnowCommand(dogCommand: $dogCommand)\n doesKnowCommand(dogCommand: $dogCommand)\n}\n```\n\nThe following do not correctly merge:\n\n```graphql counter-example\nfragment conflictingArgsOnValues on Dog {\n doesKnowCommand(dogCommand: SIT)\n doesKnowCommand(dogCommand: HEEL)\n}\n\nfragment conflictingArgsValueAndVar on Dog {\n doesKnowCommand(dogCommand: SIT)\n doesKnowCommand(dogCommand: $dogCommand)\n}\n\nfragment conflictingArgsWithVars on Dog {\n doesKnowCommand(dogCommand: $varOne)\n doesKnowCommand(dogCommand: $varTwo)\n}\n\nfragment differingArgs on Dog {\n doesKnowCommand(dogCommand: SIT)\n doesKnowCommand\n}\n```\n\nThe following fields would not merge together, however both cannot be\nencountered against the same object, so they are safe:\n\n```graphql example\nfragment safeDifferingFields on Pet {\n ... on Dog {\n volume: barkVolume\n }\n ... on Cat {\n volume: meowVolume\n }\n}\n\nfragment safeDifferingArgs on Pet {\n ... on Dog {\n doesKnowCommand(dogCommand: SIT)\n }\n ... on Cat {\n doesKnowCommand(catCommand: JUMP)\n }\n}\n```\n\nHowever, the field responses must be shapes which can be merged. For example,\nleaf types must not differ. In this example, `someValue` might be a `String` or\nan `Int`:\n\n```graphql counter-example\nfragment conflictingDifferingResponses on Pet {\n ... on Dog {\n someValue: nickname\n }\n ... on Cat {\n someValue: meowVolume\n }\n}\n```\n\n### Leaf Field Selections\n\n**Formal Specification**\n\n- For each {selection} in the document:\n - Let {selectionType} be the unwrapped result type of {selection}.\n - If {selectionType} is a scalar or enum:\n - The subselection set of that selection must be empty.\n - If {selectionType} is an interface, union, or object:\n - The subselection set of that selection must not be empty.\n\n**Explanatory Text**\n\nA field subselection is not allowed on leaf fields. A leaf field is any field\nwith a scalar or enum unwrapped type.\n\nThe following is valid.\n\n```graphql example\nfragment scalarSelection on Dog {\n barkVolume\n}\n```\n\nThe following is invalid.\n\n```graphql counter-example\nfragment scalarSelectionsNotAllowedOnInt on Dog {\n barkVolume {\n sinceWhen\n }\n}\n```\n\nConversely, non-leaf fields must have a field subselection. A non-leaf field is\nany field with an object, interface, or union unwrapped type.\n\nLet's assume the following additions to the query root operation type of the\nschema:\n\n```graphql example\nextend type Query {\n human: Human\n pet: Pet\n catOrDog: CatOrDog\n}\n```\n\nThe following examples are invalid because they include non-leaf fields without\na field subselection.\n\n```graphql counter-example\nquery directQueryOnObjectWithoutSubFields {\n human\n}\n\nquery directQueryOnInterfaceWithoutSubFields {\n pet\n}\n\nquery directQueryOnUnionWithoutSubFields {\n catOrDog\n}\n```\n\nHowever the following example is valid since it includes a field subselection.\n\n```graphql example\nquery directQueryOnObjectWithSubFields {\n human {\n name\n }\n}\n```\n\n## Arguments\n\nArguments are provided to both fields and directives. The following validation\nrules apply in both cases.\n\n### Argument Names\n\n**Formal Specification**\n\n- For each {argument} in the document:\n - Let {argumentName} be the Name of {argument}.\n - Let {argumentDefinition} be the argument definition provided by the parent\n field or definition named {argumentName}.\n - {argumentDefinition} must exist.\n\n**Explanatory Text**\n\nEvery argument provided to a field or directive must be defined in the set of\npossible arguments of that field or directive.\n\nFor example the following are valid:\n\n```graphql example\nfragment argOnRequiredArg on Dog {\n doesKnowCommand(dogCommand: SIT)\n}\n\nfragment argOnOptional on Dog {\n isHouseTrained(atOtherHomes: true) @include(if: true)\n}\n```\n\nthe following is invalid since `command` is not defined on `DogCommand`.\n\n```graphql counter-example\nfragment invalidArgName on Dog {\n doesKnowCommand(command: CLEAN_UP_HOUSE)\n}\n```\n\nand this is also invalid as `unless` is not defined on `@include`.\n\n```graphql counter-example\nfragment invalidArgName on Dog {\n isHouseTrained(atOtherHomes: true) @include(unless: false)\n}\n```\n\nIn order to explore more complicated argument examples, let's add the following\nto our type system:\n\n```graphql example\ntype Arguments {\n multipleRequirements(x: Int!, y: Int!): Int!\n booleanArgField(booleanArg: Boolean): Boolean\n floatArgField(floatArg: Float): Float\n intArgField(intArg: Int): Int\n nonNullBooleanArgField(nonNullBooleanArg: Boolean!): Boolean!\n booleanListArgField(booleanListArg: [Boolean]!): [Boolean]\n optionalNonNullBooleanArgField(optionalBooleanArg: Boolean! = false): Boolean!\n}\n\nextend type Query {\n arguments: Arguments\n}\n```\n\nOrder does not matter in arguments. Therefore both the following examples are\nvalid.\n\n```graphql example\nfragment multipleArgs on Arguments {\n multipleRequirements(x: 1, y: 2)\n}\n\nfragment multipleArgsReverseOrder on Arguments {\n multipleRequirements(y: 2, x: 1)\n}\n```\n\n### Argument Uniqueness\n\nFields and directives treat arguments as a mapping of argument name to value.\nMore than one argument with the same name in an argument set is ambiguous and\ninvalid.\n\n**Formal Specification**\n\n- For each {argument} in the Document:\n - Let {argumentName} be the Name of {argument}.\n - Let {arguments} be all Arguments named {argumentName} in the Argument Set\n which contains {argument}.\n - {arguments} must be the set containing only {argument}.\n\n### Required Arguments\n\n- For each Field or Directive in the document:\n - Let {arguments} be the arguments provided by the Field or Directive.\n - Let {argumentDefinitions} be the set of argument definitions of that Field\n or Directive.\n - For each {argumentDefinition} in {argumentDefinitions}:\n - Let {type} be the expected type of {argumentDefinition}.\n - Let {defaultValue} be the default value of {argumentDefinition}.\n - If {type} is Non-Null and {defaultValue} does not exist:\n - Let {argumentName} be the name of {argumentDefinition}.\n - Let {argument} be the argument in {arguments} named {argumentName}.\n - {argument} must exist.\n - Let {value} be the value of {argument}.\n - {value} must not be the {null} literal.\n\n**Explanatory Text**\n\nArguments can be required. An argument is required if the argument type is\nnon-null and does not have a default value. Otherwise, the argument is optional.\n\nFor example the following are valid:\n\n```graphql example\nfragment goodBooleanArg on Arguments {\n booleanArgField(booleanArg: true)\n}\n\nfragment goodNonNullArg on Arguments {\n nonNullBooleanArgField(nonNullBooleanArg: true)\n}\n```\n\nThe argument can be omitted from a field with a nullable argument.\n\nTherefore the following fragment is valid:\n\n```graphql example\nfragment goodBooleanArgDefault on Arguments {\n booleanArgField\n}\n```\n\nbut this is not valid on a required argument.\n\n```graphql counter-example\nfragment missingRequiredArg on Arguments {\n nonNullBooleanArgField\n}\n```\n\nProviding the explicit value {null} is also not valid since required arguments\nalways have a non-null type.\n\n```graphql counter-example\nfragment missingRequiredArg on Arguments {\n nonNullBooleanArgField(nonNullBooleanArg: null)\n}\n```\n\n## Fragments\n\n### Fragment Declarations\n\n#### Fragment Name Uniqueness\n\n**Formal Specification**\n\n- For each fragment definition {fragment} in the document:\n - Let {fragmentName} be the name of {fragment}.\n - Let {fragments} be all fragment definitions in the document named\n {fragmentName}.\n - {fragments} must be a set of one.\n\n**Explanatory Text**\n\nFragment definitions are referenced in fragment spreads by name. To avoid\nambiguity, each fragment's name must be unique within a document.\n\nInline fragments are not considered fragment definitions, and are unaffected by\nthis validation rule.\n\nFor example the following document is valid:\n\n```graphql example\n{\n dog {\n ...fragmentOne\n ...fragmentTwo\n }\n}\n\nfragment fragmentOne on Dog {\n name\n}\n\nfragment fragmentTwo on Dog {\n owner {\n name\n }\n}\n```\n\nWhile this document is invalid:\n\n```graphql counter-example\n{\n dog {\n ...fragmentOne\n }\n}\n\nfragment fragmentOne on Dog {\n name\n}\n\nfragment fragmentOne on Dog {\n owner {\n name\n }\n}\n```\n\n#### Fragment Spread Type Existence\n\n**Formal Specification**\n\n- For each named spread {namedSpread} in the document:\n - Let {fragment} be the target of {namedSpread}.\n - The target type of {fragment} must be defined in the schema.\n\n**Explanatory Text**\n\nFragments must be specified on types that exist in the schema. This applies for\nboth named and inline fragments. If they are not defined in the schema, the\nfragment is invalid.\n\nFor example the following fragments are valid:\n\n```graphql example\nfragment correctType on Dog {\n name\n}\n\nfragment inlineFragment on Dog {\n ... on Dog {\n name\n }\n}\n\nfragment inlineFragment2 on Dog {\n ... @include(if: true) {\n name\n }\n}\n```\n\nand the following do not validate:\n\n```graphql counter-example\nfragment notOnExistingType on NotInSchema {\n name\n}\n\nfragment inlineNotExistingType on Dog {\n ... on NotInSchema {\n name\n }\n}\n```\n\n#### Fragments on Object, Interface or Union Types\n\n**Formal Specification**\n\n- For each {fragment} defined in the document:\n - The target type of fragment must have kind {UNION}, {INTERFACE}, or\n {OBJECT}.\n\n**Explanatory Text**\n\nFragments can only be declared on unions, interfaces, and objects. They are\ninvalid on scalars. They can only be applied on non-leaf fields. This rule\napplies to both inline and named fragments.\n\nThe following fragment declarations are valid:\n\n```graphql example\nfragment fragOnObject on Dog {\n name\n}\n\nfragment fragOnInterface on Pet {\n name\n}\n\nfragment fragOnUnion on CatOrDog {\n ... on Dog {\n name\n }\n}\n```\n\nand the following are invalid:\n\n```graphql counter-example\nfragment fragOnScalar on Int {\n something\n}\n\nfragment inlineFragOnScalar on Dog {\n ... on Boolean {\n somethingElse\n }\n}\n```\n\n#### Fragments Must Be Used\n\n**Formal Specification**\n\n- For each {fragment} defined in the document:\n - {fragment} must be the target of at least one spread in the document.\n\n**Explanatory Text**\n\nDefined fragments must be used within a document.\n\nFor example the following is an invalid document:\n\n```raw graphql counter-example\nfragment nameFragment on Dog { # unused\n name\n}\n\n{\n dog {\n name\n }\n}\n```\n\n### Fragment Spreads\n\nField selection is also determined by spreading fragments into one another. The\nselection set of the target fragment is combined into the selection set at the\nlevel at which the target fragment is referenced.\n\n#### Fragment Spread Target Defined\n\n**Formal Specification**\n\n- For every {namedSpread} in the document:\n - Let {fragment} be the target of {namedSpread}.\n - {fragment} must be defined in the document.\n\n**Explanatory Text**\n\nNamed fragment spreads must refer to fragments defined within the document. It\nis a validation error if the target of a spread is not defined.\n\n```graphql counter-example\n{\n dog {\n ...undefinedFragment\n }\n}\n```\n\n#### Fragment Spreads Must Not Form Cycles\n\n**Formal Specification**\n\n- For each {fragmentDefinition} in the document:\n - Let {visited} be the empty set.\n - {DetectFragmentCycles(fragmentDefinition, visited)}.\n\nDetectFragmentCycles(fragmentDefinition, visited):\n\n- Let {spreads} be all fragment spread descendants of {fragmentDefinition}.\n- For each {spread} in {spreads}:\n - {visited} must not contain {spread}.\n - Let {nextVisited} be the set including {spread} and members of {visited}.\n - Let {nextFragmentDefinition} be the target of {spread}.\n - {DetectFragmentCycles(nextFragmentDefinition, nextVisited)}.\n\n**Explanatory Text**\n\nThe graph of fragment spreads must not form any cycles including spreading\nitself. Otherwise an operation could infinitely spread or infinitely execute on\ncycles in the underlying data.\n\nThis invalidates fragments that would result in an infinite spread:\n\n```graphql counter-example\n{\n dog {\n ...nameFragment\n }\n}\n\nfragment nameFragment on Dog {\n name\n ...barkVolumeFragment\n}\n\nfragment barkVolumeFragment on Dog {\n barkVolume\n ...nameFragment\n}\n```\n\nIf the above fragments were inlined, this would result in the infinitely large:\n\n```graphql example\n{\n dog {\n name\n barkVolume\n name\n barkVolume\n name\n barkVolume\n name\n # forever...\n }\n}\n```\n\nThis also invalidates fragments that would result in an infinite recursion when\nexecuted against cyclic data:\n\n```graphql counter-example\n{\n dog {\n ...dogFragment\n }\n}\n\nfragment dogFragment on Dog {\n name\n owner {\n ...ownerFragment\n }\n}\n\nfragment ownerFragment on Human {\n name\n pets {\n ...dogFragment\n }\n}\n```\n\n#### Fragment Spread Is Possible\n\n**Formal Specification**\n\n- For each {spread} (named or inline) defined in the document:\n - Let {fragment} be the target of {spread}.\n - Let {fragmentType} be the type condition of {fragment}.\n - Let {parentType} be the type of the selection set containing {spread}.\n - Let {applicableTypes} be the intersection of\n {GetPossibleTypes(fragmentType)} and {GetPossibleTypes(parentType)}.\n - {applicableTypes} must not be empty.\n\nGetPossibleTypes(type):\n\n- If {type} is an object type, return a set containing {type}.\n- If {type} is an interface type, return the set of types implementing {type}.\n- If {type} is a union type, return the set of possible types of {type}.\n\n**Explanatory Text**\n\nFragments are declared on a type and will only apply when the runtime object\ntype matches the type condition. They also are spread within the context of a\nparent type. A fragment spread is only valid if its type condition could ever\napply within the parent type.\n\n##### Object Spreads in Object Scope\n\nIn the scope of an object type, the only valid object type fragment spread is\none that applies to the same type that is in scope.\n\nFor example\n\n```graphql example\nfragment dogFragment on Dog {\n ... on Dog {\n barkVolume\n }\n}\n```\n\nand the following is invalid\n\n```graphql counter-example\nfragment catInDogFragmentInvalid on Dog {\n ... on Cat {\n meowVolume\n }\n}\n```\n\n##### Abstract Spreads in Object Scope\n\nIn scope of an object type, unions or interface spreads can be used if the\nobject type implements the interface or is a member of the union.\n\nFor example\n\n```graphql example\nfragment petNameFragment on Pet {\n name\n}\n\nfragment interfaceWithinObjectFragment on Dog {\n ...petNameFragment\n}\n```\n\nis valid because {Dog} implements Pet.\n\nLikewise\n\n```graphql example\nfragment catOrDogNameFragment on CatOrDog {\n ... on Cat {\n meowVolume\n }\n}\n\nfragment unionWithObjectFragment on Dog {\n ...catOrDogNameFragment\n}\n```\n\nis valid because {Dog} is a member of the {CatOrDog} union. It is worth noting\nthat if one inspected the contents of the {CatOrDogNameFragment} you could note\nthat no valid results would ever be returned. However we do not specify this as\ninvalid because we only consider the fragment declaration, not its body.\n\n##### Object Spreads in Abstract Scope\n\nUnion or interface spreads can be used within the context of an object type\nfragment, but only if the object type is one of the possible types of that\ninterface or union.\n\nFor example, the following fragments are valid:\n\n```graphql example\nfragment petFragment on Pet {\n name\n ... on Dog {\n barkVolume\n }\n}\n\nfragment catOrDogFragment on CatOrDog {\n ... on Cat {\n meowVolume\n }\n}\n```\n\n{petFragment} is valid because {Dog} implements the interface {Pet}.\n{catOrDogFragment} is valid because {Cat} is a member of the {CatOrDog} union.\n\nBy contrast the following fragments are invalid:\n\n```graphql counter-example\nfragment sentientFragment on Sentient {\n ... on Dog {\n barkVolume\n }\n}\n\nfragment humanOrAlienFragment on HumanOrAlien {\n ... on Cat {\n meowVolume\n }\n}\n```\n\n{Dog} does not implement the interface {Sentient} and therefore\n{sentientFragment} can never return meaningful results. Therefore the fragment\nis invalid. Likewise {Cat} is not a member of the union {HumanOrAlien}, and it\ncan also never return meaningful results, making it invalid.\n\n##### Abstract Spreads in Abstract Scope\n\nUnion or interfaces fragments can be used within each other. As long as there\nexists at least _one_ object type that exists in the intersection of the\npossible types of the scope and the spread, the spread is considered valid.\n\nSo for example\n\n```graphql example\nfragment unionWithInterface on Pet {\n ...dogOrHumanFragment\n}\n\nfragment dogOrHumanFragment on DogOrHuman {\n ... on Dog {\n barkVolume\n }\n}\n```\n\nis considered valid because {Dog} implements interface {Pet} and is a member of\n{DogOrHuman}.\n\nHowever\n\n```graphql counter-example\nfragment nonIntersectingInterfaces on Pet {\n ...sentientFragment\n}\n\nfragment sentientFragment on Sentient {\n name\n}\n```\n\nis not valid because there exists no type that implements both {Pet} and\n{Sentient}.\n\n**Interface Spreads in Implemented Interface Scope**\n\nAdditionally, an interface type fragment can always be spread into an interface\nscope which it implements.\n\nIn the example below, the `...resourceFragment` fragments spreads is valid,\nsince `Resource` implements `Node`.\n\n```raw graphql example\ninterface Node {\n id: ID!\n}\n\ninterface Resource implements Node {\n id: ID!\n url: String\n}\n\nfragment interfaceWithInterface on Node {\n ...resourceFragment\n}\n\nfragment resourceFragment on Resource {\n url\n}\n```\n\n## Values\n\n### Values of Correct Type\n\n**Formal Specification**\n\n- For each literal Input Value {value} in the document:\n - Let {type} be the type expected in the position {value} is found.\n - {value} must be coercible to {type} (with the assumption that any\n {variableUsage} nested within {value} will represent a runtime value valid\n for usage in its position).\n\n**Explanatory Text**\n\nLiteral values must be compatible with the type expected in the position they\nare found as per the coercion rules defined in the Type System chapter.\n\nNote: A {ListValue} or {ObjectValue} may contain nested Input Values, some of\nwhich may be a variable usage. The\n[All Variable Usages Are Allowed](#sec-All-Variable-Usages-Are-Allowed)\nvalidation rule ensures that each {variableUsage} is of a type allowed in its\nposition. The [Coercing Variable Values](#sec-Coercing-Variable-Values)\nalgorithm ensures runtime values for variables coerce correctly. Therefore, for\nthe purposes of the \"coercible\" assertion in this validation rule, we can assume\nthe runtime value of each {variableUsage} is valid for usage in its position.\n\nThe type expected in a position includes the type defined by the argument a\nvalue is provided for, the type defined by an input object field a value is\nprovided for, and the type of a variable definition a default value is provided\nfor.\n\nThe following examples are valid use of value literals:\n\n```graphql example\nfragment goodBooleanArg on Arguments {\n booleanArgField(booleanArg: true)\n}\n\nfragment coercedIntIntoFloatArg on Arguments {\n # Note: The input coercion rules for Float allow Int literals.\n floatArgField(floatArg: 123)\n}\n\nquery goodComplexDefaultValue($search: FindDogInput = { name: \"Fido\" }) {\n findDog(searchBy: $search) {\n name\n }\n}\n\nmutation addPet($pet: PetInput! = { cat: { name: \"Brontie\" } }) {\n addPet(pet: $pet) {\n name\n }\n}\n```\n\nNon-coercible values (such as a String into an Int) are invalid. The following\nexamples are invalid:\n\n```graphql counter-example\nfragment stringIntoInt on Arguments {\n intArgField(intArg: \"123\")\n}\n\nquery badComplexValue {\n findDog(searchBy: { name: 123 }) {\n name\n }\n}\n\nmutation oneOfWithNoFields {\n addPet(pet: {}) {\n name\n }\n}\n\nmutation oneOfWithTwoFields($dog: DogInput) {\n addPet(pet: { cat: { name: \"Brontie\" }, dog: $dog }) {\n name\n }\n}\n\nmutation listOfOneOfWithNullableVariable($dog: DogInput) {\n addPets(pets: [{ dog: $dog }]) {\n name\n }\n}\n```\n\n### Input Object Field Names\n\n**Formal Specification**\n\n- For each Input Object Field {inputField} in the document:\n - Let {inputFieldName} be the Name of {inputField}.\n - Let {inputFieldDefinition} be the input field definition provided by the\n parent input object type named {inputFieldName}.\n - {inputFieldDefinition} must exist.\n\n**Explanatory Text**\n\nEvery input field provided in an input object value must be defined in the set\nof possible fields of that input object's expected type.\n\nFor example the following example input object is valid:\n\n```graphql example\n{\n findDog(searchBy: { name: \"Fido\" }) {\n name\n }\n}\n```\n\nWhile the following example input-object uses a field \"favoriteCookieFlavor\"\nwhich is not defined on the expected type:\n\n```graphql counter-example\n{\n findDog(searchBy: { favoriteCookieFlavor: \"Bacon\" }) {\n name\n }\n}\n```\n\n### Input Object Field Uniqueness\n\n**Formal Specification**\n\n- For each input object value {inputObject} in the document:\n - For every {inputField} in {inputObject}:\n - Let {name} be the Name of {inputField}.\n - Let {fields} be all Input Object Fields named {name} in {inputObject}.\n - {fields} must be the set containing only {inputField}.\n\n**Explanatory Text**\n\nInput objects must not contain more than one field of the same name, otherwise\nan ambiguity would exist which includes an ignored portion of syntax.\n\nFor example the following document will not pass validation.\n\n```graphql counter-example\n{\n field(arg: { field: true, field: false })\n}\n```\n\n### Input Object Required Fields\n\n**Formal Specification**\n\n- For each Input Object in the document:\n - Let {fields} be the fields provided by that Input Object.\n - Let {fieldDefinitions} be the set of input field definitions of that Input\n Object.\n - For each {fieldDefinition} in {fieldDefinitions}:\n - Let {type} be the expected type of {fieldDefinition}.\n - Let {defaultValue} be the default value of {fieldDefinition}.\n - If {type} is Non-Null and {defaultValue} does not exist:\n - Let {fieldName} be the name of {fieldDefinition}.\n - Let {field} be the input field in {fields} named {fieldName}.\n - {field} must exist.\n - Let {value} be the value of {field}.\n - {value} must not be the {null} literal.\n\n**Explanatory Text**\n\nInput object fields may be required. Much like a field may have required\narguments, an input object may have required fields. An input field is required\nif it has a non-null type and does not have a default value. Otherwise, the\ninput object field is optional.\n\n## Directives\n\n### Directives Are Defined\n\n**Formal Specification**\n\n- For every {directive} in a document:\n - Let {directiveName} be the name of {directive}.\n - Let {directiveDefinition} be the directive named {directiveName}.\n - {directiveDefinition} must exist.\n\n**Explanatory Text**\n\nGraphQL services define what directives they support. For each usage of a\ndirective, the directive must be available on that service.\n\n### Directives Are in Valid Locations\n\n**Formal Specification**\n\n- For every {directive} in a document:\n - Let {directiveName} be the name of {directive}.\n - Let {directiveDefinition} be the directive named {directiveName}.\n - Let {locations} be the valid locations for {directiveDefinition}.\n - Let {adjacent} be the AST node the directive affects.\n - {adjacent} must be represented by an item within {locations}.\n\n**Explanatory Text**\n\nGraphQL services define what directives they support and where they support\nthem. For each usage of a directive, the directive must be used in a location\nthat the service has declared support for.\n\nFor example the following document will not pass validation because `@skip` does\nnot provide `QUERY` as a valid location.\n\n```graphql counter-example\nquery @skip(if: $foo) {\n field\n}\n```\n\n### Directives Are Unique per Location\n\n**Formal Specification**\n\n- For every {location} in the document for which Directives can apply:\n - Let {directives} be the set of Directives which apply to {location} and are\n not repeatable.\n - For each {directive} in {directives}:\n - Let {directiveName} be the name of {directive}.\n - Let {namedDirectives} be the set of all Directives named {directiveName}\n in {directives}.\n - {namedDirectives} must be a set of one.\n\n**Explanatory Text**\n\nGraphQL allows directives that are defined as `repeatable` to be used more than\nonce on the definition they apply to, possibly with different arguments. In\ncontrast, if a directive is not `repeatable`, then only one occurrence of it is\nallowed per location.\n\nFor example, the following document will not pass validation because\nnon-repeatable `@skip` has been used twice for the same field:\n\n```raw graphql counter-example\nquery ($foo: Boolean = true, $bar: Boolean = false) {\n field @skip(if: $foo) @skip(if: $bar)\n}\n```\n\nHowever the following example is valid because `@skip` has been used only once\nper location, despite being used twice in the operation and on the same named\nfield:\n\n```raw graphql example\nquery ($foo: Boolean = true, $bar: Boolean = false) {\n field @skip(if: $foo) {\n subfieldA\n }\n field @skip(if: $bar) {\n subfieldB\n }\n}\n```\n\n## Variables\n\n### Variable Uniqueness\n\n**Formal Specification**\n\n- For every {operation} in the document:\n - For every {variable} defined on {operation}:\n - Let {variableName} be the name of {variable}.\n - Let {variables} be the set of all variables named {variableName} on\n {operation}.\n - {variables} must be a set of one.\n\n**Explanatory Text**\n\nIf any operation defines more than one variable with the same name, it is\nambiguous and invalid. It is invalid even if the type of the duplicate variable\nis the same.\n\n```graphql counter-example\nquery houseTrainedQuery($atOtherHomes: Boolean, $atOtherHomes: Boolean) {\n dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n}\n```\n\nIt is valid for multiple operations to define a variable with the same name. If\ntwo operations reference the same fragment, it might actually be necessary:\n\n```graphql example\nquery A($atOtherHomes: Boolean) {\n ...HouseTrainedFragment\n}\n\nquery B($atOtherHomes: Boolean) {\n ...HouseTrainedFragment\n}\n\nfragment HouseTrainedFragment on Query {\n dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n}\n```\n\n### Variables Are Input Types\n\n**Formal Specification**\n\n- For every {operation} in a {document}:\n - For every {variable} on each {operation}:\n - Let {variableType} be the type of {variable}.\n - {IsInputType(variableType)} must be {true}.\n\n**Explanatory Text**\n\nVariables can only be input types. Objects, unions, and interfaces cannot be\nused as inputs.\n\nFor these examples, consider the following type system additions:\n\n```graphql example\nextend type Query {\n booleanList(booleanListArg: [Boolean!]): Boolean\n}\n```\n\nThe following operations are valid:\n\n```graphql example\nquery takesBoolean($atOtherHomes: Boolean) {\n dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n}\n\nquery takesComplexInput($search: FindDogInput) {\n findDog(searchBy: $search) {\n name\n }\n}\n\nquery TakesListOfBooleanBang($booleans: [Boolean!]) {\n booleanList(booleanListArg: $booleans)\n}\n```\n\nThe following operations are invalid:\n\n```graphql counter-example\nquery takesCat($cat: Cat) {\n # ...\n}\n\nquery takesDogBang($dog: Dog!) {\n # ...\n}\n\nquery takesListOfPet($pets: [Pet]) {\n # ...\n}\n\nquery takesCatOrDog($catOrDog: CatOrDog) {\n # ...\n}\n```\n\n### All Variable Uses Defined\n\n**Formal Specification**\n\n- For each {operation} in a document:\n - For each {variableUsage} in scope, variable must be in {operation}'s\n variable list.\n - Let {fragments} be every fragment referenced by that {operation}\n transitively.\n - For each {fragment} in {fragments}:\n - For each {variableUsage} in scope of {fragment}, variable must be in\n {operation}'s variable list.\n\n**Explanatory Text**\n\nVariables are scoped on a per-operation basis. That means that any variable used\nwithin the context of an operation must be defined at the top level of that\noperation\n\nFor example:\n\n```graphql example\nquery variableIsDefined($atOtherHomes: Boolean) {\n dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n}\n```\n\nis valid. ${atOtherHomes} is defined by the operation.\n\nBy contrast the following document is invalid:\n\n```graphql counter-example\nquery variableIsNotDefined {\n dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n }\n}\n```\n\n${atOtherHomes} is not defined by the operation.\n\nFragments complicate this rule. Any fragment transitively included by an\noperation has access to the variables defined by that operation. Fragments can\nappear within multiple operations and therefore variable usages must correspond\nto variable definitions in all of those operations.\n\nFor example the following is valid:\n\n```graphql example\nquery variableIsDefinedUsedInSingleFragment($atOtherHomes: Boolean) {\n dog {\n ...isHouseTrainedFragment\n }\n}\n\nfragment isHouseTrainedFragment on Dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n}\n```\n\nsince {isHouseTrainedFragment} is used within the context of the operation\n{variableIsDefinedUsedInSingleFragment} and the variable is defined by that\noperation.\n\nOn the other hand, if a fragment is included within an operation that does not\ndefine a referenced variable, the document is invalid.\n\n```graphql counter-example\nquery variableIsNotDefinedUsedInSingleFragment {\n dog {\n ...isHouseTrainedFragment\n }\n}\n\nfragment isHouseTrainedFragment on Dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n}\n```\n\nThis applies transitively as well, so the following also fails:\n\n```graphql counter-example\nquery variableIsNotDefinedUsedInNestedFragment {\n dog {\n ...outerHouseTrainedFragment\n }\n}\n\nfragment outerHouseTrainedFragment on Dog {\n ...isHouseTrainedFragment\n}\n\nfragment isHouseTrainedFragment on Dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n}\n```\n\nVariables must be defined in all operations in which a fragment is used.\n\n```graphql example\nquery houseTrainedQueryOne($atOtherHomes: Boolean) {\n dog {\n ...isHouseTrainedFragment\n }\n}\n\nquery houseTrainedQueryTwo($atOtherHomes: Boolean) {\n dog {\n ...isHouseTrainedFragment\n }\n}\n\nfragment isHouseTrainedFragment on Dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n}\n```\n\nHowever the following does not validate:\n\n```graphql counter-example\nquery houseTrainedQueryOne($atOtherHomes: Boolean) {\n dog {\n ...isHouseTrainedFragment\n }\n}\n\nquery houseTrainedQueryTwoNotDefined {\n dog {\n ...isHouseTrainedFragment\n }\n}\n\nfragment isHouseTrainedFragment on Dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n}\n```\n\nThis is because {houseTrainedQueryTwoNotDefined} does not define a variable\n${atOtherHomes} but that variable is used by {isHouseTrainedFragment} which is\nincluded in that operation.\n\n### All Variables Used\n\n**Formal Specification**\n\n- For every {operation} in the document:\n - Let {variables} be the variables defined by that {operation}.\n - Each {variable} in {variables} must be used at least once in either the\n operation scope itself or any fragment transitively referenced by that\n operation.\n\n**Explanatory Text**\n\nAll variables defined by an operation must be used in that operation or a\nfragment transitively included by that operation. Unused variables cause a\nvalidation error.\n\nFor example the following is invalid:\n\n```graphql counter-example\nquery variableUnused($atOtherHomes: Boolean) {\n dog {\n isHouseTrained\n }\n}\n```\n\nbecause ${atOtherHomes} is not referenced.\n\nThese rules apply to transitive fragment spreads as well:\n\n```graphql example\nquery variableUsedInFragment($atOtherHomes: Boolean) {\n dog {\n ...isHouseTrainedFragment\n }\n}\n\nfragment isHouseTrainedFragment on Dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n}\n```\n\nThe above is valid since ${atOtherHomes} is used in {isHouseTrainedFragment}\nwhich is included by {variableUsedInFragment}.\n\nIf that fragment did not have a reference to ${atOtherHomes} it would be not\nvalid:\n\n```graphql counter-example\nquery variableNotUsedWithinFragment($atOtherHomes: Boolean) {\n dog {\n ...isHouseTrainedWithoutVariableFragment\n }\n}\n\nfragment isHouseTrainedWithoutVariableFragment on Dog {\n isHouseTrained\n}\n```\n\nAll operations in a document must use all of their variables.\n\nAs a result, the following document does not validate.\n\n```graphql counter-example\nquery queryWithUsedVar($atOtherHomes: Boolean) {\n dog {\n ...isHouseTrainedFragment\n }\n}\n\nquery queryWithExtraVar($atOtherHomes: Boolean, $extra: Int) {\n dog {\n ...isHouseTrainedFragment\n }\n}\n\nfragment isHouseTrainedFragment on Dog {\n isHouseTrained(atOtherHomes: $atOtherHomes)\n}\n```\n\nThis document is not valid because {queryWithExtraVar} defines an extraneous\nvariable.\n\n### All Variable Usages Are Allowed\n\n**Formal Specification**\n\n- For each {operation} in {document}:\n - Let {variableUsages} be all usages transitively included in the {operation}.\n - For each {variableUsage} in {variableUsages}:\n - Let {variableName} be the name of {variableUsage}.\n - Let {variableDefinition} be the {VariableDefinition} named {variableName}\n defined within {operation}.\n - {IsVariableUsageAllowed(variableDefinition, variableUsage)} must be\n {true}.\n\nIsVariableUsageAllowed(variableDefinition, variableUsage):\n\n- Let {variableType} be the expected type of {variableDefinition}.\n- Let {locationType} be the expected type of the {Argument}, {ObjectField}, or\n {ListValue} entry where {variableUsage} is located.\n- If {IsNonNullPosition(locationType, variableUsage)} AND {variableType} is NOT\n a non-null type:\n - Let {hasNonNullVariableDefaultValue} be {true} if a default value exists for\n {variableDefinition} and is not the value {null}.\n - Let {hasLocationDefaultValue} be {true} if a default value exists for the\n {Argument} or {ObjectField} where {variableUsage} is located.\n - If {hasNonNullVariableDefaultValue} is NOT {true} AND\n {hasLocationDefaultValue} is NOT {true}, return {false}.\n - Let {nullableLocationType} be the unwrapped nullable type of {locationType}.\n - Return {AreTypesCompatible(variableType, nullableLocationType)}.\n- Return {AreTypesCompatible(variableType, locationType)}.\n\nIsNonNullPosition(locationType, variableUsage):\n\n- If {locationType} is a non-null type, return {true}.\n- If the location of {variableUsage} is an {ObjectField}:\n - Let {parentObjectValue} be the {ObjectValue} containing {ObjectField}.\n - Let {parentLocationType} be the expected type of {ObjectValue}.\n - If {parentLocationType} is a _OneOf Input Object_ type, return {true}.\n- Return {false}.\n\nAreTypesCompatible(variableType, locationType):\n\n- If {locationType} is a non-null type:\n - If {variableType} is NOT a non-null type, return {false}.\n - Let {nullableLocationType} be the unwrapped nullable type of {locationType}.\n - Let {nullableVariableType} be the unwrapped nullable type of {variableType}.\n - Return {AreTypesCompatible(nullableVariableType, nullableLocationType)}.\n- Otherwise, if {variableType} is a non-null type:\n - Let {nullableVariableType} be the nullable type of {variableType}.\n - Return {AreTypesCompatible(nullableVariableType, locationType)}.\n- Otherwise, if {locationType} is a list type:\n - If {variableType} is NOT a list type, return {false}.\n - Let {itemLocationType} be the unwrapped item type of {locationType}.\n - Let {itemVariableType} be the unwrapped item type of {variableType}.\n - Return {AreTypesCompatible(itemVariableType, itemLocationType)}.\n- Otherwise, if {variableType} is a list type, return {false}.\n- Return {true} if {variableType} and {locationType} are identical, otherwise\n {false}.\n\n**Explanatory Text**\n\nVariable usages must be compatible with the arguments they are passed to.\n\nValidation failures occur when variables are used in the context of types that\nare complete mismatches, or if a nullable type in a variable is passed to a\nnon-null argument type.\n\nTypes must match:\n\n```graphql counter-example\nquery intCannotGoIntoBoolean($intArg: Int) {\n arguments {\n booleanArgField(booleanArg: $intArg)\n }\n}\n```\n\n${intArg} typed as {Int} cannot be used as an argument to {booleanArg}, typed as\n{Boolean}.\n\nList cardinality must also be the same. For example, lists cannot be passed into\nsingular values.\n\n```graphql counter-example\nquery booleanListCannotGoIntoBoolean($booleanListArg: [Boolean]) {\n arguments {\n booleanArgField(booleanArg: $booleanListArg)\n }\n}\n```\n\nNullability must also be respected. In general a nullable variable cannot be\npassed to a non-null argument.\n\n```graphql counter-example\nquery booleanArgQuery($booleanArg: Boolean) {\n arguments {\n nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)\n }\n}\n```\n\nFor list types, the same rules around nullability apply to both outer types and\ninner types. A nullable list cannot be passed to a non-null list, and a list of\nnullable values cannot be passed to a list of non-null values. The following is\nvalid:\n\n```graphql example\nquery nonNullListToList($nonNullBooleanList: [Boolean]!) {\n arguments {\n booleanListArgField(booleanListArg: $nonNullBooleanList)\n }\n}\n```\n\nHowever, a nullable list cannot be passed to a non-null list:\n\n```graphql counter-example\nquery listToNonNullList($booleanList: [Boolean]) {\n arguments {\n nonNullBooleanListField(nonNullBooleanListArg: $booleanList)\n }\n}\n```\n\nThis would fail validation because a `[T]` cannot be passed to a `[T]!`.\nSimilarly a `[T]` cannot be passed to a `[T!]`.\n\nVariables used for OneOf Input Object fields must be non-nullable.\n\n```graphql example\nmutation addCat($cat: CatInput!) {\n addPet(pet: { cat: $cat }) {\n name\n }\n}\n\nmutation addCatWithDefault($cat: CatInput! = { name: \"Brontie\" }) {\n addPet(pet: { cat: $cat }) {\n name\n }\n}\n```\n\n```graphql counter-example\nmutation addNullableCat($cat: CatInput) {\n addPet(pet: { cat: $cat }) {\n name\n }\n}\n```\n\n**Allowing Optional Variables When Default Values Exist**\n\nA notable exception to typical variable type compatibility is allowing a\nvariable definition with a nullable type to be provided to a non-null location\nas long as either that variable or that location provides a default value.\n\nIn the example below, an optional variable `$booleanArg` is allowed to be used\nin the non-null argument `optionalBooleanArg` because the field argument is\noptional since it provides a default value in the schema.\n\n```graphql example\nquery booleanArgQueryWithDefault($booleanArg: Boolean) {\n arguments {\n optionalNonNullBooleanArgField(optionalBooleanArg: $booleanArg)\n }\n}\n```\n\nIn the example below, an optional variable `$booleanArg` is allowed to be used\nin the non-null argument (`nonNullBooleanArg`) because the variable provides a\ndefault value in the operation. This behavior is explicitly supported for\ncompatibility with earlier editions of this specification. GraphQL authoring\ntools may wish to report this as a warning with the suggestion to replace\n`Boolean` with `Boolean!` to avoid ambiguity.\n\n```graphql example\nquery booleanArgQueryWithDefault($booleanArg: Boolean = true) {\n arguments {\n nonNullBooleanArgField(nonNullBooleanArg: $booleanArg)\n }\n}\n```\n\nNote: The value {null} could still be provided to such a variable at runtime. A\nnon-null argument must raise an _execution error_ if provided a {null} value.\n" }, { "path": "spec/Section 6 -- Execution.md", "content": "# Execution\n\nA GraphQL service generates a response from a request via execution.\n\n:: A _request_ for execution consists of a few pieces of information:\n\n- {schema}: The schema to use, typically solely provided by the GraphQL service.\n- {document}: A {Document} which must contain GraphQL {OperationDefinition} and\n may contain {FragmentDefinition}.\n- {operationName} (optional): The name of the Operation in the Document to\n execute.\n- {variableValues} (optional): Values for any Variables defined by the\n Operation.\n- {initialValue} (optional): An initial value corresponding to the root type\n being executed. Conceptually, an initial value represents the \"universe\" of\n data available via a GraphQL Service. It is common for a GraphQL Service to\n always use the same initial value for every request.\n- {extensions} (optional): A map reserved for implementation-specific additional\n information.\n\nGiven this information, the result of {ExecuteRequest(schema, document,\noperationName, variableValues, initialValue)} produces the response, to be\nformatted according to the Response section below.\n\nImplementations should not add additional properties to a _request_, which may\nconflict with future editions of the GraphQL specification. Instead,\n{extensions} provides a reserved location for implementation-specific additional\ninformation. If present, {extensions} must be a map, but there are no additional\nrestrictions on its contents. To avoid conflicts, keys should use unique\nprefixes.\n\nNote: GraphQL requests do not require any specific serialization format or\ntransport mechanism. Message serialization and transport mechanisms should be\nchosen by the implementing service.\n\nNote: Descriptions and comments in executable documents (operation definitions,\nfragment definitions, and variable definitions) MUST be ignored during execution\nand have no effect on the observable execution, validation, or response of a\nGraphQL document. Descriptions and comments on executable documents MAY be used\nfor non-observable purposes, such as logging and other developer tools.\n\n## Executing Requests\n\nTo execute a request, the executor must have a parsed {Document} and a selected\noperation name to run if the document defines multiple operations, otherwise the\ndocument is expected to only contain a single operation. The result of the\nrequest is determined by the result of executing this operation according to the\n\"Executing Operations” section below.\n\nExecuteRequest(schema, document, operationName, variableValues, initialValue):\n\n- Let {operation} be the result of {GetOperation(document, operationName)}.\n- Let {coercedVariableValues} be the result of {CoerceVariableValues(schema,\n operation, variableValues)}.\n- If {operation} is a query operation:\n - Return {ExecuteQuery(operation, schema, coercedVariableValues,\n initialValue)}.\n- Otherwise if {operation} is a mutation operation:\n - Return {ExecuteMutation(operation, schema, coercedVariableValues,\n initialValue)}.\n- Otherwise if {operation} is a subscription operation:\n - Return {Subscribe(operation, schema, coercedVariableValues, initialValue)}.\n\nGetOperation(document, operationName):\n\n- If {operationName} is {null}:\n - If {document} contains exactly one operation.\n - Return the Operation contained in the {document}.\n - Otherwise raise a _request error_ requiring {operationName}.\n- Otherwise:\n - Let {operation} be the Operation named {operationName} in {document}.\n - If {operation} was not found, raise a _request error_.\n - Return {operation}.\n\n### Validating Requests\n\nAs explained in the Validation section, only requests which pass all validation\nrules should be executed. If validation errors are known, they should be\nreported in the list of \"errors\" in the response and the request must fail\nwithout execution.\n\nTypically validation is performed in the context of a request immediately before\nexecution, however a GraphQL service may execute a request without immediately\nvalidating it if that exact same request is known to have been validated before.\nA GraphQL service should only execute requests which _at some point_ were known\nto be free of any validation errors, and have since not changed.\n\nFor example: the request may be validated during development, provided it does\nnot later change, or a service may validate a request once and memoize the\nresult to avoid validating the same request again in the future.\n\n### Coercing Variable Values\n\nIf the operation has defined any variables, then the values for those variables\nneed to be coerced using the input coercion rules of the variable's declared\ntype. If a _request error_ is encountered during input coercion of variable\nvalues, then the operation fails without execution.\n\nCoerceVariableValues(schema, operation, variableValues):\n\n- Let {coercedValues} be an empty unordered Map.\n- Let {variablesDefinition} be the variables defined by {operation}.\n- For each {variableDefinition} in {variablesDefinition}:\n - Let {variableName} be the name of {variableDefinition}.\n - Let {variableType} be the expected type of {variableDefinition}.\n - Assert: {IsInputType(variableType)} must be {true}.\n - Let {defaultValue} be the default value for {variableDefinition}.\n - Let {hasValue} be {true} if {variableValues} provides a value for the name\n {variableName}.\n - Let {value} be the value provided in {variableValues} for the name\n {variableName}.\n - If {hasValue} is not {true} and {defaultValue} exists (including {null}):\n - Let {coercedDefaultValue} be the result of coercing {defaultValue}\n according to the input coercion rules of {variableType}.\n - Add an entry to {coercedValues} named {variableName} with the value\n {coercedDefaultValue}.\n - Otherwise if {variableType} is a Non-Nullable type, and either {hasValue} is\n not {true} or {value} is {null}, raise a _request error_.\n - Otherwise if {hasValue} is {true}:\n - If {value} is {null}:\n - Add an entry to {coercedValues} named {variableName} with the value\n {null}.\n - Otherwise:\n - If {value} cannot be coerced according to the input coercion rules of\n {variableType}, raise a _request error_.\n - Let {coercedValue} be the result of coercing {value} according to the\n input coercion rules of {variableType}.\n - Add an entry to {coercedValues} named {variableName} with the value\n {coercedValue}.\n- Return {coercedValues}.\n\nNote: This algorithm is very similar to {CoerceArgumentValues()}.\n\n## Executing Operations\n\nThe type system, as described in the \"Type System\" section of the spec, must\nprovide a query root operation type. If mutations or subscriptions are\nsupported, it must also provide a mutation or subscription root operation type,\nrespectively.\n\n### Query\n\nIf the operation is a query, the result of the operation is the result of\nexecuting the operation’s _root selection set_ with the query root operation\ntype.\n\nAn initial value may be provided when executing a query operation.\n\nExecuteQuery(query, schema, variableValues, initialValue):\n\n- Let {queryType} be the root Query type in {schema}.\n- Assert: {queryType} is an Object type.\n- Let {rootSelectionSet} be the _root selection set_ in {query}.\n- Return {ExecuteRootSelectionSet(variableValues, initialValue, queryType,\n rootSelectionSet, \"normal\")}.\n\n### Mutation\n\nIf the operation is a mutation, the result of the operation is the result of\nexecuting the operation’s _root selection set_ on the mutation root object type.\nThis selection set should be executed serially.\n\nIt is expected that the top level fields in a mutation operation perform\nside-effects on the underlying data system. Serial execution of the provided\nmutations ensures against race conditions during these side-effects.\n\nExecuteMutation(mutation, schema, variableValues, initialValue):\n\n- Let {mutationType} be the root Mutation type in {schema}.\n- Assert: {mutationType} is an Object type.\n- Let {rootSelectionSet} be the _root selection set_ in {mutation}.\n- Return {ExecuteRootSelectionSet(variableValues, initialValue, mutationType,\n rootSelectionSet, \"serial\")}.\n\n### Subscription\n\nIf the operation is a subscription, the result is an _event stream_ called the\n_response stream_ where each event in the event stream is the result of\nexecuting the operation for each new event on an underlying _source stream_.\n\nExecuting a subscription operation creates a persistent function on the service\nthat maps an underlying _source stream_ to a returned _response stream_.\n\nSubscribe(subscription, schema, variableValues, initialValue):\n\n- Let {sourceStream} be the result of running\n {CreateSourceEventStream(subscription, schema, variableValues, initialValue)}.\n- Let {responseStream} be the result of running\n {MapSourceToResponseEvent(sourceStream, subscription, schema,\n variableValues)}.\n- Return {responseStream}.\n\nNote: In a large-scale subscription system, the {Subscribe()} and\n{ExecuteSubscriptionEvent()} algorithms may be run on separate services to\nmaintain predictable scaling properties. See the section below on Supporting\nSubscriptions at Scale.\n\nAs an example, consider a chat application. To subscribe to new messages posted\nto the chat room, the client sends a request like so:\n\n```graphql example\nsubscription NewMessages {\n newMessage(roomId: 123) {\n sender\n text\n }\n}\n```\n\nWhile the client is subscribed, whenever new messages are posted to chat room\nwith ID \"123\", the selection for \"sender\" and \"text\" will be evaluated and\npublished to the client, for example:\n\n```json example\n{\n \"data\": {\n \"newMessage\": {\n \"sender\": \"Hagrid\",\n \"text\": \"You're a wizard!\"\n }\n }\n}\n```\n\nThe \"new message posted to chat room\" could use a \"Pub-Sub\" system where the\nchat room ID is the \"topic\" and each \"publish\" contains the sender and text.\n\n**Event Streams**\n\n:: An _event stream_ represents a sequence of events: discrete emitted values\nover time which can be observed. As an example, a \"Pub-Sub\" system may produce\nan _event stream_ when \"subscribing to a topic\", with an value emitted for each\n\"publish\" to that topic.\n\nAn _event stream_ may complete at any point, often because no further events\nwill occur. An _event stream_ may emit an infinite sequence of values, in which\nit may never complete. If an _event stream_ encounters an error, it must\ncomplete with that error.\n\nAn observer may at any point decide to stop observing an _event stream_ by\ncancelling it. When an _event stream_ is cancelled, it must complete.\n\nInternal user code also may cancel an _event stream_ for any reason, which would\nbe observed as that _event stream_ completing.\n\n**Supporting Subscriptions at Scale**\n\nQuery and mutation operations are stateless, allowing scaling via cloning of\nGraphQL service instances. Subscriptions, by contrast, are stateful and require\nmaintaining the GraphQL document, variables, and other context over the lifetime\nof the subscription.\n\nConsider the behavior of your system when state is lost due to the failure of a\nsingle machine in a service. Durability and availability may be improved by\nhaving separate dedicated services for managing subscription state and client\nconnectivity.\n\n**Delivery Agnostic**\n\nGraphQL subscriptions do not require any specific serialization format or\ntransport mechanism. GraphQL specifies algorithms for the creation of the\nresponse stream, the content of each payload on that stream, and the closing of\nthat stream. There are intentionally no specifications for message\nacknowledgement, buffering, resend requests, or any other quality of service\n(QoS) details. Message serialization, transport mechanisms, and quality of\nservice details should be chosen by the implementing service.\n\n#### Source Stream\n\n:: A _source stream_ is an _event stream_ representing a sequence of root\nvalues, each of which will trigger a GraphQL execution. Like field value\nresolution, the logic to create a _source stream_ is application-specific.\n\nCreateSourceEventStream(subscription, schema, variableValues, initialValue):\n\n- Let {subscriptionType} be the root Subscription type in {schema}.\n- Assert: {subscriptionType} is an Object type.\n- Let {selectionSet} be the top level selection set in {subscription}.\n- Let {collectedFieldsMap} be the result of {CollectFields(subscriptionType,\n selectionSet, variableValues)}.\n- If {collectedFieldsMap} does not have exactly one entry, raise a _request\n error_.\n- Let {fields} be the value of the first entry in {collectedFieldsMap}.\n- Let {fieldName} be the name of the first entry in {fields}. Note: This value\n is unaffected if an alias is used.\n- Let {field} be the first entry in {fields}.\n- Let {argumentValues} be the result of {CoerceArgumentValues(subscriptionType,\n field, variableValues)}.\n- Let {sourceStream} be the result of running\n {ResolveFieldEventStream(subscriptionType, initialValue, fieldName,\n argumentValues)}.\n- Return {sourceStream}.\n\nResolveFieldEventStream(subscriptionType, rootValue, fieldName, argumentValues):\n\n- Let {resolver} be the internal function provided by {subscriptionType} for\n determining the resolved _event stream_ of a subscription field named\n {fieldName}.\n- Return the result of calling {resolver}, providing {rootValue} and\n {argumentValues}.\n\nNote: This {ResolveFieldEventStream()} algorithm is intentionally similar to\n{ResolveFieldValue()} to enable consistency when defining resolvers on any\noperation type.\n\n#### Response Stream\n\nEach event from the underlying _source stream_ triggers execution of the\nsubscription _selection set_ using that event's value as the {initialValue}.\n\nMapSourceToResponseEvent(sourceStream, subscription, schema, variableValues):\n\n- Let {responseStream} be a new _event stream_.\n- When {sourceStream} emits {sourceValue}:\n - Let {executionResult} be the result of running\n {ExecuteSubscriptionEvent(subscription, schema, variableValues,\n sourceValue)}.\n - If internal {error} was raised:\n - Cancel {sourceStream}.\n - Complete {responseStream} with {error}.\n - Otherwise emit {executionResult} on {responseStream}.\n- When {sourceStream} completes normally:\n - Complete {responseStream} normally.\n- When {sourceStream} completes with {error}:\n - Complete {responseStream} with {error}.\n- When {responseStream} is cancelled:\n - Cancel {sourceStream}.\n - Complete {responseStream} normally.\n- Return {responseStream}.\n\nNote: Since {ExecuteSubscriptionEvent()} handles all _execution error_, and\n_request error_ only occur during {CreateSourceEventStream()}, the only\nremaining error condition handled from {ExecuteSubscriptionEvent()} are internal\nexceptional errors not described by this specification.\n\nExecuteSubscriptionEvent(subscription, schema, variableValues, initialValue):\n\n- Let {subscriptionType} be the root Subscription type in {schema}.\n- Assert: {subscriptionType} is an Object type.\n- Let {rootSelectionSet} be the _root selection set_ in {subscription}.\n- Return {ExecuteRootSelectionSet(variableValues, initialValue,\n subscriptionType, rootSelectionSet, \"normal\")}.\n\nNote: The {ExecuteSubscriptionEvent()} algorithm is intentionally similar to\n{ExecuteQuery()} since this is how each event result is produced.\n\n#### Unsubscribe\n\nUnsubscribe cancels the _response stream_ when a client no longer wishes to\nreceive payloads for a subscription. This in turn also cancels the Source\nStream, which is a good opportunity to clean up any other resources used by the\nsubscription.\n\nUnsubscribe(responseStream):\n\n- Cancel {responseStream}.\n\n## Executing Selection Sets\n\nExecuting a GraphQL operation recursively collects and executes every selected\nfield in the operation. First all initially selected fields from the operation's\ntop most _root selection set_ are collected, then each executed. As each field\ncompletes, all its subfields are collected, then each executed. This process\ncontinues until there are no more subfields to collect and execute.\n\n### Executing the Root Selection Set\n\n:: A _root selection set_ is the top level _selection set_ provided by a GraphQL\noperation. A root selection set always selects from a _root operation type_.\n\nTo execute the root selection set, the initial value being evaluated and the\nroot type must be known, as well as whether the fields must be executed in a\nseries, or normally by executing all fields in parallel (see\n[Normal and Serial Execution](#sec-Normal-and-Serial-Execution)).\n\nExecuting the root selection set works similarly for queries (parallel),\nmutations (serial), and subscriptions (where it is executed for each event in\nthe underlying Source Stream).\n\nFirst, the _selection set_ is collected into a _collected fields map_ which is\nthen executed, returning the resulting {data} and {errors}.\n\nExecuteRootSelectionSet(variableValues, initialValue, objectType, selectionSet,\nexecutionMode):\n\n- Let {collectedFieldsMap} be the result of {CollectFields(objectType,\n selectionSet, variableValues)}.\n- Let {data} be the result of running\n {ExecuteCollectedFields(collectedFieldsMap, objectType, initialValue,\n variableValues)} _serially_ if {executionMode} is {\"serial\"}, otherwise\n _normally_ (allowing parallelization)).\n- Let {errors} be the list of all _execution error_ raised while executing the\n selection set.\n- Return an unordered map containing {data} and {errors}.\n\n### Field Collection\n\nBefore execution, each _selection set_ is converted to a _collected fields map_\nby collecting all fields with the same response name, including those in\nreferenced fragments, into an individual _field set_. This ensures that multiple\nreferences to fields with the same response name will only be executed once.\n\n:: A _collected fields map_ is an ordered map where each entry is a _response\nname_ and its associated _field set_. A _collected fields map_ may be produced\nfrom a selection set via {CollectFields()} or from the selection sets of all\nentries of a _field set_ via {CollectSubfields()}.\n\n:: A _field set_ is an ordered set of selected fields that share the same\n_response name_ (the field alias if defined, otherwise the field's name).\nValidation ensures each field in the set has the same name and arguments,\nhowever each may have different subfields (see:\n[Field Selection Merging](#sec-Field-Selection-Merging)).\n\nNote: The order of field selections in both a _collected fields map_ and a\n_field set_ are significant, hence the algorithms in this specification model\nthem as an ordered map and ordered set.\n\nAs an example, collecting the fields of this query's selection set would result\nin a collected fields map with two entries, `\"a\"` and `\"b\"`, with two instances\nof the field `a` and one of field `b`:\n\n```graphql example\n{\n a {\n subfield1\n }\n ...ExampleFragment\n}\n\nfragment ExampleFragment on Query {\n a {\n subfield2\n }\n b\n}\n```\n\nThe depth-first-search order of each _field set_ produced by {CollectFields()}\nis maintained through execution, ensuring that fields appear in the executed\nresponse in a stable and predictable order.\n\nCollectFields(objectType, selectionSet, variableValues, visitedFragments):\n\n- If {visitedFragments} is not provided, initialize it to the empty set.\n- Initialize {collectedFieldsMap} to an empty ordered map of ordered sets.\n- For each {selection} in {selectionSet}:\n - If {selection} provides the directive `@skip`, let {skipDirective} be that\n directive.\n - If {skipDirective}'s {if} argument is {true} or is a variable in\n {variableValues} with the value {true}, continue with the next {selection}\n in {selectionSet}.\n - If {selection} provides the directive `@include`, let {includeDirective} be\n that directive.\n - If {includeDirective}'s {if} argument is not {true} and is not a variable\n in {variableValues} with the value {true}, continue with the next\n {selection} in {selectionSet}.\n - If {selection} is a {Field}:\n - Let {responseName} be the _response name_ of {selection} (the alias if\n defined, otherwise the field name).\n - Let {fieldsForResponseName} be the _field set_ value in\n {collectedFieldsMap} for the key {responseName}; otherwise create the\n entry with an empty ordered set.\n - Add {selection} to the {fieldsForResponseName}.\n - If {selection} is a {FragmentSpread}:\n - Let {fragmentSpreadName} be the name of {selection}.\n - If {fragmentSpreadName} is in {visitedFragments}, continue with the next\n {selection} in {selectionSet}.\n - Add {fragmentSpreadName} to {visitedFragments}.\n - Let {fragment} be the Fragment in the current Document whose name is\n {fragmentSpreadName}.\n - If no such {fragment} exists, continue with the next {selection} in\n {selectionSet}.\n - Let {fragmentType} be the type condition on {fragment}.\n - If {DoesFragmentTypeApply(objectType, fragmentType)} is {false}, continue\n with the next {selection} in {selectionSet}.\n - Let {fragmentSelectionSet} be the top-level selection set of {fragment}.\n - Let {fragmentCollectedFieldsMap} be the result of calling\n {CollectFields(objectType, fragmentSelectionSet, variableValues,\n visitedFragments)}.\n - For each {responseName} and {fragmentFields} in\n {fragmentCollectedFieldsMap}:\n - Let {fieldsForResponseName} be the _field set_ value in\n {collectedFieldsMap} for the key {responseName}; otherwise create the\n entry with an empty ordered set.\n - Add each item from {fragmentFields} to {fieldsForResponseName}.\n - If {selection} is an {InlineFragment}:\n - Let {fragmentType} be the type condition on {selection}.\n - If {fragmentType} is not {null} and {DoesFragmentTypeApply(objectType,\n fragmentType)} is {false}, continue with the next {selection} in\n {selectionSet}.\n - Let {fragmentSelectionSet} be the top-level selection set of {selection}.\n - Let {fragmentCollectedFieldsMap} be the result of calling\n {CollectFields(objectType, fragmentSelectionSet, variableValues,\n visitedFragments)}.\n - For each {responseName} and {fragmentFields} in\n {fragmentCollectedFieldsMap}:\n - Let {fieldsForResponseName} be the _field set_ value in\n {collectedFieldsMap} for the key {responseName}; otherwise create the\n entry with an empty ordered set.\n - Append each item from {fragmentFields} to {fieldsForResponseName}.\n- Return {collectedFieldsMap}.\n\nDoesFragmentTypeApply(objectType, fragmentType):\n\n- If {fragmentType} is an Object Type:\n - If {objectType} and {fragmentType} are the same type, return {true},\n otherwise return {false}.\n- If {fragmentType} is an Interface Type:\n - If {objectType} is an implementation of {fragmentType}, return {true},\n otherwise return {false}.\n- If {fragmentType} is a Union:\n - If {objectType} is a possible type of {fragmentType}, return {true},\n otherwise return {false}.\n\nNote: The steps in {CollectFields()} evaluating the `@skip` and `@include`\ndirectives may be applied in either order since they apply commutatively.\n\n**Merging Selection Sets**\n\nIn order to execute the sub-selections of an object typed field, all _selection\nsets_ of each field with the same response name in the parent _field set_ are\nmerged together into a single _collected fields map_ representing the subfields\nto be executed next.\n\nAn example operation illustrating parallel fields with the same name with\nsub-selections.\n\nContinuing the example above,\n\n```graphql example\n{\n a {\n subfield1\n }\n ...ExampleFragment\n}\n\nfragment ExampleFragment on Query {\n a {\n subfield2\n }\n b\n}\n```\n\nAfter resolving the value for field `\"a\"`, the following multiple selection sets\nare collected and merged together so `\"subfield1\"` and `\"subfield2\"` are\nresolved in the same phase with the same value.\n\nCollectSubfields(objectType, fields, variableValues):\n\n- Let {collectedFieldsMap} be an empty ordered map of ordered sets.\n- For each {field} in {fields}:\n - Let {fieldSelectionSet} be the selection set of {field}.\n - If {fieldSelectionSet} is null or empty, continue to the next field.\n - Let {fieldCollectedFieldsMap} be the result of {CollectFields(objectType,\n fieldSelectionSet, variableValues)}.\n - For each {responseName} and {subfields} in {fieldCollectedFieldsMap}:\n - Let {fieldsForResponseName} be the _field set_ value in\n {collectedFieldsMap} for the key {responseName}; otherwise create the\n entry with an empty ordered set.\n - Add each fields from {subfields} to {fieldsForResponseName}.\n- Return {collectedFieldsMap}.\n\nNote: All the {fields} passed to {CollectSubfields()} share the same _response\nname_.\n\n### Executing Collected Fields\n\nTo execute a _collected fields map_, the object type being evaluated and the\nruntime value need to be known, as well as the runtime values for any variables.\n\nExecution will recursively resolve and complete the value of every entry in the\ncollected fields map, producing an entry in the result map with the same\n_response name_ key.\n\nExecuteCollectedFields(collectedFieldsMap, objectType, objectValue,\nvariableValues):\n\n- Initialize {resultMap} to an empty ordered map.\n- For each {responseName} and {fields} in {collectedFieldsMap}:\n - Let {fieldName} be the name of the first entry in {fields}. Note: This value\n is unaffected if an alias is used.\n - Let {fieldType} be the return type defined for the field {fieldName} of\n {objectType}.\n - If {fieldType} is defined:\n - Let {responseValue} be {ExecuteField(objectType, objectValue, fieldType,\n fields, variableValues)}.\n - Set {responseValue} as the value for {responseName} in {resultMap}.\n- Return {resultMap}.\n\nNote: {resultMap} is ordered by which fields appear first in the operation. This\nis explained in greater detail in the [Field Collection](#sec-Field-Collection)\nsection.\n\n**Errors and Non-Null Types**\n\n\n \n\n\nIf during {ExecuteCollectedFields()} a _response position_ with a non-null type\nraises an _execution error_ then that error must propagate to the parent\nresponse position (the entire selection set in the case of a field, or the\nentire list in the case of a list position), either resolving to {null} if\nallowed or being further propagated to a parent response position.\n\nIf this occurs, any sibling response positions which have not yet executed or\nhave not yet yielded a value may be cancelled to avoid unnecessary work.\n\nNote: See [Handling Execution Errors](#sec-Handling-Execution-Errors) for more\nabout this behavior.\n\n### Normal and Serial Execution\n\nNormally the executor can execute the entries in a _collected fields map_ in\nwhatever order it chooses (normally in parallel). Because the resolution of\nfields other than top-level mutation fields must always be side effect-free and\nidempotent, the execution order must not affect the result, and hence the\nservice has the freedom to execute the field entries in whatever order it deems\noptimal.\n\nFor example, given the following collected fields map to be executed normally:\n\n```graphql example\n{\n birthday {\n month\n }\n address {\n street\n }\n}\n```\n\nA valid GraphQL executor can resolve the four fields in whatever order it chose\n(however of course `birthday` must be resolved before `month`, and `address`\nbefore `street`).\n\nWhen executing a mutation, the selections in the top most selection set will be\nexecuted in serial order, starting with the first appearing field textually.\n\nWhen executing a collected fields map serially, the executor must consider each\nentry from the collected fields map in the order provided in the collected\nfields map. It must determine the corresponding entry in the result map for each\nitem to completion before it continues on to the next entry in the collected\nfields map:\n\nFor example, given the following mutation operation, the root _selection set_\nmust be executed serially:\n\n```graphql example\nmutation ChangeBirthdayAndAddress($newBirthday: String!, $newAddress: String!) {\n changeBirthday(birthday: $newBirthday) {\n month\n }\n changeAddress(address: $newAddress) {\n street\n }\n}\n```\n\nTherefore the executor must, in serial:\n\n- Run {ExecuteField()} for `changeBirthday`, which during {CompleteValue()} will\n execute the `{ month }` sub-selection set normally.\n- Run {ExecuteField()} for `changeAddress`, which during {CompleteValue()} will\n execute the `{ street }` sub-selection set normally.\n\nAs an illustrative example, let's assume we have a mutation field\n`changeTheNumber` that returns an object containing one field, `theNumber`. If\nwe execute the following _selection set_ serially:\n\n```graphql example\n# Note: This is a selection set, not a full document using the query shorthand.\n{\n first: changeTheNumber(newNumber: 1) {\n theNumber\n }\n second: changeTheNumber(newNumber: 3) {\n theNumber\n }\n third: changeTheNumber(newNumber: 2) {\n theNumber\n }\n}\n```\n\nThe executor will execute the following serially:\n\n- Resolve the `changeTheNumber(newNumber: 1)` field\n- Execute the `{ theNumber }` sub-selection set of `first` normally\n- Resolve the `changeTheNumber(newNumber: 3)` field\n- Execute the `{ theNumber }` sub-selection set of `second` normally\n- Resolve the `changeTheNumber(newNumber: 2)` field\n- Execute the `{ theNumber }` sub-selection set of `third` normally\n\nA correct executor must generate the following result for that _selection set_:\n\n```json example\n{\n \"first\": {\n \"theNumber\": 1\n },\n \"second\": {\n \"theNumber\": 3\n },\n \"third\": {\n \"theNumber\": 2\n }\n}\n```\n\n## Executing Fields\n\nEach entry in a result map is the result of executing a field on an object type\nselected by the name of that field in a _collected fields map_. Field execution\nfirst coerces any provided argument values, then resolves a value for the field,\nand finally completes that value either by recursively executing another\nselection set or coercing a scalar value.\n\nExecuteField(objectType, objectValue, fieldType, fields, variableValues):\n\n- Let {field} be the first entry in {fields}.\n- Let {fieldName} be the field name of {field}.\n- Let {argumentValues} be the result of {CoerceArgumentValues(objectType, field,\n variableValues)}.\n- Let {resolvedValue} be {ResolveFieldValue(objectType, objectValue, fieldName,\n argumentValues)}.\n- Return the result of {CompleteValue(fieldType, fields, resolvedValue,\n variableValues)}.\n\n### Coercing Field Arguments\n\nFields may include arguments which are provided to the underlying runtime in\norder to correctly produce a value. These arguments are defined by the field in\nthe type system to have a specific input type.\n\nAt each argument position in an operation may be a literal {Value}, or a\n{Variable} to be provided at runtime.\n\nCoerceArgumentValues(objectType, field, variableValues):\n\n- Let {coercedValues} be an empty unordered Map.\n- Let {argumentValues} be the argument values provided in {field}.\n- Let {fieldName} be the name of {field}.\n- Let {argumentDefinitions} be the arguments defined by {objectType} for the\n field named {fieldName}.\n- For each {argumentDefinition} in {argumentDefinitions}:\n - Let {argumentName} be the name of {argumentDefinition}.\n - Let {argumentType} be the expected type of {argumentDefinition}.\n - Let {defaultValue} be the default value for {argumentDefinition}.\n - Let {argumentValue} be the value provided in {argumentValues} for the name\n {argumentName}.\n - If {argumentValue} is a {Variable}:\n - Let {variableName} be the name of {argumentValue}.\n - If {variableValues} provides a value for the name {variableName}:\n - Let {hasValue} be {true}.\n - Let {value} be the value provided in {variableValues} for the name\n {variableName}.\n - Otherwise if {argumentValues} provides a value for the name {argumentName}.\n - Let {hasValue} be {true}.\n - Let {value} be {argumentValue}.\n - If {hasValue} is not {true} and {defaultValue} exists (including {null}):\n - Let {coercedDefaultValue} be the result of coercing {defaultValue}\n according to the input coercion rules of {argumentType}.\n - Add an entry to {coercedValues} named {argumentName} with the value\n {coercedDefaultValue}.\n - Otherwise if {argumentType} is a Non-Nullable type, and either {hasValue} is\n not {true} or {value} is {null}, raise an _execution error_.\n - Otherwise if {hasValue} is {true}:\n - If {value} is {null}:\n - Add an entry to {coercedValues} named {argumentName} with the value\n {null}.\n - Otherwise, if {argumentValue} is a {Variable}:\n - Add an entry to {coercedValues} named {argumentName} with the value\n {value}.\n - Otherwise:\n - If {value} cannot be coerced according to the input coercion rules of\n {argumentType}, raise an _execution error_.\n - Let {coercedValue} be the result of coercing {value} according to the\n input coercion rules of {argumentType}.\n - Add an entry to {coercedValues} named {argumentName} with the value\n {coercedValue}.\n- Return {coercedValues}.\n\nAny _request error_ raised as a result of input coercion during\n{CoerceArgumentValues()} should be treated instead as an _execution error_.\n\nNote: Variable values are not coerced because they are expected to be coerced\nbefore executing the operation in {CoerceVariableValues()}, and valid operations\nmust only allow usage of variables of appropriate types.\n\nNote: Implementations are encouraged to optimize the coercion of an argument's\ndefault value by doing so only once and caching the resulting coerced value.\n\n### Value Resolution\n\nWhile nearly all of GraphQL execution can be described generically, ultimately\nthe internal system exposing the GraphQL interface must provide values. This is\nexposed via {ResolveFieldValue}, which produces a value for a given field on a\ntype for a real value.\n\nAs an example, this might accept the {objectType} `Person`, the {field}\n{\"soulMate\"}, and the {objectValue} representing John Lennon. It would be\nexpected to yield the value representing Yoko Ono.\n\nResolveFieldValue(objectType, objectValue, fieldName, argumentValues):\n\n- Let {resolver} be the internal function provided by {objectType} for\n determining the resolved value of a field named {fieldName}.\n- Return the result of calling {resolver}, providing {objectValue} and\n {argumentValues}.\n\nNote: It is common for {resolver} to be asynchronous due to relying on reading\nan underlying database or networked service to produce a value. This\nnecessitates the rest of a GraphQL executor to handle an asynchronous execution\nflow. If the field is of a list type, each value in the collection of values\nreturned by {resolver} may itself be retrieved asynchronously.\n\n### Value Completion\n\nAfter resolving the value for a field, it is completed by ensuring it adheres to\nthe expected return type. If the return type is another Object type, then the\nfield execution process continues recursively by collecting and executing\nsubfields.\n\nCompleteValue(fieldType, fields, result, variableValues):\n\n- If the {fieldType} is a Non-Null type:\n - Let {innerType} be the inner type of {fieldType}.\n - Let {completedResult} be the result of calling {CompleteValue(innerType,\n fields, result, variableValues)}.\n - If {completedResult} is {null}, raise an _execution error_.\n - Return {completedResult}.\n- If {result} is {null} (or another internal value similar to {null} such as\n {undefined}), return {null}.\n- If {fieldType} is a List type:\n - If {result} is not a collection of values, raise an _execution error_.\n - Let {innerType} be the inner type of {fieldType}.\n - Return a list where each list item is the result of calling\n {CompleteValue(innerType, fields, resultItem, variableValues)}, where\n {resultItem} is each item in {result}.\n- If {fieldType} is a Scalar or Enum type:\n - Return the result of {CoerceResult(fieldType, result)}.\n- If {fieldType} is an Object, Interface, or Union type:\n - If {fieldType} is an Object type.\n - Let {objectType} be {fieldType}.\n - Otherwise if {fieldType} is an Interface or Union type.\n - Let {objectType} be {ResolveAbstractType(fieldType, result)}.\n - Let {collectedFieldsMap} be the result of calling\n {CollectSubfields(objectType, fields, variableValues)}.\n - Return the result of evaluating {ExecuteCollectedFields(collectedFieldsMap,\n objectType, result, variableValues)} _normally_ (allowing for\n parallelization).\n\n**Coercing Results**\n\nThe primary purpose of value completion is to ensure that the values returned by\nfield resolvers are valid according to the GraphQL type system and a service's\nschema. This \"dynamic type checking\" allows GraphQL to provide consistent\nguarantees about returned types atop any service's internal runtime.\n\nSee the Scalars\n[Result Coercion and Serialization](#sec-Scalars.Result-Coercion-and-Serialization)\nsub-section for more detailed information about how GraphQL's built-in scalars\ncoerce result values.\n\nCoerceResult(leafType, value):\n\n- Assert: {value} is not {null}.\n- Return the result of calling the internal method provided by the type system\n for determining the \"result coercion\" of {leafType} given the value {value}.\n This internal method must return a valid value for the type and not {null}.\n Otherwise raise an _execution error_.\n\nNote: If a field resolver returns {null} then it is handled within\n{CompleteValue()} before {CoerceResult()} is called. Therefore both the input\nand output of {CoerceResult()} must not be {null}.\n\n**Resolving Abstract Types**\n\nWhen completing a field with an abstract return type, that is an Interface or\nUnion return type, first the abstract type must be resolved to a relevant Object\ntype. This determination is made by the internal system using whatever means\nappropriate.\n\nNote: A common method of determining the Object type for an {objectValue} in\nobject-oriented environments, such as Java or C#, is to use the class name of\nthe {objectValue}.\n\nResolveAbstractType(abstractType, objectValue):\n\n- Return the result of calling the internal method provided by the type system\n for determining the Object type of {abstractType} given the value\n {objectValue}.\n\n### Handling Execution Errors\n\n\n \n\n\nAn _execution error_ is an error raised during field execution, value resolution\nor coercion, at a specific _response position_. While these errors must be\nreported in the response, they are \"handled\" by producing partial {\"data\"} in\nthe _response_.\n\nNote: This is distinct from a _request error_ which results in a _request error\nresult_ with no data.\n\nIf an execution error is raised while resolving a field (either directly or\nnested inside any lists), it is handled as though the _response position_ at\nwhich the error occurred resolved to {null}, and the error must be added to the\n{\"errors\"} list in the _execution result_.\n\nIf the result of resolving a _response position_ is {null} (either due to the\nresult of {ResolveFieldValue()} or because an execution error was raised), and\nthat position is of a `Non-Null` type, then an execution error is raised at that\nposition. The error must be added to the {\"errors\"} list in the _execution\nresult_.\n\nIf a _response position_ resolves to {null} because of an execution error which\nhas already been added to the {\"errors\"} list in the _execution result_, the\n{\"errors\"} list must not be further affected. That is, only one error should be\nadded to the errors list per _response position_.\n\nSince `Non-Null` response positions cannot be {null}, execution errors are\npropagated to be handled by the parent _response position_. If the parent\nresponse position may be {null} then it resolves to {null}, otherwise if it is a\n`Non-Null` type, the execution error is further propagated to its parent\n_response position_.\n\nIf a `List` type wraps a `Non-Null` type, and one of the _response position_\nelements of that list resolves to {null}, then the entire list _response\nposition_ must resolve to {null}. If the `List` type is also wrapped in a\n`Non-Null`, the execution error continues to propagate upwards.\n\nIf every _response position_ from the root of the request to the source of the\nexecution error has a `Non-Null` type, then the {\"data\"} entry in the _execution\nresult_ should be {null}.\n" }, { "path": "spec/Section 7 -- Response.md", "content": "# Response\n\nWhen a GraphQL service receives a _request_, it must return a well-formed\nresponse. The service's response describes the result of executing the requested\noperation if successful, and describes any errors raised during the request.\n\nA response may contain both a partial response as well as a list of errors in\nthe case that any _execution error_ was raised and replaced with {null}.\n\n## Response Format\n\n:: A GraphQL request returns a _response_. A _response_ is either an _execution\nresult_, a _response stream_, or a _request error result_.\n\n### Execution Result\n\n:: A GraphQL request returns an _execution result_ when the GraphQL operation is\na query or mutation and the request included execution. Additionally, for each\nevent in a subscription's _source stream_, the _response stream_ will emit an\n_execution result_.\n\nAn _execution result_ must be a map.\n\nThe _execution result_ must contain an entry with key {\"data\"}. The value of\nthis entry is described in the \"Data\" section.\n\nIf execution raised any errors, the _execution result_ must contain an entry\nwith key {\"errors\"}. The value of this entry must be a non-empty list of\n_execution error_ raised during execution. Each error must be a map as described\nin the \"Errors\" section below. If the request completed without raising any\nerrors, this entry must not be present.\n\nNote: When {\"errors\"} is present in an _execution result_, it may be helpful for\nit to appear first when serialized to make it more apparent that errors are\npresent.\n\nThe _execution result_ may also contain an entry with key `extensions`. The\nvalue of this entry is described in the \"Extensions\" section.\n\n### Response Stream\n\n:: A GraphQL request returns a _response stream_ when the GraphQL operation is a\nsubscription and the request included execution. A response stream must be a\nstream of _execution result_.\n\n### Request Error Result\n\n:: A GraphQL request returns a _request error result_ when one or more _request\nerror_ are raised, causing the request to fail before execution. This request\nwill result in no response data.\n\nNote: A _request error_ may be raised before execution due to missing\ninformation, syntax errors, validation failure, coercion failure, or any other\nreason the implementation may determine should prevent the request from\nproceeding.\n\nA _request error result_ must be a map.\n\nThe _request error result_ map must contain an entry with key {\"errors\"}. The\nvalue of this entry must be a non-empty list of _request error_ raised during\nthe _request_. It must contain at least one _request error_ indicating why no\ndata was able to be returned. Each error must be a map as described in the\n\"Errors\" section below.\n\nNote: It may be helpful for the {\"errors\"} key to appear first when serialized\nto make it more apparent that errors are present.\n\nThe _request error result_ map must not contain an entry with key {\"data\"}.\n\nThe _request error result_ map may also contain an entry with key `extensions`.\nThe value of this entry is described in the \"Extensions\" section.\n\n### Response Position\n\n\n \n\n\n:: A _response position_ is a uniquely identifiable position in the response\ndata produced during execution. It is either a direct entry in the {resultMap}\nof a {ExecuteSelectionSet()}, or it is a position in a (potentially nested) List\nvalue. Each response position is uniquely identifiable via a _response path_.\n\n:: A _response path_ uniquely identifies a _response position_ via a list of\npath segments (response names or list indices) starting at the root of the\nresponse and ending with the associated response position.\n\nThe value for a _response path_ must be a list of path segments. Path segments\nthat represent field _response name_ must be strings, and path segments that\nrepresent list indices must be 0-indexed integers. If a path segment is\nassociated with an aliased field it must use the aliased name, since it\nrepresents a path in the response, not in the request.\n\nWhen a _response path_ is present on an _error result_, it identifies the\n_response position_ which raised the error.\n\nA single field execution may result in multiple response positions. For example,\n\n```graphql example\n{\n hero(episode: $episode) {\n name\n friends {\n name\n }\n }\n}\n```\n\nThe hero's name would be found in the _response position_ identified by the\n_response path_ `[\"hero\", \"name\"]`. The List of the hero's friends would be\nfound at `[\"hero\", \"friends\"]`, the hero's first friend at\n`[\"hero\", \"friends\", 0]` and that friend's name at\n`[\"hero\", \"friends\", 0, \"name\"]`.\n\n### Data\n\nThe {\"data\"} entry in the _execution result_ will be the result of the execution\nof the requested operation. If the operation was a query, this output will be an\nobject of the query root operation type; if the operation was a mutation, this\noutput will be an object of the mutation root operation type.\n\nThe response data is the result of accumulating the resolved result of all\nresponse positions during execution.\n\nIf an error was raised before execution begins, the _response_ must be a\n_request error result_ which will result in no response data.\n\nIf an error was raised during the execution that prevented a valid response, the\n{\"data\"} entry in the response should be `null`.\n\n### Errors\n\nThe {\"errors\"} entry in the _execution result_ or _request error result_ is a\nnon-empty list of errors raised during the _request_, where each error is a map\nof data described by the error result format below.\n\n**Request Errors**\n\n:: A _request error_ is an error raised during a _request_ which results in no\nresponse data. Typically raised before execution begins, a request error may\noccur due to a parse grammar or validation error in the _Document_, an inability\nto determine which operation to execute, or invalid input values for variables.\n\nA request error is typically the fault of the requesting client.\n\nIf a request error is raised, the _response_ must be a _request error result_.\nThe {\"data\"} entry in this map must not be present, the {\"errors\"} entry must\ninclude the error, and request execution should be halted.\n\n**Execution Errors**\n\n\n \n\n\n:: An _execution error_ is an error raised during the execution of a particular\nfield which results in partial response data. This may occur due to failure to\ncoerce the arguments for the field, an internal error during value resolution,\nor failure to coerce the resulting value.\n\nNote: In previous versions of this specification _execution error_ was called\n_field error_.\n\nAn execution error is typically the fault of a GraphQL service.\n\nAn _execution error_ must occur at a specific _response position_, and may occur\nin any response position. The response position of an execution error is\nindicated via a _response path_ in the error response's {\"path\"} entry.\n\nWhen an execution error is raised at a given _response position_, then that\nresponse position must not be present within the _response_ {\"data\"} entry\n(except {null}), and the {\"errors\"} entry must include the error. Nested\nexecution is halted and sibling execution attempts to continue, producing\npartial result (see\n[Handling Execution Errors](#sec-Handling-Execution-Errors)).\n\n**Error Result Format**\n\nEvery error must contain an entry with the key {\"message\"} with a string\ndescription of the error intended for the developer as a guide to understand and\ncorrect the error.\n\nIf an error can be associated to a particular point in the requested GraphQL\ndocument, it should contain an entry with the key {\"locations\"} with a list of\nlocations, where each location is a map with the keys {\"line\"} and {\"column\"},\nboth positive numbers starting from `1` which describe the beginning of an\nassociated syntax element.\n\nIf an error can be associated to a particular field in the GraphQL result, it\nmust contain an entry with the key {\"path\"} with a _response path_ which\ndescribes the _response position_ which raised the error. This allows clients to\nidentify whether a {null} resolved result is a true value or the result of an\n_execution error_.\n\nFor example, if fetching one of the friends' names fails in the following\noperation:\n\n```graphql example\n{\n hero(episode: $episode) {\n name\n heroFriends: friends {\n id\n name\n }\n }\n}\n```\n\nThe response might look like:\n\n```json example\n{\n \"errors\": [\n {\n \"message\": \"Name for character with ID 1002 could not be fetched.\",\n \"locations\": [{ \"line\": 6, \"column\": 7 }],\n \"path\": [\"hero\", \"heroFriends\", 1, \"name\"]\n }\n ],\n \"data\": {\n \"hero\": {\n \"name\": \"R2-D2\",\n \"heroFriends\": [\n {\n \"id\": \"1000\",\n \"name\": \"Luke Skywalker\"\n },\n {\n \"id\": \"1002\",\n \"name\": null\n },\n {\n \"id\": \"1003\",\n \"name\": \"Leia Organa\"\n }\n ]\n }\n }\n}\n```\n\nIf the field which experienced an error was declared as `Non-Null`, the `null`\nresult will bubble up to the next nullable field. In that case, the `path` for\nthe error should include the full path to the result field where the error was\nraised, even if that field is not present in the response.\n\nFor example, if the `name` field from above had declared a `Non-Null` return\ntype in the schema, the result would look different but the error reported would\nbe the same:\n\n```json example\n{\n \"errors\": [\n {\n \"message\": \"Name for character with ID 1002 could not be fetched.\",\n \"locations\": [{ \"line\": 6, \"column\": 7 }],\n \"path\": [\"hero\", \"heroFriends\", 1, \"name\"]\n }\n ],\n \"data\": {\n \"hero\": {\n \"name\": \"R2-D2\",\n \"heroFriends\": [\n {\n \"id\": \"1000\",\n \"name\": \"Luke Skywalker\"\n },\n null,\n {\n \"id\": \"1003\",\n \"name\": \"Leia Organa\"\n }\n ]\n }\n }\n}\n```\n\nGraphQL services may provide an additional entry to errors with key\n`extensions`. This entry, if set, must have a map as its value. This entry is\nreserved for implementers to add additional information to errors however they\nsee fit, and there are no additional restrictions on its contents.\n\n```json example\n{\n \"errors\": [\n {\n \"message\": \"Name for character with ID 1002 could not be fetched.\",\n \"locations\": [{ \"line\": 6, \"column\": 7 }],\n \"path\": [\"hero\", \"heroFriends\", 1, \"name\"],\n \"extensions\": {\n \"code\": \"CAN_NOT_FETCH_BY_ID\",\n \"timestamp\": \"Fri Feb 9 14:33:09 UTC 2018\"\n }\n }\n ]\n}\n```\n\nGraphQL services should not provide any additional entries to the error format\nsince they could conflict with additional entries that may be added in future\nversions of this specification.\n\nNote: Previous versions of this spec did not describe the `extensions` entry for\nerror formatting. While non-specified entries are not violations, they are still\ndiscouraged.\n\n```json counter-example\n{\n \"errors\": [\n {\n \"message\": \"Name for character with ID 1002 could not be fetched.\",\n \"locations\": [{ \"line\": 6, \"column\": 7 }],\n \"path\": [\"hero\", \"heroFriends\", 1, \"name\"],\n \"code\": \"CAN_NOT_FETCH_BY_ID\",\n \"timestamp\": \"Fri Feb 9 14:33:09 UTC 2018\"\n }\n ]\n}\n```\n\n### Extensions\n\nThe {\"extensions\"} entry in an _execution result_ or _request error result_, if\nset, must have a map as its value. This entry is reserved for implementers to\nextend the protocol however they see fit, and hence there are no additional\nrestrictions on its contents.\n\n### Additional Entries\n\nTo ensure future changes to the protocol do not break existing services and\nclients, the _execution result_ and _request error result_ maps must not contain\nany entries other than those described above. Clients must ignore any entries\nother than those described above.\n\n## Serialization Format\n\nGraphQL does not require a specific serialization format. However, clients\nshould use a serialization format that supports the major primitives in the\nGraphQL response. In particular, the serialization format must at least support\nrepresentations of the following four primitives:\n\n- Map\n- List\n- String\n- Null\n\nA serialization format should also support the following primitives, each\nrepresenting one of the common GraphQL scalar types, however a string or simpler\nprimitive may be used as a substitute if any are not directly supported:\n\n- Boolean\n- Int\n- Float\n- Enum Value\n\nThis is not meant to be an exhaustive list of what a serialization format may\nencode. For example custom scalars representing a Date, Time, URI, or number\nwith a different precision may be represented in whichever relevant format a\ngiven serialization format may support.\n\n### JSON Serialization\n\nJSON is the most common serialization format for GraphQL. Though as mentioned\nabove, GraphQL does not require a specific serialization format.\n\nWhen using JSON as a serialization of GraphQL responses, the following JSON\nvalues should be used to encode the related GraphQL values:\n\n| GraphQL Value | JSON Value |\n| ------------- | ----------------- |\n| Map | Object |\n| List | Array |\n| Null | {null} |\n| String | String |\n| Boolean | {true} or {false} |\n| Int | Number |\n| Float | Number |\n| Enum Value | String |\n\nNote: For consistency and ease of notation, examples of responses are given in\nJSON format throughout this document.\n\n### Serialized Map Ordering\n\nSince the result of evaluating a _selection set_ is ordered, the serialized Map\nof results should preserve this order by writing the map entries in the same\norder as those fields were requested as defined by selection set execution.\nProducing a serialized response where fields are represented in the same order\nin which they appear in the request improves human readability during debugging\nand enables more efficient parsing of responses if the order of properties can\nbe anticipated.\n\nSerialization formats which represent an ordered map should preserve the order\nof requested fields as defined by {CollectFields()} in the Execution section.\nSerialization formats which only represent unordered maps but where order is\nstill implicit in the serialization's textual order (such as JSON) should\npreserve the order of requested fields textually.\n\nFor example, if the request was `{ name, age }`, a GraphQL service responding in\nJSON should respond with `{ \"name\": \"Mark\", \"age\": 30 }` and should not respond\nwith `{ \"age\": 30, \"name\": \"Mark\" }`.\n\nWhile JSON Objects are specified as an\n[unordered collection of key-value pairs](https://tools.ietf.org/html/rfc7159#section-4)\nthe pairs are represented in an ordered manner. In other words, while the JSON\nstrings `{ \"name\": \"Mark\", \"age\": 30 }` and `{ \"age\": 30, \"name\": \"Mark\" }`\nencode the same value, they also have observably different property orderings.\n\nNote: This does not violate the JSON spec, as clients may still interpret\nobjects in the response as unordered Maps and arrive at a valid value.\n" }, { "path": "spec/metadata.json", "content": "{\n \"biblio\": {\n \"https://www.unicode.org/glossary\": {\n \"byte-order-mark\": \"#byte_order_mark\",\n \"leading-surrogate\": \"#leading_surrogate\",\n \"trailing-surrogate\": \"#trailing_surrogate\",\n \"supplementary-character\": \"#supplementary_character\",\n \"supplementary-code-point\": \"#supplementary_code_point\",\n \"surrogate-code-point\": \"#surrogate_code_point\",\n \"surrogate-pair\": \"#surrogate_pair\",\n \"unicode-scalar-value\": \"#unicode_scalar_value\",\n \"utf-16\": \"#UTF_16\"\n }\n }\n}\n" } ]