CINXE.COM

<!DOCTYPE html>  <html> <head><meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"><title>GraphQL</title> <style>/** * prism.js default theme for JavaScript, CSS and HTML * Based on dabblet (http://dabblet.com) * @author Lea Verou */ code[class*="language-"], pre[class*="language-"] { color: black; background: none; text-shadow: 0 1px white; font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace; font-size: 1em; text-align: left; white-space: pre; word-spacing: normal; word-break: normal; word-wrap: normal; line-height: 1.5; -moz-tab-size: 4; -o-tab-size: 4; tab-size: 4; -webkit-hyphens: none; -moz-hyphens: none; -ms-hyphens: none; hyphens: none; } pre[class*="language-"]::-moz-selection, pre[class*="language-"] ::-moz-selection, code[class*="language-"]::-moz-selection, code[class*="language-"] ::-moz-selection { text-shadow: none; background: #b3d4fc; } pre[class*="language-"]::selection, pre[class*="language-"] ::selection, code[class*="language-"]::selection, code[class*="language-"] ::selection { text-shadow: none; background: #b3d4fc; } @media print { code[class*="language-"], pre[class*="language-"] { text-shadow: none; } } /* Code blocks */ pre[class*="language-"] { padding: 1em; margin: .5em 0; overflow: auto; } :not(pre) > code[class*="language-"], pre[class*="language-"] { background: #f5f2f0; } /* Inline code */ :not(pre) > code[class*="language-"] { padding: .1em; border-radius: .3em; white-space: normal; } .token.comment, .token.prolog, .token.doctype, .token.cdata { color: slategray; } .token.punctuation { color: #999; } .token.namespace { opacity: .7; } .token.property, .token.tag, .token.boolean, .token.number, .token.constant, .token.symbol, .token.deleted { color: #905; } .token.selector, .token.attr-name, .token.string, .token.char, .token.builtin, .token.inserted { color: #690; } .token.operator, .token.entity, .token.url, .language-css .token.string, .style .token.string { color: #9a6e3a; /* This background color was intended by the author of this theme. */ background: hsla(0, 0%, 100%, .5); } .token.atrule, .token.attr-value, .token.keyword { color: #07a; } .token.function, .token.class-name { color: #DD4A68; } .token.regex, .token.important, .token.variable { color: #e90; } .token.important, .token.bold { font-weight: bold; } .token.italic { font-style: italic; } .token.entity { cursor: help; }</style> <style>:root{color:#333;font-family:Cambria,"Palatino Linotype",Palatino,"Liberation Serif",serif;font-size:15px;line-height:1.5;--mono-font-size: 13px;--indent: 1rem;--list-indent: 1.5rem;--dfn-indent: 0rem}@media (min-width: 720px){:root{font-size:17px;--mono-font-size: 15px;--indent: 2rem;--list-indent: 2rem;--dfn-indent: 2rem}}body{margin:3rem 0 3rem}article{margin:0 1rem}@media (min-width: 720px){body{margin:6rem auto 3rem;max-width:800px;padding-left:75px;padding-right:clamp(0px,calc((100vw - 800px) * .25),75px)}}.source-link{display:none}@media screen and (min-width: 720px){.source-link{display:block;position:absolute;width:18px;fill:#ccc;opacity:.3}.source-link:hover{opacity:1}}.outdated-selection-link,.selection-link{position:absolute;display:block;color:#fff;--selection-background-color: #cacee0;background:var(--selection-background-color);border-radius:4px;font-size:36px;height:23px;line-height:48px;text-align:center;text-decoration:none;width:25px;user-select:none;-moz-user-select:none;-webkit-user-select:none;-ms-user-select:none}.outdated-selection-link:hover,.selection-link:hover{text-decoration:none}.outdated-selection-link:before,.selection-link:before{border:5px solid transparent;content:"";height:0;margin-top:-5px;margin-right:-5px;position:absolute;right:1px;top:50%;width:0}@media (max-width: 719px){.outdated-selection-link:before,.selection-link:before{border-bottom-color:var(--selection-background-color);border-top:0;right:50%;top:1px}}@media (min-width: 720px){.outdated-selection-link:before,.selection-link:before{border-left-color:var(--selection-background-color);border-right:0;right:1px;top:50%}}.selection-link:hover{--selection-background-color: #3b5998}.outdated-selection-link{--selection-background-color: #f0babe;font-size:21px;font-weight:800;line-height:27px}.outdated-selection-link:hover:after{content:"This selection content has changed since this link was created.";font:9pt/11pt Cambria,"Palatino Linotype",Palatino,"Liberation Serif",serif;position:absolute;display:block;white-space:nowrap;padding:2px 5px 1px;top:-20px;background:black;color:#fff}a{color:#3b5998;text-decoration:none}a:hover{text-decoration:underline}img{max-width:100%}dl{margin:1rem 0 1rem var(--dfn-indent)}dd{margin:.25em 0 .5em var(--indent)}dd+dd{margin-top:1rem}dfn,.spec-ref{font-style:italic}dfn>a,.spec-ref>a{color:inherit}h1,h2,h3,h4,h5,h6{font-weight:bold;margin:3em 0 1em;position:relative}@media (min-width: 720px){header>h1{margin:6em 0 3em}}h1{font-size:1.5em;margin-top:5em}h2,h3{font-size:1.25em}h4,h5,h6{font-size:1em}section{padding-top:1rem;margin-top:-1rem}section.subsec>h6{margin-top:2em}section.subsec>h6>a{color:#333}section .spec-secid{margin-right:1ex}@media (min-width: 720px){section .spec-secid{position:absolute;right:100%;text-align:right;white-space:nowrap}}footer{font-size:75%;opacity:.5;text-align:center;margin-top:12rem}.spec-toc{margin:1rem 0 3rem}.spec-toc .title{content:"Contents";display:block;font-weight:bold;margin:5em 0 1em}.spec-toc .spec-secid{margin-right:1ex}.spec-toc ol{list-style:none;padding-left:0;margin-top:0;margin-bottom:0}.spec-toc ol ol{list-style:none;padding-left:2ex;margin-bottom:.25em}.spec-toc li{position:relative;padding:5px 0 0 30px;margin:-5px 0 0 -30px}.spec-toc a{color:#333}.spec-toc a:hover{text-decoration:none}.spec-toc a .spec-secid{color:#3b5998}.spec-toc a:hover .spec-secid{text-decoration:underline}.spec-toc .toggle{display:none}.spec-toc .toggle+label{cursor:pointer;left:6px;opacity:1;padding:5px 6px 5px 7px;position:absolute;top:6px;transform:rotate(0deg);transition:all .18s ease-in-out}.spec-toc .toggle+label:after{border-color:transparent transparent transparent #bbc;border-style:solid;border-width:6px 0 6px 7px;content:" ";display:block;height:0;width:0}@media (pointer: fine){.spec-toc .toggle+label{left:10px;padding:3px 5px 3px 6px;top:8px}}.spec-toc .toggle:checked+label{transform:rotate(90deg)}@media (hover: hover){.spec-toc li:not(:hover)>.toggle:checked+label{opacity:0}}.spec-toc .toggle:not(:checked)~ol{max-height:0;overflow:hidden;margin:0}.spec-sidebar-toggle{display:none}.spec-sidebar-toggle+label>.spec-sidebar-button{position:fixed;right:0;top:0;padding:10px 15px;font-size:30px;color:#000000b3;z-index:2;cursor:pointer;user-select:none;-moz-user-select:none;-webkit-user-select:none;-ms-user-select:none}.spec-sidebar-toggle:checked+label:after{content:"";position:fixed;top:0;left:0;width:100vw;height:100vh;z-index:0}.spec-sidebar{display:none;position:fixed;right:0;top:0;width:min(320px,calc(100vw - 48px));font-size:14px;line-height:1.75;overflow-y:scroll;height:100%;padding:0 0 5rem 30px;box-sizing:border-box;background:#f0f0f0;box-shadow:inset 1px 0 rgba(0,0,0,.05),-4px 0 8px -2px rgba(0,0,0,.04);overscroll-behavior:contain}.spec-sidebar{user-select:none;-moz-user-select:none;-webkit-user-select:none;-ms-user-select:none}.spec-sidebar-toggle:checked~.spec-sidebar{display:block}.spec-sidebar .viewing>a:after{color:#8b9;content:"\2022";margin-left:1ex}@media (min-width: 1220px){.spec-sidebar-toggle+label{display:none}.spec-sidebar{display:block;box-shadow:inset 1px 0 rgba(0,0,0,.05),inset 4px 0 8px -2px rgba(0,0,0,.08)!important}body{padding-right:345px}}.spec-note{background:#FEFEF3;border-left:solid 4px #F4E925;margin:1rem -1rem;min-width:70vw;padding:8px 1rem 12px calc(1rem - 4px);width:-moz-fit-content;width:-webkit-fit-content;width:fit-content}@media (min-width: 720px){.spec-note{min-width:416px}}.spec-note>a:first-child{color:#6c6613;display:block;font:italic 11pt/18pt Cambria,"Palatino Linotype",Palatino,"Liberation Serif",serif;opacity:.6;user-select:none}.spec-todo{color:#666;margin:1em 0 1em 5em;min-height:1em}.spec-todo::before{content:"todo";display:block;float:left;margin-left:-5em;text-transform:uppercase}.spec-index ol{list-style-type:none;margin:0 0 0 var(--indent);padding:0;column-width:210px;column-gap:var(--indent)}.spec-index ol li{width:min-content;white-space:nowrap}pre,code{font-family:Consolas,Monaco,"Andale Mono","Ubuntu Mono",monospace;font-size:var(--mono-font-size);font-weight:inherit}code{background:rgba(0,0,0,.03);margin:-2px -1px;padding:3px 3px;white-space:pre-wrap}pre>code{background:none;font-weight:inherit;margin:0;padding:0;white-space:pre}pre{background:#FAFAFA;border-left:solid 4px #E9E9E9;margin:1rem -1rem;min-width:70vw;padding:12px 1rem 12px calc(1rem - 4px);width:-moz-fit-content;width:-webkit-fit-content;width:fit-content;max-width:calc(100vw - 2rem);overflow-y:scroll}@media (min-width: 720px){pre{min-width:40ch}}.spec-example{background:#FAFAFF;border-left:solid 4px #BBBBFF;padding-top:8px}.spec-counter-example{background:#FFFAFA;border-left:solid 4px #FFBBBB;padding-top:8px}.spec-example>a,.spec-counter-example>a{display:block;font:italic 11pt/18pt Cambria,"Palatino Linotype",Palatino,"Liberation Serif",serif;opacity:.6;user-select:none}.spec-counter-example>a{color:#98593b}table{border-collapse:collapse}th{background-color:#f9f9f9}td,th{border:1px solid #D0D0D0;padding:.4em;vertical-align:baseline}ol,ul{padding-left:var(--list-indent)}li>ol,li>ul{margin-top:.25em;margin-bottom:.5em}li+li{margin-top:.25em}li.task{list-style-type:none;position:relative}li.task>input:first-child{margin-left:0;position:absolute;transform:translateX(calc(-100% - 1ch))}ins{background-color:#00c81e14;text-decoration:none}del{background-color:#c8000014}.spec-added,.spec-removed{border-left:4px solid;margin-left:-18px;padding-left:14px}.spec-added{border-color:#396}.spec-removed{border-color:#933;text-decoration:line-through}.spec-keyword{font-weight:bold}.spec-string{font-family:Consolas,Monaco,monospace;font-size:85%;white-space:pre}var{font-style:italic}*[data-name]{transition:.15s background ease-out;border-radius:2px;padding:0 3px;margin:0 -3px}.spec-semantic,.spec-algo{margin:1rem 0 1rem var(--dfn-indent)}.spec-semantic>.spec-nt::after,.spec-algo>.spec-call:first-child::after{content:":";font-style:normal;font-weight:bold;margin-left:1ex}.spec-semantic ol,.spec-semantic ol ol ol ol,.spec-algo ol,.spec-algo ol ol ol ol{list-style-type:decimal}.spec-semantic ol ol,.spec-semantic ol ol ol ol ol,.spec-algo ol ol,.spec-algo ol ol ol ol ol{list-style-type:lower-alpha}.spec-semantic ol ol ol,.spec-semantic ol ol ol ol ol ol,.spec-algo ol ol ol,.spec-algo ol ol ol ol ol ol{list-style-type:lower-roman}.spec-call>a{color:inherit}.spec-production{margin:1rem 0 1rem var(--dfn-indent)}.spec-production>.spec-nt::after{content:":";font-style:normal;font-weight:bold;margin:0 1ex}.spec-semantic.d2>.spec-nt::after,.spec-production.d2>.spec-nt::after{content:"::"}.spec-semantic.d3>.spec-nt::after,.spec-production.d3>.spec-nt::after{content:":::"}.spec-production>.spec-rhs{line-height:1.1;margin:.25em 0 .5em calc(2 * var(--indent));text-indent:calc(-1 * var(--indent))}.spec-semantic>.spec-rhs{display:inline-block;text-indent:calc(-1 * var(--indent));margin-left:calc(1ex + var(--indent))}.spec-rhs>*{text-indent:0}.spec-oneof{display:inline}.spec-oneof::before{content:"one of";font-style:normal;font-weight:bold}.spec-oneof-grid{max-width:calc(100vw - 2rem);overflow:scroll;margin:-1ex -1rem;padding:1ex 1rem}.spec-oneof-grid>table{margin-left:var(--indent)}.spec-oneof .spec-rhs{border:none;margin:0;padding:0 0 0 1rem;vertical-align:baseline;white-space:pre}.spec-oneof .spec-rhs:first-child{padding:0}.spec-rhs .spec-constrained:not(:first-child),.spec-rhs .spec-quantified:not(:first-child),.spec-rhs .spec-nt:not(:first-child),.spec-rhs .spec-t:not(:first-child),.spec-rhs .spec-rx:not(:first-child),.spec-rhs .spec-prose:not(:first-child),.spec-rhs .spec-empty:not(:first-child),.spec-rhs .spec-lookahead:not(:first-child){margin-left:1ex;display:inline-block}.spec-condition{font-size:85%}.spec-condition::before{content:"[if "}.spec-condition.not::before{content:"[if not "}.spec-condition::after{content:"]"}.spec-empty,.spec-prose{color:#666}.spec-nt{font-style:italic}.spec-nt>a{color:inherit}.spec-quantifiers,.spec-params{font-size:65%;font-style:normal;vertical-align:sub}.spec-quantifier.list{color:#3348d3}.spec-quantifier.optional{color:#83238e}.spec-params,.spec-condition{color:#1c7758}.spec-params::before{content:"["}.spec-params::after{content:"]"}.spec-quantifier:not(:last-child)::after,.spec-param:not(:last-child)::after{color:#666;content:", "}.spec-param.conditional::before{content:"?"}.spec-param.negated::before{content:"!"}.spec-t,.spec-rx{color:#333;font-family:monospace;font-weight:bold}.spec-butnot::before{color:#666;content:"but not";font-family:Cambria,"Palatino Linotype",Palatino,"Liberation Serif",serif;font-weight:normal;margin-right:1ex}.spec-butnot>*:not(:first-child)::before{color:#666;content:"or";font-family:Cambria,"Palatino Linotype",Palatino,"Liberation Serif",serif;font-weight:normal;margin-right:1ex}.spec-rhs .spec-oneof::before,.spec-rhs .spec-butnot::before{margin-left:1ex}.spec-lookahead>*{margin:0!important}.spec-lookahead>*:not(:first-child)::before{color:#666;content:", ";font-family:Cambria,"Palatino Linotype",Palatino,"Liberation Serif",serif;font-style:normal;font-weight:normal}.spec-lookahead::before{color:#666;content:"[lookahead = ";font-family:Cambria,"Palatino Linotype",Palatino,"Liberation Serif",serif;font-style:normal;font-weight:normal}.spec-lookahead.not::before{content:"[lookahead \2260 "}.spec-lookahead.set::before{content:"[lookahead \2208 {";margin-right:0}.spec-lookahead.set.not::before{content:"[lookahead \2209 {"}.spec-lookahead.ntset::before{content:"[lookahead \2208 ";margin-right:0}.spec-lookahead.ntset.not::before{content:"[lookahead \2209 "}.spec-lookahead::after{color:#666;content:"]"}.spec-lookahead.set::after{content:"}]"}.token.atrule,.token.attr-value,.token.keyword,.token.property,.token.selector,.token.attr-name,.token.builtin,.token.entity,.token.url,.token.inserted{color:#1b1994b0;background:none}.token.tag,.token.boolean,.token.number,.token.string,.token.char,.token.constant,.token.symbol,.token.regex,.token.important,.token.variable,.token.function,.token.class-name,.token.deleted{color:#a20764bd}.token.comment,.token.prolog,.token.doctype,.token.cdata,.token.description{color:inherit;opacity:.3}.token.punctuation{color:inherit;opacity:.5}.token.operator,.token.namespace{color:inherit;opacity:.7}</style> <script>(function(){var r,a=[];document.addEventListener("readystatechange",function(){document.readyState==="interactive"&&u()});function u(){var n=document.querySelector('label[for="spec-sidebar-toggle"]');n.addEventListener("scroll",o),n.addEventListener("touchmove",o);function o(d){d.preventDefault()}for(var t=document.getElementsByTagName("section"),e=0;e<t.length;e++)t[e].getAttribute("secid")&&a.push(t[e]);var i=window.scrollY,c=!1;window.addEventListener("scroll",function(d){i=window.scrollY,c||(c=!0,window.requestAnimationFrame(function(){s(i),c=!1}))})}function s(n){for(var o=n+document.documentElement.clientHeight/4,t,e=a.length-1;e>=0;e--)if(a[e].offsetTop<o){t=a[e];break}var i=t&&t.getAttribute("secid");i!==r&&(r&&l(r,!1),i&&l(i,!0),r=i)}function l(n,o){document.getElementById("_sidebar_"+n).className=o?"viewing":"";for(var t=n.split(".");t.length;){var e=document.getElementById("_toggle_"+t.join("."));e&&(e.checked=o),t.pop()}}s(window.scrollY);})();</script> <script>(function(){var n=document.getElementsByTagName("style")[0].sheet,e;function u(){e&&(n.deleteRule(e),e=void 0)}function d(t){u(),e=n.insertRule('*[data-name="'+t+'"] { background: rgba(230,215,0,0.12); }',n.cssRules.length)}document.documentElement.addEventListener("mouseover",function(t){var a=t.target.attributes["data-name"];a&&d(a.value)});document.documentElement.addEventListener("mouseout",u);})();</script> <script>(function(){var R="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_",o,p,r,g;document.addEventListener("selectionchange",E);window.addEventListener("resize",C);window.addEventListener("hashchange",x);window.addEventListener("load",x);function S(n){y(new URL(n.target.href))}function x(){y(window.location)}function y(n){var e=n.hash.match(/^#sel-([A-Za-z0-9-_]+)$/);if(!!e){g=e[1],r=k(g);var t=r.getBoundingClientRect(),d=Math.max(20,Math.floor((window.innerHeight-t.height)*.4));window.scrollTo(0,window.scrollY+t.y-d);var c=document.getSelection();c.empty(),c.addRange(r),C()}}function E(n){var e=document.getSelection();if(e.isCollapsed)o&&(o.parentNode.removeChild(o),o=null);else{var t=e.getRangeAt(0);(!r||t.compareBoundaryPoints(Range.START_TO_START,r)!==0||t.compareBoundaryPoints(Range.END_TO_END,r)!==0)&&(r=t,g=B(r),C())}}function C(){if(!!r){p||(p=document.getElementsByTagName("article")[0]),o||(o=document.createElement("a"),document.body.appendChild(o)),o.href="#sel-"+g,o.onclick=S,o.className=r.isOutdated?"outdated-selection-link":"selection-link",o.innerText=r.isOutdated?"!":"\u201F";var n=window.innerWidth<720,e=r.getBoundingClientRect();if(n)o.style.left=Math.floor(e.x+e.width/2+window.scrollX-13)+"px",o.style.top=Math.floor(e.bottom+window.scrollY+10)+"px";else{var t=p.getBoundingClientRect().x;o.style.left=Math.floor(t+window.scrollX-37)+"px",o.style.top=Math.floor(e.y+window.scrollY-3)+"px"}}}function B(n){var e="",t=N(n.startContainer),d=N(n.endContainer),c=M(t,d);return l(c),l(t.slice(c.length).concat(n.startOffset)),l(d.slice(c.length).concat(n.endOffset)),i(L(n.toString())),e;function i(a){do e+=R[a&31|(a>31?32:0)],a>>=5;while(a>0)}function l(a){i(a.length);for(var h=0;h<a.length;h++)i(a[h])}}function k(n){for(var e=new Array(64),t=0;t<64;t++)e[R.charCodeAt(t)]=t;var d=0,c=m(),i=m(),l=m(),a=w(),h=i.pop(),P=O(c.concat(i)),T=l.pop(),A=O(c.concat(l)),u=document.createRange();return u.setStart(P,h),u.setEnd(A,T),u.isOutdated=a!==void 0&&a!==L(u.toString()),u;function w(){for(var s=0,v=0;d<n.length;){var f=e[n.charCodeAt(d++)];if(s|=(f&31)<<v,v+=5,f<32)return s}}function m(){var s=w();if(s!=null){for(var v=new Array(s),f=0;f<s;f++)v[f]=w();return v}}}function N(n){for(var e=[];n!=document.body;){var t=n.parentNode;e.push(Array.prototype.indexOf.call(t.childNodes,n)),n=t}return e.reverse()}function O(n){for(var e=document.body,t=0;t<n.length&&e;t++)e=e.childNodes[n[t]];return e}function M(n,e){for(var t=0;t<n.length&&t<e.length&&n[t]===e[t];)t++;return n.slice(0,t)}function L(n){for(var e=2166136261,t=0;t<n.length;++t)e^=n.charCodeAt(t),e+=(e<<1)+(e<<4)+(e<<7)+(e<<8)+(e<<24);return(e>>15^e)&32767}})();</script> <script>(function(){var a,i,t;document.addEventListener("pointerover",c);document.addEventListener("pointerleave",u);window.addEventListener("resize",d);var s={OL:1,UL:1};function c(r){var e=r.target;if(e.nodeType===Node.ELEMENT_NODE){for(;e&&!e.getAttribute("data-source");){if(s[e.nodeName])return;e=e.parentElement}e&&e!==a&&(a=e,d())}}function d(){if(!!a){i||(i=document.getElementsByTagName("article")[0]),t||(t=document.createElement("a"),t.className="source-link",t.target="_blank",t.innerHTML='<svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg>',document.body.appendChild(t)),t.href=i.getAttribute("data-source-base")+a.getAttribute("data-source");var r=v(a),e=document.createRange();r.nodeType===Node.TEXT_NODE?e.setStart(r,0):e.selectNode(r);var n=e.getBoundingClientRect();e.detach();var o=n.y+n.height/2-9,l=i.getBoundingClientRect().x-95;t.style.left=Math.floor(window.scrollX+l)+"px",t.style.top=Math.floor(window.scrollY+o)+"px"}}function v(r){e:for(;r;){for(var e=r.childNodes,n=0;e&&n<e.length;n++){var o=e[n];if(o.nodeType===Node.ELEMENT_NODE||o.nodeType===Node.TEXT_NODE&&!/^\s*$/.test(o.data)){r=o;continue e}}return r}}function u(){t&&(t.parentNode.removeChild(t),t=null)}})();</script> </head> <body><article data-source-base="https://github.com/graphql/graphql-spec/blame/October2021/"> <header> <h1>GraphQL</h1> <section id="intro"> October 2021 Edition <section id="sec-Introduction" class="subsec"> <h6 data-source="spec/GraphQL.md#L5"><a href="#sec-Introduction" title="link to this subsection">Introduction</a></h6> This is the specification for GraphQL, a query language and execution engine originally created at Facebook in 2012 for describing the capabilities and requirements of data models for client-server applications. The development of this open standard started in 2015. This specification was licensed under OWFa 1.0 in 2017. The <a href="https://graphql.org/foundation/">GraphQL Foundation</a> was formed in 2019 as a neutral focal point for organizations who support the GraphQL ecosystem, and the <a href="https://graphql.org/community/">GraphQL Specification Project</a> was established also in 2019 as the Joint Development Foundation Projects, LLC, GraphQL Series. If your organization benefits from GraphQL, please consider <a href="https://graphql.org/foundation/join/#graphql-foundation">becoming a member</a> and helping us to sustain the activities that support the health of our neutral ecosystem. The GraphQL Specification Project has evolved and may continue to evolve in future editions of this specification. Previous editions of the GraphQL specification can be found at permalinks that match their <a href="https://github.com/graphql/graphql-spec/releases">release tag</a>. The latest working draft release can be found at <a href="https://spec.graphql.org/draft">https://spec.graphql.org/draft</a>. </section> <section id="sec-Copyright-notice" class="subsec"> <h6 data-source="spec/GraphQL.md#L30"><a href="#sec-Copyright-notice" title="link to this subsection">Copyright notice</a></h6> Copyright © 2015-2018, Facebook, Inc. Copyright © 2019-present, GraphQL contributors THESE MATERIALS ARE PROVIDED “AS IS.” The parties expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL THE PARTIES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. </section> <section id="sec-Licensing" class="subsec"> <h6 data-source="spec/GraphQL.md#L49"><a href="#sec-Licensing" title="link to this subsection">Licensing</a></h6> The GraphQL Specification Project is made available by the <a href="https://www.jointdevelopment.org/">Joint Development Foundation</a>. The current <a href="https://github.com/graphql/graphql-wg">Working Group</a> charter, which includes the IP policy governing all working group deliverables (including specifications, source code, and datasets) may be found at <a href="https://technical-charter.graphql.org">https://technical-charter.graphql.org</a>. Currently, the licenses governing GraphQL Specification Project deliverables are: <table> <thead> <tr data-source="spec/GraphQL.md#L60"> <th>Deliverable</th> <th>License</th> </tr> </thead> <tbody> <tr data-source="spec/GraphQL.md#L62"> <td>Specifications</td> <td><a href="http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0">Open Web Foundation Agreement 1.0 Mode</a> (Patent and Copyright)</td> </tr> <tr data-source="spec/GraphQL.md#L63"> <td>Source code</td> <td><a href="https://opensource.org/licenses/MIT">MIT License</a></td> </tr> <tr data-source="spec/GraphQL.md#L64"> <td>Data sets</td> <td><a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0 1.0</a></td> </tr> </tbody> </table> </section> <section id="sec-Conformance" class="subsec"> <h6 data-source="spec/GraphQL.md#L67"><a href="#sec-Conformance" title="link to this subsection">Conformance</a></h6> A conforming implementation of GraphQL must fulfill all normative requirements. Conformance requirements are described in this document via both descriptive assertions and key words with clearly defined meanings. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative portions of this document are to be interpreted as described in <a href="https://tools.ietf.org/html/rfc2119">IETF RFC 2119</a>. These key words may appear in lowercase and still retain their meaning unless explicitly declared as non-normative. A conforming implementation of GraphQL may provide additional functionality, but must not where explicitly disallowed or would otherwise result in non-conformance. </section> <section id="sec-Conforming-Algorithms" class="subsec"> <h6 data-source="spec/GraphQL.md#L84"><a href="#sec-Conforming-Algorithms" title="link to this subsection">Conforming Algorithms</a></h6> Algorithm steps phrased in imperative grammar (e.g. “Return the result of calling resolver”) are to be interpreted with the same level of requirement as the algorithm it is contained within. Any algorithm referenced within an algorithm step (e.g. “Let completedResult be the result of calling CompleteValue()”) is to be interpreted as having at least the same level of requirement as the algorithm containing that step. Conformance requirements expressed as algorithms can be fulfilled by an implementation of this specification in any way as long as the perceived result is equivalent. Algorithms described in this document are written to be easy to understand. Implementers are encouraged to include equivalent but optimized implementations. See <a href="#sec-Appendix-Notation-Conventions">Appendix A</a> for more details about the definition of algorithms and other notational conventions used in this document. </section> <section id="sec-Non-Normative-Portions" class="subsec"> <h6 data-source="spec/GraphQL.md#L104"><a href="#sec-Non-Normative-Portions" title="link to this subsection">Non-Normative Portions</a></h6> All contents of this document are normative except portions explicitly declared as non-normative. Examples in this document are non-normative, and are presented to aid understanding of introduced concepts and the behavior of normative portions of the specification. Examples are either introduced explicitly in prose (e.g. “for example”) or are set apart in example or counter-example blocks, like this: <pre id="example-fed99" class="spec-example" data-source="spec/GraphQL.md#L115-L117"><a href="#example-fed99">Example № 1</a><code>This is an example of a non-normative example. </code></pre> <pre id="example-881bd" class="spec-counter-example" data-source="spec/GraphQL.md#L119-L121"><a href="#example-881bd">Counter Example № 2</a><code>This is an example of a non-normative counter-example. </code></pre> Notes in this document are non-normative, and are presented to clarify intent, draw attention to potential edge-cases and pit-falls, and answer common questions that arise during implementation. Notes are either introduced explicitly in prose (e.g. “Note: “) or are set apart in a note block, like this: <div id="note-c0129" class="spec-note" data-source="spec/GraphQL.md#L128"> <a href="#note-c0129">Note</a> This is an example of a non-normative note.</div> </section> </section> <nav class="spec-toc"> <div class="title">Contents</div> <ol> <li><a href="#sec-Overview">1Overview</a></li> <li><a href="#sec-Language">2Language</a><ol> <li><a href="#sec-Language.Source-Text">2.1Source Text</a><ol> <li><a href="#sec-Unicode">2.1.1Unicode</a></li> <li><a href="#sec-White-Space">2.1.2White Space</a></li> <li><a href="#sec-Line-Terminators">2.1.3Line Terminators</a></li> <li><a href="#sec-Comments">2.1.4Comments</a></li> <li><a href="#sec-Insignificant-Commas">2.1.5Insignificant Commas</a></li> <li><a href="#sec-Language.Source-Text.Lexical-Tokens">2.1.6Lexical Tokens</a></li> <li><a href="#sec-Language.Source-Text.Ignored-Tokens">2.1.7Ignored Tokens</a></li> <li><a href="#sec-Punctuators">2.1.8Punctuators</a></li> <li><a href="#sec-Names">2.1.9Names</a></li> </ol> </li> <li><a href="#sec-Document">2.2Document</a></li> <li><a href="#sec-Language.Operations">2.3Operations</a></li> <li><a href="#sec-Selection-Sets">2.4Selection Sets</a></li> <li><a href="#sec-Language.Fields">2.5Fields</a></li> <li><a href="#sec-Language.Arguments">2.6Arguments</a></li> <li><a href="#sec-Field-Alias">2.7Field Alias</a></li> <li><a href="#sec-Language.Fragments">2.8Fragments</a><ol> <li><a href="#sec-Type-Conditions">2.8.1Type Conditions</a></li> <li><a href="#sec-Inline-Fragments">2.8.2Inline Fragments</a></li> </ol> </li> <li><a href="#sec-Input-Values">2.9Input Values</a><ol> <li><a href="#sec-Int-Value">2.9.1Int Value</a></li> <li><a href="#sec-Float-Value">2.9.2Float Value</a></li> <li><a href="#sec-Boolean-Value">2.9.3Boolean Value</a></li> <li><a href="#sec-String-Value">2.9.4String Value</a></li> <li><a href="#sec-Null-Value">2.9.5Null Value</a></li> <li><a href="#sec-Enum-Value">2.9.6Enum Value</a></li> <li><a href="#sec-List-Value">2.9.7List Value</a></li> <li><a href="#sec-Input-Object-Values">2.9.8Input Object Values</a></li> </ol> </li> <li><a href="#sec-Language.Variables">2.10Variables</a></li> <li><a href="#sec-Type-References">2.11Type References</a></li> <li><a href="#sec-Language.Directives">2.12Directives</a></li> </ol> </li> <li><a href="#sec-Type-System">3Type System</a><ol> <li><a href="#sec-Type-System-Extensions">3.1Type System Extensions</a></li> <li><a href="#sec-Descriptions">3.2Descriptions</a></li> <li><a href="#sec-Schema">3.3Schema</a><ol> <li><a href="#sec-Root-Operation-Types">3.3.1Root Operation Types</a></li> <li><a href="#sec-Schema-Extension">3.3.2Schema Extension</a></li> </ol> </li> <li><a href="#sec-Types">3.4Types</a><ol> <li><a href="#sec-Wrapping-Types">3.4.1Wrapping Types</a></li> <li><a href="#sec-Input-and-Output-Types">3.4.2Input and Output Types</a></li> <li><a href="#sec-Type-Extensions">3.4.3Type Extensions</a></li> </ol> </li> <li><a href="#sec-Scalars">3.5Scalars</a><ol> <li><a href="#sec-Int">3.5.1Int</a></li> <li><a href="#sec-Float">3.5.2Float</a></li> <li><a href="#sec-String">3.5.3String</a></li> <li><a href="#sec-Boolean">3.5.4Boolean</a></li> <li><a href="#sec-ID">3.5.5ID</a></li> <li><a href="#sec-Scalar-Extensions">3.5.6Scalar Extensions</a></li> </ol> </li> <li><a href="#sec-Objects">3.6Objects</a><ol> <li><a href="#sec-Field-Arguments">3.6.1Field Arguments</a></li> <li><a href="#sec-Field-Deprecation">3.6.2Field Deprecation</a></li> <li><a href="#sec-Object-Extensions">3.6.3Object Extensions</a></li> </ol> </li> <li><a href="#sec-Interfaces">3.7Interfaces</a><ol> <li><a href="#sec-Interface-Extensions">3.7.1Interface Extensions</a></li> </ol> </li> <li><a href="#sec-Unions">3.8Unions</a><ol> <li><a href="#sec-Union-Extensions">3.8.1Union Extensions</a></li> </ol> </li> <li><a href="#sec-Enums">3.9Enums</a><ol> <li><a href="#sec-Enum-Extensions">3.9.1Enum Extensions</a></li> </ol> </li> <li><a href="#sec-Input-Objects">3.10Input Objects</a><ol> <li><a href="#sec-Input-Object-Extensions">3.10.1Input Object Extensions</a></li> </ol> </li> <li><a href="#sec-List">3.11List</a></li> <li><a href="#sec-Non-Null">3.12Non-Null</a><ol> <li><a href="#sec-Combining-List-and-Non-Null">3.12.1Combining List and Non-Null</a></li> </ol> </li> <li><a href="#sec-Type-System.Directives">3.13Directives</a><ol> <li><a href="#sec--skip">3.13.1@skip</a></li> <li><a href="#sec--include">3.13.2@include</a></li> <li><a href="#sec--deprecated">3.13.3@deprecated</a></li> <li><a href="#sec--specifiedBy">3.13.4@specifiedBy</a></li> </ol> </li> </ol> </li> <li><a href="#sec-Introspection">4Introspection</a><ol> <li><a href="#sec-Type-Name-Introspection">4.1Type Name Introspection</a></li> <li><a href="#sec-Schema-Introspection">4.2Schema Introspection</a><ol> <li><a href="#sec-The-__Schema-Type">4.2.1The __Schema Type</a></li> <li><a href="#sec-The-__Type-Type">4.2.2The __Type Type</a></li> <li><a href="#sec-The-__Field-Type">4.2.3The __Field Type</a></li> <li><a href="#sec-The-__InputValue-Type">4.2.4The __InputValue Type</a></li> <li><a href="#sec-The-__EnumValue-Type">4.2.5The __EnumValue Type</a></li> <li><a href="#sec-The-__Directive-Type">4.2.6The __Directive Type</a></li> </ol> </li> </ol> </li> <li><a href="#sec-Validation">5Validation</a><ol> <li><a href="#sec-Documents">5.1Documents</a><ol> <li><a href="#sec-Executable-Definitions">5.1.1Executable Definitions</a></li> </ol> </li> <li><a href="#sec-Validation.Operations">5.2Operations</a><ol> <li><a href="#sec-Named-Operation-Definitions">5.2.1Named Operation Definitions</a><ol> <li><a href="#sec-Operation-Name-Uniqueness">5.2.1.1Operation Name Uniqueness</a></li> </ol> </li> <li><a href="#sec-Anonymous-Operation-Definitions">5.2.2Anonymous Operation Definitions</a><ol> <li><a href="#sec-Lone-Anonymous-Operation">5.2.2.1Lone Anonymous Operation</a></li> </ol> </li> <li><a href="#sec-Subscription-Operation-Definitions">5.2.3Subscription Operation Definitions</a><ol> <li><a href="#sec-Single-root-field">5.2.3.1Single root field</a></li> </ol> </li> </ol> </li> <li><a href="#sec-Validation.Fields">5.3Fields</a><ol> <li><a href="#sec-Field-Selections">5.3.1Field Selections</a></li> <li><a href="#sec-Field-Selection-Merging">5.3.2Field Selection Merging</a></li> <li><a href="#sec-Leaf-Field-Selections">5.3.3Leaf Field Selections</a></li> </ol> </li> <li><a href="#sec-Validation.Arguments">5.4Arguments</a><ol> <li><a href="#sec-Argument-Names">5.4.1Argument Names</a></li> <li><a href="#sec-Argument-Uniqueness">5.4.2Argument Uniqueness</a><ol> <li><a href="#sec-Required-Arguments">5.4.2.1Required Arguments</a></li> </ol> </li> </ol> </li> <li><a href="#sec-Validation.Fragments">5.5Fragments</a><ol> <li><a href="#sec-Fragment-Declarations">5.5.1Fragment Declarations</a><ol> <li><a href="#sec-Fragment-Name-Uniqueness">5.5.1.1Fragment Name Uniqueness</a></li> <li><a href="#sec-Fragment-Spread-Type-Existence">5.5.1.2Fragment Spread Type Existence</a></li> <li><a href="#sec-Fragments-On-Composite-Types">5.5.1.3Fragments On Composite Types</a></li> <li><a href="#sec-Fragments-Must-Be-Used">5.5.1.4Fragments Must Be Used</a></li> </ol> </li> <li><a href="#sec-Fragment-Spreads">5.5.2Fragment Spreads</a><ol> <li><a href="#sec-Fragment-spread-target-defined">5.5.2.1Fragment spread target defined</a></li> <li><a href="#sec-Fragment-spreads-must-not-form-cycles">5.5.2.2Fragment spreads must not form cycles</a></li> <li><a href="#sec-Fragment-spread-is-possible">5.5.2.3Fragment spread is possible</a><ol> <li><a href="#sec-Object-Spreads-In-Object-Scope">5.5.2.3.1Object Spreads In Object Scope</a></li> <li><a href="#sec-Abstract-Spreads-in-Object-Scope">5.5.2.3.2Abstract Spreads in Object Scope</a></li> <li><a href="#sec-Object-Spreads-In-Abstract-Scope">5.5.2.3.3Object Spreads In Abstract Scope</a></li> <li><a href="#sec-Abstract-Spreads-in-Abstract-Scope">5.5.2.3.4Abstract Spreads in Abstract Scope</a></li> </ol> </li> </ol> </li> </ol> </li> <li><a href="#sec-Values">5.6Values</a><ol> <li><a href="#sec-Values-of-Correct-Type">5.6.1Values of Correct Type</a></li> <li><a href="#sec-Input-Object-Field-Names">5.6.2Input Object Field Names</a></li> <li><a href="#sec-Input-Object-Field-Uniqueness">5.6.3Input Object Field Uniqueness</a></li> <li><a href="#sec-Input-Object-Required-Fields">5.6.4Input Object Required Fields</a></li> </ol> </li> <li><a href="#sec-Validation.Directives">5.7Directives</a><ol> <li><a href="#sec-Directives-Are-Defined">5.7.1Directives Are Defined</a></li> <li><a href="#sec-Directives-Are-In-Valid-Locations">5.7.2Directives Are In Valid Locations</a></li> <li><a href="#sec-Directives-Are-Unique-Per-Location">5.7.3Directives Are Unique Per Location</a></li> </ol> </li> <li><a href="#sec-Validation.Variables">5.8Variables</a><ol> <li><a href="#sec-Variable-Uniqueness">5.8.1Variable Uniqueness</a></li> <li><a href="#sec-Variables-Are-Input-Types">5.8.2Variables Are Input Types</a></li> <li><a href="#sec-All-Variable-Uses-Defined">5.8.3All Variable Uses Defined</a></li> <li><a href="#sec-All-Variables-Used">5.8.4All Variables Used</a></li> <li><a href="#sec-All-Variable-Usages-are-Allowed">5.8.5All Variable Usages are Allowed</a></li> </ol> </li> </ol> </li> <li><a href="#sec-Execution">6Execution</a><ol> <li><a href="#sec-Executing-Requests">6.1Executing Requests</a><ol> <li><a href="#sec-Validating-Requests">6.1.1Validating Requests</a></li> <li><a href="#sec-Coercing-Variable-Values">6.1.2Coercing Variable Values</a></li> </ol> </li> <li><a href="#sec-Executing-Operations">6.2Executing Operations</a><ol> <li><a href="#sec-Query">6.2.1Query</a></li> <li><a href="#sec-Mutation">6.2.2Mutation</a></li> <li><a href="#sec-Subscription">6.2.3Subscription</a><ol> <li><a href="#sec-Source-Stream">6.2.3.1Source Stream</a></li> <li><a href="#sec-Response-Stream">6.2.3.2Response Stream</a></li> <li><a href="#sec-Unsubscribe">6.2.3.3Unsubscribe</a></li> </ol> </li> </ol> </li> <li><a href="#sec-Executing-Selection-Sets">6.3Executing Selection Sets</a><ol> <li><a href="#sec-Normal-and-Serial-Execution">6.3.1Normal and Serial Execution</a></li> <li><a href="#sec-Field-Collection">6.3.2Field Collection</a></li> </ol> </li> <li><a href="#sec-Executing-Fields">6.4Executing Fields</a><ol> <li><a href="#sec-Coercing-Field-Arguments">6.4.1Coercing Field Arguments</a></li> <li><a href="#sec-Value-Resolution">6.4.2Value Resolution</a></li> <li><a href="#sec-Value-Completion">6.4.3Value Completion</a></li> <li><a href="#sec-Handling-Field-Errors">6.4.4Handling Field Errors</a></li> </ol> </li> </ol> </li> <li><a href="#sec-Response">7Response</a><ol> <li><a href="#sec-Response-Format">7.1Response Format</a><ol> <li><a href="#sec-Data">7.1.1Data</a></li> <li><a href="#sec-Errors">7.1.2Errors</a></li> </ol> </li> <li><a href="#sec-Serialization-Format">7.2Serialization Format</a><ol> <li><a href="#sec-JSON-Serialization">7.2.1JSON Serialization</a></li> <li><a href="#sec-Serialized-Map-Ordering">7.2.2Serialized Map Ordering</a></li> </ol> </li> </ol> </li> <li><a href="#sec-Appendix-Notation-Conventions">AAppendix: Notation Conventions</a><ol> <li><a href="#sec-Context-Free-Grammar">A.1Context-Free Grammar</a></li> <li><a href="#sec-Lexical-and-Syntactical-Grammar">A.2Lexical and Syntactical Grammar</a></li> <li><a href="#sec-Grammar-Notation">A.3Grammar Notation</a></li> <li><a href="#sec-Grammar-Semantics">A.4Grammar Semantics</a></li> <li><a href="#sec-Algorithms">A.5Algorithms</a></li> </ol> </li> <li><a href="#sec-Appendix-Grammar-Summary">BAppendix: Grammar Summary</a><ol> <li><a href="#sec-Appendix-Grammar-Summary.Source-Text">B.1Source Text</a></li> <li><a href="#sec-Appendix-Grammar-Summary.Ignored-Tokens">B.2Ignored Tokens</a></li> <li><a href="#sec-Appendix-Grammar-Summary.Lexical-Tokens">B.3Lexical Tokens</a></li> <li><a href="#sec-Document-Syntax">B.4Document Syntax</a></li> </ol> </li> <li><a href="#index">§Index</a></li> </ol> </nav> </header> <section id="sec-Overview" secid="1"> <h1 data-source="spec/Section%201%20--%20Overview.md#L1"><a href="#sec-Overview">1</a>Overview</h1> GraphQL is a query language designed to build client applications by providing an intuitive and flexible syntax and system for describing their data requirements and interactions. For example, this GraphQL request will receive the name of the user with id 4 from the Facebook implementation of GraphQL. <pre id="example-85684" class="spec-example" data-language="graphql" data-source="spec/Section%201%20--%20Overview.md#L10-L16"><a href="#example-85684">Example № 3</a><code>{ user(id: 4) { name } } </code></pre> Which produces the resulting data (in JSON): <pre id="example-90fe6" class="spec-example" data-language="json" data-source="spec/Section%201%20--%20Overview.md#L20-L26"><a href="#example-90fe6">Example № 4</a><code>{ "user": { "name": "Mark Zuckerberg" } } </code></pre> GraphQL is not a programming language capable of arbitrary computation, but is instead a language used to make requests to application services that have capabilities defined in this specification. GraphQL does not mandate a particular programming language or storage system for application services that implement it. Instead, application services take their capabilities and map them to a uniform language, type system, and philosophy that GraphQL encodes. This provides a unified interface friendly to product development and a powerful platform for tool-building. GraphQL has a number of design principles: <ul> <li data-source="spec/Section%201%20--%20Overview.md#L39-L42">Product-centric: GraphQL is unapologetically driven by the requirements of views and the front-end engineers that write them. GraphQL starts with their way of thinking and requirements and builds the language and runtime necessary to enable that.</li> <li data-source="spec/Section%201%20--%20Overview.md#L44-L48">Hierarchical: Most product development today involves the creation and manipulation of view hierarchies. To achieve congruence with the structure of these applications, a GraphQL request itself is structured hierarchically. The request is shaped just like the data in its response. It is a natural way for clients to describe data requirements.</li> <li data-source="spec/Section%201%20--%20Overview.md#L50-L55">Strong-typing: Every GraphQL service defines an application-specific type system. Requests are executed within the context of that type system. Given a GraphQL operation, tools can ensure that it is both syntactically correct and valid within that type system before execution, i.e. at development time, and the service can make certain guarantees about the shape and nature of the response.</li> <li data-source="spec/Section%201%20--%20Overview.md#L57-L64">Client-specified response: Through its type system, a GraphQL service publishes the capabilities that its clients are allowed to consume. It is the client that is responsible for specifying exactly how it will consume those published capabilities. These requests are specified at field-level granularity. In the majority of client-server applications written without GraphQL, the service determines the shape of data returned from its various endpoints. A GraphQL response, on the other hand, contains exactly what a client asks for and no more.</li> <li data-source="spec/Section%201%20--%20Overview.md#L66-L69">Introspective: GraphQL is introspective. A GraphQL service’s type system can be queryable by the GraphQL language itself, as will be described in this specification. GraphQL introspection serves as a powerful platform for building common tools and client software libraries.</li> </ul> Because of these principles, GraphQL is a powerful and productive environment for building client applications. Product developers and designers building applications against working GraphQL services—supported with quality tools—can quickly become productive without reading extensive documentation and with little or no formal training. To enable that experience, there must be those that build those services and tools. The following formal specification serves as a reference for those builders. It describes the language and its grammar, the type system and the introspection system used to query it, and the execution and validation engines with the algorithms to power them. The goal of this specification is to provide a foundation and framework for an ecosystem of GraphQL tools, client libraries, and service implementations—spanning both organizations and platforms—that has yet to be built. We look forward to working with the community in order to do that. </section> <section id="sec-Language" secid="2"> <h1 data-source="spec/Section%202%20--%20Language.md#L1"><a href="#sec-Language">2</a>Language</h1> Clients use the GraphQL query language to make requests to a GraphQL service. We refer to these request sources as documents. A document may contain operations (queries, mutations, and subscriptions) as well as fragments, a common unit of composition allowing for data requirement reuse. A GraphQL document is defined as a syntactic grammar where terminal symbols are tokens (indivisible lexical units). These tokens are defined in a lexical grammar which matches patterns of source characters. In this document, syntactic grammar productions are distinguished with a colon <code>:</code> while lexical grammar productions are distinguished with a double-colon <code>::</code>. The source text of a GraphQL document must be a sequence of <a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a>. The character sequence must be described by a sequence of <a href="#Token" data-name="Token">Token</a> and <a href="#Ignored" data-name="Ignored">Ignored</a> lexical grammars. The lexical token sequence, omitting <a href="#Ignored" data-name="Ignored">Ignored</a>, must be described by a single <a href="#Document" data-name="Document">Document</a> syntactic grammar. <div id="note-e800c" class="spec-note" data-source="spec/Section%202%20--%20Language.md#L19-L21"> <a href="#note-e800c">Note</a> See <a href="#sec-Appendix-Notation-Conventions">Appendix A</a> for more information about the lexical and syntactic grammar and other notational conventions used throughout this document.</div> <section id="sec-Language.Lexical-Analysis-Syntactic-Parse" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L23"><a href="#sec-Language.Lexical-Analysis-Syntactic-Parse" title="link to this subsection">Lexical Analysis & Syntactic Parse</a></h6> The source text of a GraphQL document is first converted into a sequence of lexical tokens, <a href="#Token" data-name="Token">Token</a>, and ignored tokens, <a href="#Ignored" data-name="Ignored">Ignored</a>. The source text is scanned from left to right, repeatedly taking the next possible sequence of code-points allowed by the lexical grammar productions as the next token. This sequence of lexical tokens are then scanned from left to right to produce an abstract syntax tree (AST) according to the <a href="#Document" data-name="Document">Document</a> syntactical grammar. Lexical grammar productions in this document use lookahead restrictions to remove ambiguity and ensure a single valid lexical analysis. A lexical token is only valid if not followed by a character in its lookahead restriction. For example, an <a href="#IntValue" data-name="IntValue">IntValue</a> has the restriction <a href="#Digit" data-name="Digit">Digit</a>, so cannot be followed by a <a href="#Digit" data-name="Digit">Digit</a>. Because of this, the sequence 123 cannot represent the tokens (12, 3) since 12 is followed by the <a href="#Digit" data-name="Digit">Digit</a> 3 and so must only represent a single token. Use <a href="#WhiteSpace" data-name="WhiteSpace">WhiteSpace</a> or other <a href="#Ignored" data-name="Ignored">Ignored</a> between characters to represent multiple tokens. <div id="note-ba22f" class="spec-note" data-source="spec/Section%202%20--%20Language.md#L42-L44"> <a href="#note-ba22f">Note</a> This typically has the same behavior as a “<a href="https://en.wikipedia.org/wiki/Maximal_munch">maximal munch</a>” longest possible match, however some lookahead restrictions include additional constraints.</div> </section> <section id="sec-Language.Source-Text" secid="2.1"> <h2 data-source="spec/Section%202%20--%20Language.md#L47"><a href="#sec-Language.Source-Text">2.1</a>Source Text</h2> <div class="spec-production d2" id="SourceCharacter" data-source="spec/Section%202%20--%20Language.md#L49-L53"> <a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a><div class="spec-rhs">U+0009</div> <div class="spec-rhs">U+000A</div> <div class="spec-rhs">U+000D</div> <div class="spec-rhs">U+0020–U+FFFF</div> </div> GraphQL documents are expressed as a sequence of <a href="https://unicode.org/standard/standard.html">Unicode</a> code points (informally referred to as “characters” through most of this specification). However, with few exceptions, most of GraphQL is expressed only in the original non-control ASCII range so as to be as widely compatible with as many existing tools, languages, and serialization formats as possible and avoid display issues in text editors and source control. <div id="note-3e8b0" class="spec-note" data-source="spec/Section%202%20--%20Language.md#L63-L64"> <a href="#note-3e8b0">Note</a> Non-ASCII Unicode characters may appear freely within <a href="#StringValue" data-name="StringValue">StringValue</a> and <a href="#Comment" data-name="Comment">Comment</a> portions of GraphQL.</div> <section id="sec-Unicode" secid="2.1.1"> <h3 data-source="spec/Section%202%20--%20Language.md#L67"><a href="#sec-Unicode">2.1.1</a>Unicode</h3> <div class="spec-production d2" id="UnicodeBOM" data-source="spec/Section%202%20--%20Language.md#L69"> <a href="#UnicodeBOM" data-name="UnicodeBOM">UnicodeBOM</a><div class="spec-rhs">Byte Order Mark (U+FEFF)</div> </div> The “Byte Order Mark” is a special Unicode character which may appear at the beginning of a file containing Unicode which programs may use to determine the fact that the text stream is Unicode, what endianness the text stream is in, and which of several Unicode encodings to interpret. </section> <section id="sec-White-Space" secid="2.1.2"> <h3 data-source="spec/Section%202%20--%20Language.md#L77"><a href="#sec-White-Space">2.1.2</a>White Space</h3> <div class="spec-production d2" id="WhiteSpace" data-source="spec/Section%202%20--%20Language.md#L79-L81"> <a href="#WhiteSpace" data-name="WhiteSpace">WhiteSpace</a><div class="spec-rhs">Horizontal Tab (U+0009)</div> <div class="spec-rhs">Space (U+0020)</div> </div> White space is used to improve legibility of source text and act as separation between tokens, and any amount of white space may appear before or after any token. White space between tokens is not significant to the semantic meaning of a GraphQL Document, however white space characters may appear within a String or <a href="#Comment" data-name="Comment">Comment</a> token. <div id="note-e49cd" class="spec-note" data-source="spec/Section%202%20--%20Language.md#L89-L91"> <a href="#note-e49cd">Note</a> GraphQL intentionally does not consider Unicode “Zs” category characters as white-space, avoiding misinterpretation by text editors and source control tools.</div> </section> <section id="sec-Line-Terminators" secid="2.1.3"> <h3 data-source="spec/Section%202%20--%20Language.md#L94"><a href="#sec-Line-Terminators">2.1.3</a>Line Terminators</h3> <div class="spec-production d2" id="LineTerminator" data-source="spec/Section%202%20--%20Language.md#L96-L99"> <a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a><div class="spec-rhs">New Line (U+000A)</div> <div class="spec-rhs">Carriage Return (U+000D)New Line (U+000A)</div> <div class="spec-rhs">Carriage Return (U+000D)New Line (U+000A)</div> </div> Like white space, line terminators are used to improve the legibility of source text and separate lexical tokens, any amount may appear before or after any other token and have no significance to the semantic meaning of a GraphQL Document. Line terminators are not found within any other token. <div id="note-2b19e" class="spec-note" data-source="spec/Section%202%20--%20Language.md#L106-L108"> <a href="#note-2b19e">Note</a> Any error reporting which provides the line number in the source of the offending syntax should use the preceding amount of <a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a> to produce the line number.</div> </section> <section id="sec-Comments" secid="2.1.4"> <h3 data-source="spec/Section%202%20--%20Language.md#L111"><a href="#sec-Comments">2.1.4</a>Comments</h3> <div class="spec-production d2" id="Comment" data-source="spec/Section%202%20--%20Language.md#L113"> <a href="#Comment" data-name="Comment">Comment</a><div class="spec-rhs">#<a href="#CommentChar" data-name="CommentChar">CommentChar</a>listopt<a href="#CommentChar" data-name="CommentChar">CommentChar</a></div> </div> <div class="spec-production d2" id="CommentChar" data-source="spec/Section%202%20--%20Language.md#L115"> <a href="#CommentChar" data-name="CommentChar">CommentChar</a><div class="spec-rhs"><a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a><a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a></div> </div> GraphQL source documents may contain single-line comments, starting with the # marker. A comment can contain any Unicode code point in <a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a> except <a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a> so a comment always consists of all code points starting with the # character up to but not including the <a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a> (or end of the source). Comments are <a href="#Ignored" data-name="Ignored">Ignored</a> like white space and may appear after any token, or before a <a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a>, and have no significance to the semantic meaning of a GraphQL Document. </section> <section id="sec-Insignificant-Commas" secid="2.1.5"> <h3 data-source="spec/Section%202%20--%20Language.md#L130"><a href="#sec-Insignificant-Commas">2.1.5</a>Insignificant Commas</h3> <div class="spec-production d2" id="Comma" data-source="spec/Section%202%20--%20Language.md#L132"> <a href="#Comma" data-name="Comma">Comma</a><div class="spec-rhs">,</div> </div> Similar to white space and line terminators, commas (,) are used to improve the legibility of source text and separate lexical tokens but are otherwise syntactically and semantically insignificant within GraphQL Documents. Non-significant comma characters ensure that the absence or presence of a comma does not meaningfully alter the interpreted syntax of the document, as this can be a common user-error in other languages. It also allows for the stylistic use of either trailing commas or line terminators as list delimiters which are both often desired for legibility and maintainability of source code. </section> <section id="sec-Language.Source-Text.Lexical-Tokens" secid="2.1.6"> <h3 data-source="spec/Section%202%20--%20Language.md#L145"><a href="#sec-Language.Source-Text.Lexical-Tokens">2.1.6</a>Lexical Tokens</h3> <div class="spec-production d2" id="Token" data-source="spec/Section%202%20--%20Language.md#L147-L152"> <a href="#Token" data-name="Token">Token</a><div class="spec-rhs"><a href="#Punctuator" data-name="Punctuator">Punctuator</a></div> <div class="spec-rhs"><a href="#Name" data-name="Name">Name</a></div> <div class="spec-rhs"><a href="#IntValue" data-name="IntValue">IntValue</a></div> <div class="spec-rhs"><a href="#FloatValue" data-name="FloatValue">FloatValue</a></div> <div class="spec-rhs"><a href="#StringValue" data-name="StringValue">StringValue</a></div> </div> A GraphQL document is comprised of several kinds of indivisible lexical tokens defined here in a lexical grammar by patterns of source Unicode characters. Lexical tokens may be separated by <a href="#Ignored" data-name="Ignored">Ignored</a> tokens. Tokens are later used as terminal symbols in GraphQL syntactic grammar rules. </section> <section id="sec-Language.Source-Text.Ignored-Tokens" secid="2.1.7"> <h3 data-source="spec/Section%202%20--%20Language.md#L161"><a href="#sec-Language.Source-Text.Ignored-Tokens">2.1.7</a>Ignored Tokens</h3> <div class="spec-production d2" id="Ignored" data-source="spec/Section%202%20--%20Language.md#L163-L168"> <a href="#Ignored" data-name="Ignored">Ignored</a><div class="spec-rhs"><a href="#UnicodeBOM" data-name="UnicodeBOM">UnicodeBOM</a></div> <div class="spec-rhs"><a href="#WhiteSpace" data-name="WhiteSpace">WhiteSpace</a></div> <div class="spec-rhs"><a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a></div> <div class="spec-rhs"><a href="#Comment" data-name="Comment">Comment</a></div> <div class="spec-rhs"><a href="#Comma" data-name="Comma">Comma</a></div> </div> <a href="#Ignored" data-name="Ignored">Ignored</a> tokens are used to improve readability and provide separation between lexical tokens, but are otherwise insignificant and not referenced in syntactical grammar productions. Any amount of <a href="#Ignored" data-name="Ignored">Ignored</a> may appear before and after every lexical token. No ignored regions of a source document are significant, however <a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a> which appear in <a href="#Ignored" data-name="Ignored">Ignored</a> may also appear within a lexical <a href="#Token" data-name="Token">Token</a> in a significant way, for example a <a href="#StringValue" data-name="StringValue">StringValue</a> may contain white space characters. No <a href="#Ignored" data-name="Ignored">Ignored</a> may appear within a <a href="#Token" data-name="Token">Token</a>, for example no white space characters are permitted between the characters defining a <a href="#FloatValue" data-name="FloatValue">FloatValue</a>. </section> <section id="sec-Punctuators" secid="2.1.8"> <h3 data-source="spec/Section%202%20--%20Language.md#L182"><a href="#sec-Punctuators">2.1.8</a>Punctuators</h3> <div class="spec-production d2" id="Punctuator" data-source="spec/Section%202%20--%20Language.md#L184"> <a href="#Punctuator" data-name="Punctuator">Punctuator</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">!</td><td class="spec-rhs">$</td><td class="spec-rhs">&</td><td class="spec-rhs">(</td><td class="spec-rhs">)</td><td class="spec-rhs">...</td><td class="spec-rhs">:</td><td class="spec-rhs">=</td><td class="spec-rhs">@</td><td class="spec-rhs">[</td><td class="spec-rhs">]</td><td class="spec-rhs">{</td><td class="spec-rhs">|</td><td class="spec-rhs">}</td></tr> </table></div></div> </div> GraphQL documents include punctuation in order to describe structure. GraphQL is a data description language and not a programming language, therefore GraphQL lacks the punctuation often used to describe mathematical expressions. </section> <section id="sec-Names" secid="2.1.9"> <h3 data-source="spec/Section%202%20--%20Language.md#L191"><a href="#sec-Names">2.1.9</a>Names</h3> <div class="spec-production d2" id="Name" data-source="spec/Section%202%20--%20Language.md#L193-L194"> <a href="#Name" data-name="Name">Name</a><div class="spec-rhs"><a href="#NameStart" data-name="NameStart">NameStart</a><a href="#NameContinue" data-name="NameContinue">NameContinue</a>listopt<a href="#NameContinue" data-name="NameContinue">NameContinue</a></div> </div> <div class="spec-production d2" id="NameStart" data-source="spec/Section%202%20--%20Language.md#L196-L198"> <a href="#NameStart" data-name="NameStart">NameStart</a><div class="spec-rhs"><a href="#Letter" data-name="Letter">Letter</a></div> <div class="spec-rhs">_</div> </div> <div class="spec-production d2" id="NameContinue" data-source="spec/Section%202%20--%20Language.md#L200-L203"> <a href="#NameContinue" data-name="NameContinue">NameContinue</a><div class="spec-rhs"><a href="#Letter" data-name="Letter">Letter</a></div> <div class="spec-rhs"><a href="#Digit" data-name="Digit">Digit</a></div> <div class="spec-rhs">_</div> </div> <div class="spec-production d2" id="Letter" data-source="spec/Section%202%20--%20Language.md#L205-L209"> <a href="#Letter" data-name="Letter">Letter</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">A</td><td class="spec-rhs">B</td><td class="spec-rhs">C</td><td class="spec-rhs">D</td><td class="spec-rhs">E</td><td class="spec-rhs">F</td><td class="spec-rhs">G</td><td class="spec-rhs">H</td><td class="spec-rhs">I</td><td class="spec-rhs">J</td><td class="spec-rhs">K</td><td class="spec-rhs">L</td><td class="spec-rhs">M</td></tr> <tr> <td class="spec-rhs">N</td><td class="spec-rhs">O</td><td class="spec-rhs">P</td><td class="spec-rhs">Q</td><td class="spec-rhs">R</td><td class="spec-rhs">S</td><td class="spec-rhs">T</td><td class="spec-rhs">U</td><td class="spec-rhs">V</td><td class="spec-rhs">W</td><td class="spec-rhs">X</td><td class="spec-rhs">Y</td><td class="spec-rhs">Z</td></tr> <tr> <td class="spec-rhs">a</td><td class="spec-rhs">b</td><td class="spec-rhs">c</td><td class="spec-rhs">d</td><td class="spec-rhs">e</td><td class="spec-rhs">f</td><td class="spec-rhs">g</td><td class="spec-rhs">h</td><td class="spec-rhs">i</td><td class="spec-rhs">j</td><td class="spec-rhs">k</td><td class="spec-rhs">l</td><td class="spec-rhs">m</td></tr> <tr> <td class="spec-rhs">n</td><td class="spec-rhs">o</td><td class="spec-rhs">p</td><td class="spec-rhs">q</td><td class="spec-rhs">r</td><td class="spec-rhs">s</td><td class="spec-rhs">t</td><td class="spec-rhs">u</td><td class="spec-rhs">v</td><td class="spec-rhs">w</td><td class="spec-rhs">x</td><td class="spec-rhs">y</td><td class="spec-rhs">z</td></tr> </table></div></div> </div> <div class="spec-production d2" id="Digit" data-source="spec/Section%202%20--%20Language.md#L211-L212"> <a href="#Digit" data-name="Digit">Digit</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">0</td><td class="spec-rhs">1</td><td class="spec-rhs">2</td><td class="spec-rhs">3</td><td class="spec-rhs">4</td><td class="spec-rhs">5</td><td class="spec-rhs">6</td><td class="spec-rhs">7</td><td class="spec-rhs">8</td><td class="spec-rhs">9</td></tr> </table></div></div> </div> GraphQL Documents are full of named things: operations, fields, arguments, types, directives, fragments, and variables. All names must follow the same grammatical form. Names in GraphQL are case-sensitive. That is to say <code>name</code>, <code>Name</code>, and <code>NAME</code> all refer to different names. Underscores are significant, which means <code>other_name</code> and <code>othername</code> are two different names. A <a href="#Name" data-name="Name">Name</a> must not be followed by a <a href="#NameContinue" data-name="NameContinue">NameContinue</a>. In other words, a <a href="#Name" data-name="Name">Name</a> token is always the longest possible valid sequence. The source characters a1 cannot be interpreted as two tokens since a is followed by the <a href="#NameContinue" data-name="NameContinue">NameContinue</a> 1. <div id="note-46408" class="spec-note" data-source="spec/Section%202%20--%20Language.md#L226-L228"> <a href="#note-46408">Note</a> Names in GraphQL are limited to the Latin <acronym>ASCII</acronym> subset of <a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a> in order to support interoperation with as many other systems as possible.</div> <section id="sec-Names.Reserved-Names" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L230"><a href="#sec-Names.Reserved-Names" title="link to this subsection">Reserved Names</a></h6> Any <a href="#Name" data-name="Name">Name</a> within a GraphQL type system must not start with two underscores "__" unless it is part of the <a href="#sec-Introspection">introspection system</a> as defined by this specification. </section> </section> </section> <section id="sec-Document" secid="2.2"> <h2 data-source="spec/Section%202%20--%20Language.md#L237"><a href="#sec-Document">2.2</a>Document</h2> <div class="spec-production" id="Document" data-source="spec/Section%202%20--%20Language.md#L239"> <a href="#Document" data-name="Document">Document</a><div class="spec-rhs"><a href="#Definition" data-name="Definition">Definition</a>list</div> </div> <div class="spec-production" id="Definition" data-source="spec/Section%202%20--%20Language.md#L241-L243"> <a href="#Definition" data-name="Definition">Definition</a><div class="spec-rhs"><a href="#ExecutableDefinition" data-name="ExecutableDefinition">ExecutableDefinition</a></div> <div class="spec-rhs"><a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a></div> </div> <div class="spec-production" id="ExecutableDocument" data-source="spec/Section%202%20--%20Language.md#L245"> <a href="#ExecutableDocument" data-name="ExecutableDocument">ExecutableDocument</a><div class="spec-rhs"><a href="#ExecutableDefinition" data-name="ExecutableDefinition">ExecutableDefinition</a>list</div> </div> <div class="spec-production" id="ExecutableDefinition" data-source="spec/Section%202%20--%20Language.md#L247-L249"> <a href="#ExecutableDefinition" data-name="ExecutableDefinition">ExecutableDefinition</a><div class="spec-rhs"><a href="#OperationDefinition" data-name="OperationDefinition">OperationDefinition</a></div> <div class="spec-rhs"><a href="#FragmentDefinition" data-name="FragmentDefinition">FragmentDefinition</a></div> </div> A GraphQL Document describes a complete file or request string operated on by a GraphQL service or client. A document contains multiple definitions, either executable or representative of a GraphQL type system. Documents are only executable by a GraphQL service if they are <a href="#ExecutableDocument" data-name="ExecutableDocument">ExecutableDocument</a> and contain at least one <a href="#OperationDefinition" data-name="OperationDefinition">OperationDefinition</a>. A Document which contains <a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a> must not be executed; GraphQL execution services which receive a Document containing these should return a descriptive error. GraphQL services which only seek to execute GraphQL requests and not construct a new GraphQL schema may choose to only permit <a href="#ExecutableDocument" data-name="ExecutableDocument">ExecutableDocument</a>. Documents which do not contain <a href="#OperationDefinition" data-name="OperationDefinition">OperationDefinition</a> or do contain <a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a> may still be parsed and validated to allow client tools to represent many GraphQL uses which may appear across many individual files. If a Document contains only one operation, that operation may be unnamed. If that operation is a query without variables or directives then it may also be represented in the shorthand form, omitting both the query keyword as well as the operation name. Otherwise, if a GraphQL Document contains multiple operations, each operation must be named. When submitting a Document with multiple operations to a GraphQL service, the name of the desired operation to be executed must also be provided. </section> <section id="sec-Language.Operations" secid="2.3"> <h2 data-source="spec/Section%202%20--%20Language.md#L278"><a href="#sec-Language.Operations">2.3</a>Operations</h2> <div class="spec-production" id="OperationDefinition" data-source="spec/Section%202%20--%20Language.md#L280-L282"> <a href="#OperationDefinition" data-name="OperationDefinition">OperationDefinition</a><div class="spec-rhs"><a href="#OperationType" data-name="OperationType">OperationType</a><a href="#Name" data-name="Name">Name</a>opt<a href="#VariableDefinitions" data-name="VariableDefinitions">VariableDefinitions</a>opt<a href="#Directives" data-name="Directives">Directives</a>opt<a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a></div> <div class="spec-rhs"><a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a></div> </div> <div class="spec-production" id="OperationType" data-source="spec/Section%202%20--%20Language.md#L284"> <a href="#OperationType" data-name="OperationType">OperationType</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">query</td><td class="spec-rhs">mutation</td><td class="spec-rhs">subscription</td></tr> </table></div></div> </div> There are three types of operations that GraphQL models: <ul> <li data-source="spec/Section%202%20--%20Language.md#L288">query – a read-only fetch.</li> <li data-source="spec/Section%202%20--%20Language.md#L289">mutation – a write followed by a fetch.</li> <li data-source="spec/Section%202%20--%20Language.md#L290-L291">subscription – a long-lived request that fetches data in response to source events.</li> </ul> Each operation is represented by an optional operation name and a selection set. For example, this mutation operation might “like” a story and then retrieve the new number of likes: <pre id="example-ed6a8" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L298-L306"><a href="#example-ed6a8">Example № 5</a><code>mutation { likeStory(storyID: 12345) { story { likeCount } } } </code></pre> <section id="sec-Language.Operations.Query-shorthand" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L308"><a href="#sec-Language.Operations.Query-shorthand" title="link to this subsection">Query shorthand</a></h6> If a document contains only one operation and that operation is a query which defines no variables and contains no directives then that operation may be represented in a short-hand form which omits the query keyword and operation name. For example, this unnamed query operation is written via query shorthand. <pre id="example-63b18" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L317-L321"><a href="#example-63b18">Example № 6</a><code>{ field } </code></pre> <div id="note-5e20f" class="spec-note" data-source="spec/Section%202%20--%20Language.md#L323"> <a href="#note-5e20f">Note</a> many examples below will use the query short-hand syntax.</div> </section> </section> <section id="sec-Selection-Sets" secid="2.4"> <h2 data-source="spec/Section%202%20--%20Language.md#L326"><a href="#sec-Selection-Sets">2.4</a>Selection Sets</h2> <div class="spec-production" id="SelectionSet" data-source="spec/Section%202%20--%20Language.md#L328"> <a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a><div class="spec-rhs">{<a href="#Selection" data-name="Selection">Selection</a>list}</div> </div> <div class="spec-production" id="Selection" data-source="spec/Section%202%20--%20Language.md#L330-L333"> <a href="#Selection" data-name="Selection">Selection</a><div class="spec-rhs"><a href="#Field" data-name="Field">Field</a></div> <div class="spec-rhs"><a href="#FragmentSpread" data-name="FragmentSpread">FragmentSpread</a></div> <div class="spec-rhs"><a href="#InlineFragment" data-name="InlineFragment">InlineFragment</a></div> </div> An operation selects the set of information it needs, and will receive exactly that information and nothing more, avoiding over-fetching and under-fetching data. <pre id="example-21649" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L339-L345"><a href="#example-21649">Example № 7</a><code>{ id firstName lastName } </code></pre> In this query operation, the <code>id</code>, <code>firstName</code>, and <code>lastName</code> fields form a selection set. Selection sets may also contain fragment references. </section> <section id="sec-Language.Fields" secid="2.5"> <h2 data-source="spec/Section%202%20--%20Language.md#L351"><a href="#sec-Language.Fields">2.5</a>Fields</h2> <div class="spec-production" id="Field" data-source="spec/Section%202%20--%20Language.md#L353"> <a href="#Field" data-name="Field">Field</a><div class="spec-rhs"><a href="#Alias" data-name="Alias">Alias</a>opt<a href="#Name" data-name="Name">Name</a><a href="#Arguments" data-name="Arguments">Arguments</a>opt<a href="#Directives" data-name="Directives">Directives</a>opt<a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a>opt</div> </div> A selection set is primarily composed of fields. A field describes one discrete piece of information available to request within a selection set. Some fields describe complex data or relationships to other data. In order to further explore this data, a field may itself contain a selection set, allowing for deeply nested requests. All GraphQL operations must specify their selections down to fields which return scalar values to ensure an unambiguously shaped response. For example, this operation selects fields of complex data and relationships down to scalar values. <pre id="example-100a3" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L367-L382"><a href="#example-100a3">Example № 8</a><code>{ me { id firstName lastName birthday { month day } friends { name } } } </code></pre> Fields in the top-level selection set of an operation often represent some information that is globally accessible to your application and its current viewer. Some typical examples of these top fields include references to a current logged-in viewer, or accessing certain types of data referenced by a unique identifier. <pre id="example-e1984" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L390-L405"><a href="#example-e1984">Example № 9</a><code># `me` could represent the currently logged in viewer. { me { name } } # `user` represents one of many users in a graph of data, referred to by a # unique identifier. { user(id: 4) { name } } </code></pre> </section> <section id="sec-Language.Arguments" secid="2.6"> <h2 data-source="spec/Section%202%20--%20Language.md#L408"><a href="#sec-Language.Arguments">2.6</a>Arguments</h2> <div class="spec-production" id="Arguments" data-source="spec/Section%202%20--%20Language.md#L410"> <a href="#Arguments" data-name="Arguments">Arguments</a>Const<div class="spec-rhs">(<a href="#Argument" data-name="Argument">Argument</a>Constlist)</div> </div> <div class="spec-production" id="Argument" data-source="spec/Section%202%20--%20Language.md#L412"> <a href="#Argument" data-name="Argument">Argument</a>Const<div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>:<a href="#Value" data-name="Value">Value</a>Const</div> </div> Fields are conceptually functions which return values, and occasionally accept arguments which alter their behavior. These arguments often map directly to function arguments within a GraphQL service’s implementation. In this example, we want to query a specific user (requested via the <code>id</code> argument) and their profile picture of a specific <code>size</code>: <pre id="example-1a865" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L421-L429"><a href="#example-1a865">Example № 10</a><code>{ user(id: 4) { id name profilePic(size: 100) } } </code></pre> Many arguments can exist for a given field: <pre id="example-34b2d" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L433-L441"><a href="#example-34b2d">Example № 11</a><code>{ user(id: 4) { id name profilePic(width: 100, height: 50) } } </code></pre> <section id="sec-Language.Arguments.Arguments-are-unordered" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L443"><a href="#sec-Language.Arguments.Arguments-are-unordered" title="link to this subsection">Arguments are unordered</a></h6> Arguments may be provided in any syntactic order and maintain identical semantic meaning. These two operations are semantically identical: <pre id="example-7eba7" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L450-L454"><a href="#example-7eba7">Example № 12</a><code>{ picture(width: 200, height: 100) } </code></pre> <pre id="example-c93a3" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L456-L460"><a href="#example-c93a3">Example № 13</a><code>{ picture(height: 100, width: 200) } </code></pre> </section> </section> <section id="sec-Field-Alias" secid="2.7"> <h2 data-source="spec/Section%202%20--%20Language.md#L463"><a href="#sec-Field-Alias">2.7</a>Field Alias</h2> <div class="spec-production" id="Alias" data-source="spec/Section%202%20--%20Language.md#L465"> <a href="#Alias" data-name="Alias">Alias</a><div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>:</div> </div> By default a field’s response key in the response object will use that field’s name. However, you can define a different response key by specifying an alias. In this example, we can fetch two profile pictures of different sizes and ensure the resulting response object will not have duplicate keys: <pre id="example-34435" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L473-L482"><a href="#example-34435">Example № 14</a><code>{ user(id: 4) { id name smallPic: profilePic(size: 64) bigPic: profilePic(size: 1024) } } </code></pre> which returns the result: <pre id="example-6e98a" class="spec-example" data-language="json" data-source="spec/Section%202%20--%20Language.md#L486-L495"><a href="#example-6e98a">Example № 15</a><code>{ "user": { "id": 4, "name": "Mark Zuckerberg", "smallPic": "https://cdn.site.io/pic-4-64.jpg", "bigPic": "https://cdn.site.io/pic-4-1024.jpg" } } </code></pre> The fields at the top level of an operation can also be given an alias: <pre id="example-27d2f" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L499-L506"><a href="#example-27d2f">Example № 16</a><code>{ zuck: user(id: 4) { id name } } </code></pre> which returns the result: <pre id="example-768a2" class="spec-example" data-language="json" data-source="spec/Section%202%20--%20Language.md#L510-L517"><a href="#example-768a2">Example № 17</a><code>{ "zuck": { "id": 4, "name": "Mark Zuckerberg" } } </code></pre> </section> <section id="sec-Language.Fragments" secid="2.8"> <h2 data-source="spec/Section%202%20--%20Language.md#L520"><a href="#sec-Language.Fragments">2.8</a>Fragments</h2> <div class="spec-production" id="FragmentSpread" data-source="spec/Section%202%20--%20Language.md#L522"> <a href="#FragmentSpread" data-name="FragmentSpread">FragmentSpread</a><div class="spec-rhs">...<a href="#FragmentName" data-name="FragmentName">FragmentName</a><a href="#Directives" data-name="Directives">Directives</a>opt</div> </div> <div class="spec-production" id="FragmentDefinition" data-source="spec/Section%202%20--%20Language.md#L524"> <a href="#FragmentDefinition" data-name="FragmentDefinition">FragmentDefinition</a><div class="spec-rhs">fragment<a href="#FragmentName" data-name="FragmentName">FragmentName</a><a href="#TypeCondition" data-name="TypeCondition">TypeCondition</a><a href="#Directives" data-name="Directives">Directives</a>opt<a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a></div> </div> <div class="spec-production" id="FragmentName" data-source="spec/Section%202%20--%20Language.md#L526"> <a href="#FragmentName" data-name="FragmentName">FragmentName</a><div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>on</div> </div> Fragments are the primary unit of composition in GraphQL. Fragments allow for the reuse of common repeated selections of fields, reducing duplicated text in the document. Inline Fragments can be used directly within a selection to condition upon a type condition when querying against an interface or union. For example, if we wanted to fetch some common information about mutual friends as well as friends of some user: <pre id="example-bcf38" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L538-L553"><a href="#example-bcf38">Example № 18</a><code>query noFragments { user(id: 4) { friends(first: 10) { id name profilePic(size: 50) } mutualFriends(first: 10) { id name profilePic(size: 50) } } } </code></pre> The repeated fields could be extracted into a fragment and composed by a parent fragment or operation. <pre id="example-72b4e" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L558-L575"><a href="#example-72b4e">Example № 19</a><code>query withFragments { user(id: 4) { friends(first: 10) { ...friendFields } mutualFriends(first: 10) { ...friendFields } } } fragment friendFields on User { id name profilePic(size: 50) } </code></pre> Fragments are consumed by using the spread operator (<code>...</code>). All fields selected by the fragment will be added to the field selection at the same level as the fragment invocation. This happens through multiple levels of fragment spreads. For example: <pre id="example-fb6c3" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L584-L605"><a href="#example-fb6c3">Example № 20</a><code>query withNestedFragments { user(id: 4) { friends(first: 10) { ...friendFields } mutualFriends(first: 10) { ...friendFields } } } fragment friendFields on User { id name ...standardProfilePic } fragment standardProfilePic on User { profilePic(size: 50) } </code></pre> The operations <code>noFragments</code>, <code>withFragments</code>, and <code>withNestedFragments</code> all produce the same response object. <section id="sec-Type-Conditions" secid="2.8.1"> <h3 data-source="spec/Section%202%20--%20Language.md#L611"><a href="#sec-Type-Conditions">2.8.1</a>Type Conditions</h3> <div class="spec-production" id="TypeCondition" data-source="spec/Section%202%20--%20Language.md#L613"> <a href="#TypeCondition" data-name="TypeCondition">TypeCondition</a><div class="spec-rhs">on<a href="#NamedType" data-name="NamedType">NamedType</a></div> </div> Fragments must specify the type they apply to. In this example, <code>friendFields</code> can be used in the context of querying a <code>User</code>. Fragments cannot be specified on any input value (scalar, enumeration, or input object). Fragments can be specified on object types, interfaces, and unions. Selections within fragments only return values when the concrete type of the object it is operating on matches the type of the fragment. For example in this operation using the Facebook data model: <pre id="example-80138" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L628-L648"><a href="#example-80138">Example № 21</a><code>query FragmentTyping { profiles(handles: ["zuck", "coca-cola"]) { handle ...userFragment ...pageFragment } } fragment userFragment on User { friends { count } } fragment pageFragment on Page { likers { count } } </code></pre> The <code>profiles</code> root field returns a list where each element could be a <code>Page</code> or a <code>User</code>. When the object in the <code>profiles</code> result is a <code>User</code>, <code>friends</code> will be present and <code>likers</code> will not. Conversely when the result is a <code>Page</code>, <code>likers</code> will be present and <code>friends</code> will not. <pre id="example-883a1" class="spec-example" data-language="json" data-source="spec/Section%202%20--%20Language.md#L655-L668"><a href="#example-883a1">Example № 22</a><code>{ "profiles": [ { "handle": "zuck", "friends": { "count": 1234 } }, { "handle": "coca-cola", "likers": { "count": 90234512 } } ] } </code></pre> </section> <section id="sec-Inline-Fragments" secid="2.8.2"> <h3 data-source="spec/Section%202%20--%20Language.md#L671"><a href="#sec-Inline-Fragments">2.8.2</a>Inline Fragments</h3> <div class="spec-production" id="InlineFragment" data-source="spec/Section%202%20--%20Language.md#L673"> <a href="#InlineFragment" data-name="InlineFragment">InlineFragment</a><div class="spec-rhs">...<a href="#TypeCondition" data-name="TypeCondition">TypeCondition</a>opt<a href="#Directives" data-name="Directives">Directives</a>opt<a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a></div> </div> Fragments can be defined inline within a selection set. This is done to conditionally include fields based on their runtime type. This feature of standard fragment inclusion was demonstrated in the <code>query FragmentTyping</code> example. We could accomplish the same thing using inline fragments. <pre id="example-10b94" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L680-L696"><a href="#example-10b94">Example № 23</a><code>query inlineFragmentTyping { profiles(handles: ["zuck", "coca-cola"]) { handle ... on User { friends { count } } ... on Page { likers { count } } } } </code></pre> Inline fragments may also be used to apply a directive to a group of fields. If the TypeCondition is omitted, an inline fragment is considered to be of the same type as the enclosing context. <pre id="example-77377" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L702-L714"><a href="#example-77377">Example № 24</a><code>query inlineFragmentNoType($expandedInfo: Boolean) { user(handle: "zuck") { id name ... @include(if: $expandedInfo) { firstName lastName birthday } } } </code></pre> </section> </section> <section id="sec-Input-Values" secid="2.9"> <h2 data-source="spec/Section%202%20--%20Language.md#L717"><a href="#sec-Input-Values">2.9</a>Input Values</h2> <div class="spec-production" id="Value" data-source="spec/Section%202%20--%20Language.md#L719-L728"> <a href="#Value" data-name="Value">Value</a>Const<div class="spec-rhs">Const<a href="#Variable" data-name="Variable">Variable</a></div> <div class="spec-rhs"><a href="#IntValue" data-name="IntValue">IntValue</a></div> <div class="spec-rhs"><a href="#FloatValue" data-name="FloatValue">FloatValue</a></div> <div class="spec-rhs"><a href="#StringValue" data-name="StringValue">StringValue</a></div> <div class="spec-rhs"><a href="#BooleanValue" data-name="BooleanValue">BooleanValue</a></div> <div class="spec-rhs"><a href="#NullValue" data-name="NullValue">NullValue</a></div> <div class="spec-rhs"><a href="#EnumValue" data-name="EnumValue">EnumValue</a></div> <div class="spec-rhs"><a href="#ListValue" data-name="ListValue">ListValue</a>Const</div> <div class="spec-rhs"><a href="#ObjectValue" data-name="ObjectValue">ObjectValue</a>Const</div> </div> Field and directive arguments accept input values of various literal primitives; input values can be scalars, enumeration values, lists, or input objects. If not defined as constant (for example, in <a href="#DefaultValue" data-name="DefaultValue">DefaultValue</a>), input values can be specified as a variable. List and inputs objects may also contain variables (unless defined to be constant). <section id="sec-Int-Value" secid="2.9.1"> <h3 data-source="spec/Section%202%20--%20Language.md#L737"><a href="#sec-Int-Value">2.9.1</a>Int Value</h3> <div class="spec-production d2" id="IntValue" data-source="spec/Section%202%20--%20Language.md#L739"> <a href="#IntValue" data-name="IntValue">IntValue</a><div class="spec-rhs"><a href="#IntegerPart" data-name="IntegerPart">IntegerPart</a><a href="#Digit" data-name="Digit">Digit</a>.<a href="#NameStart" data-name="NameStart">NameStart</a></div> </div> <div class="spec-production d2" id="IntegerPart" data-source="spec/Section%202%20--%20Language.md#L741-L743"> <a href="#IntegerPart" data-name="IntegerPart">IntegerPart</a><div class="spec-rhs"><a href="#NegativeSign" data-name="NegativeSign">NegativeSign</a>opt0</div> <div class="spec-rhs"><a href="#NegativeSign" data-name="NegativeSign">NegativeSign</a>opt<a href="#NonZeroDigit" data-name="NonZeroDigit">NonZeroDigit</a><a href="#Digit" data-name="Digit">Digit</a>listopt</div> </div> <div class="spec-production d2" id="NegativeSign" data-source="spec/Section%202%20--%20Language.md#L745"> <a href="#NegativeSign" data-name="NegativeSign">NegativeSign</a><div class="spec-rhs">-</div> </div> <div class="spec-production d2" id="NonZeroDigit" data-source="spec/Section%202%20--%20Language.md#L747"> <a href="#NonZeroDigit" data-name="NonZeroDigit">NonZeroDigit</a><div class="spec-rhs"><a href="#Digit" data-name="Digit">Digit</a>0</div> </div> An <a href="#IntValue" data-name="IntValue">IntValue</a> is specified without a decimal point or exponent but may be negative (ex. -123). It must not have any leading 0. An <a href="#IntValue" data-name="IntValue">IntValue</a> must not be followed by a <a href="#Digit" data-name="Digit">Digit</a>. In other words, an <a href="#IntValue" data-name="IntValue">IntValue</a> token is always the longest possible valid sequence. The source characters 12 cannot be interpreted as two tokens since 1 is followed by the <a href="#Digit" data-name="Digit">Digit</a> 2. This also means the source 00 is invalid since it can neither be interpreted as a single token nor two 0 tokens. An <a href="#IntValue" data-name="IntValue">IntValue</a> must not be followed by a . or <a href="#NameStart" data-name="NameStart">NameStart</a>. If either . or <a href="#ExponentIndicator" data-name="ExponentIndicator">ExponentIndicator</a> follows then the token must only be interpreted as a possible <a href="#FloatValue" data-name="FloatValue">FloatValue</a>. No other <a href="#NameStart" data-name="NameStart">NameStart</a> character can follow. For example the sequences <code>0x123</code> and <code>123L</code> have no valid lexical representations. </section> <section id="sec-Float-Value" secid="2.9.2"> <h3 data-source="spec/Section%202%20--%20Language.md#L764"><a href="#sec-Float-Value">2.9.2</a>Float Value</h3> <div class="spec-production d2" id="FloatValue" data-source="spec/Section%202%20--%20Language.md#L766-L769"> <a href="#FloatValue" data-name="FloatValue">FloatValue</a><div class="spec-rhs"><a href="#IntegerPart" data-name="IntegerPart">IntegerPart</a><a href="#FractionalPart" data-name="FractionalPart">FractionalPart</a><a href="#ExponentPart" data-name="ExponentPart">ExponentPart</a><a href="#Digit" data-name="Digit">Digit</a>.<a href="#NameStart" data-name="NameStart">NameStart</a></div> <div class="spec-rhs"><a href="#IntegerPart" data-name="IntegerPart">IntegerPart</a><a href="#FractionalPart" data-name="FractionalPart">FractionalPart</a><a href="#Digit" data-name="Digit">Digit</a>.<a href="#NameStart" data-name="NameStart">NameStart</a></div> <div class="spec-rhs"><a href="#IntegerPart" data-name="IntegerPart">IntegerPart</a><a href="#ExponentPart" data-name="ExponentPart">ExponentPart</a><a href="#Digit" data-name="Digit">Digit</a>.<a href="#NameStart" data-name="NameStart">NameStart</a></div> </div> <div class="spec-production d2" id="FractionalPart" data-source="spec/Section%202%20--%20Language.md#L771"> <a href="#FractionalPart" data-name="FractionalPart">FractionalPart</a><div class="spec-rhs">.<a href="#Digit" data-name="Digit">Digit</a>list</div> </div> <div class="spec-production d2" id="ExponentPart" data-source="spec/Section%202%20--%20Language.md#L773"> <a href="#ExponentPart" data-name="ExponentPart">ExponentPart</a><div class="spec-rhs"><a href="#ExponentIndicator" data-name="ExponentIndicator">ExponentIndicator</a><a href="#Sign" data-name="Sign">Sign</a>opt<a href="#Digit" data-name="Digit">Digit</a>list</div> </div> <div class="spec-production d2" id="ExponentIndicator" data-source="spec/Section%202%20--%20Language.md#L775"> <a href="#ExponentIndicator" data-name="ExponentIndicator">ExponentIndicator</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">e</td><td class="spec-rhs">E</td></tr> </table></div></div> </div> <div class="spec-production d2" id="Sign" data-source="spec/Section%202%20--%20Language.md#L777"> <a href="#Sign" data-name="Sign">Sign</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">+</td><td class="spec-rhs">-</td></tr> </table></div></div> </div> A <a href="#FloatValue" data-name="FloatValue">FloatValue</a> includes either a decimal point (ex. 1.0) or an exponent (ex. 1e50) or both (ex. 6.0221413e23) and may be negative. Like <a href="#IntValue" data-name="IntValue">IntValue</a>, it also must not have any leading 0. A <a href="#FloatValue" data-name="FloatValue">FloatValue</a> must not be followed by a <a href="#Digit" data-name="Digit">Digit</a>. In other words, a <a href="#FloatValue" data-name="FloatValue">FloatValue</a> token is always the longest possible valid sequence. The source characters 1.23 cannot be interpreted as two tokens since 1.2 is followed by the <a href="#Digit" data-name="Digit">Digit</a> 3. A <a href="#FloatValue" data-name="FloatValue">FloatValue</a> must not be followed by a .. For example, the sequence 1.23.4 cannot be interpreted as two tokens (1.2, 3.4). A <a href="#FloatValue" data-name="FloatValue">FloatValue</a> must not be followed by a <a href="#NameStart" data-name="NameStart">NameStart</a>. For example the sequence <code>0x1.2p3</code> has no valid lexical representation. <div id="note-dea61" class="spec-note" data-source="spec/Section%202%20--%20Language.md#L794-L796"> <a href="#note-dea61">Note</a> The numeric literals <a href="#IntValue" data-name="IntValue">IntValue</a> and <a href="#FloatValue" data-name="FloatValue">FloatValue</a> both restrict being immediately followed by a letter (or other <a href="#NameStart" data-name="NameStart">NameStart</a>) to reduce confusion or unexpected behavior since GraphQL only supports decimal numbers.</div> </section> <section id="sec-Boolean-Value" secid="2.9.3"> <h3 data-source="spec/Section%202%20--%20Language.md#L799"><a href="#sec-Boolean-Value">2.9.3</a>Boolean Value</h3> <div class="spec-production" id="BooleanValue" data-source="spec/Section%202%20--%20Language.md#L801"> <a href="#BooleanValue" data-name="BooleanValue">BooleanValue</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">true</td><td class="spec-rhs">false</td></tr> </table></div></div> </div> The two keywords <code>true</code> and <code>false</code> represent the two boolean values. </section> <section id="sec-String-Value" secid="2.9.4"> <h3 data-source="spec/Section%202%20--%20Language.md#L806"><a href="#sec-String-Value">2.9.4</a>String Value</h3> <div class="spec-production d2" id="StringValue" data-source="spec/Section%202%20--%20Language.md#L808-L811"> <a href="#StringValue" data-name="StringValue">StringValue</a><div class="spec-rhs">"""</div> <div class="spec-rhs">"<a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a>list"</div> <div class="spec-rhs">"""<a href="#BlockStringCharacter" data-name="BlockStringCharacter">BlockStringCharacter</a>listopt"""</div> </div> <div class="spec-production d2" id="StringCharacter" data-source="spec/Section%202%20--%20Language.md#L813-L816"> <a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a><div class="spec-rhs"><a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a>"\<a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a></div> <div class="spec-rhs">\u<a href="#EscapedUnicode" data-name="EscapedUnicode">EscapedUnicode</a></div> <div class="spec-rhs">\<a href="#EscapedCharacter" data-name="EscapedCharacter">EscapedCharacter</a></div> </div> <div class="spec-production d2" id="EscapedUnicode" data-source="spec/Section%202%20--%20Language.md#L818"> <a href="#EscapedUnicode" data-name="EscapedUnicode">EscapedUnicode</a><div class="spec-rhs">/[0-9A-Fa-f]{4}/</div> </div> <div class="spec-production d2" id="EscapedCharacter" data-source="spec/Section%202%20--%20Language.md#L820"> <a href="#EscapedCharacter" data-name="EscapedCharacter">EscapedCharacter</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">"</td><td class="spec-rhs">\</td><td class="spec-rhs">/</td><td class="spec-rhs">b</td><td class="spec-rhs">f</td><td class="spec-rhs">n</td><td class="spec-rhs">r</td><td class="spec-rhs">t</td></tr> </table></div></div> </div> <div class="spec-production d2" id="BlockStringCharacter" data-source="spec/Section%202%20--%20Language.md#L822-L824"> <a href="#BlockStringCharacter" data-name="BlockStringCharacter">BlockStringCharacter</a><div class="spec-rhs"><a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a>"""\"""</div> <div class="spec-rhs">\"""</div> </div> Strings are sequences of characters wrapped in quotation marks (U+0022). (ex. "Hello World"). White space and other otherwise-ignored characters are significant within a string value. The empty string "" must not be followed by another " otherwise it would be interpreted as the beginning of a block string. As an example, the source """""" can only be interpreted as a single empty block string and not three empty strings. Non-ASCII Unicode characters are allowed within single-quoted strings. Since <a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a> must not contain some ASCII control characters, escape sequences must be used to represent these characters. The \, " characters also must be escaped. All other escape sequences are optional. <section id="sec-String-Value.Block-Strings" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L840"><a href="#sec-String-Value.Block-Strings" title="link to this subsection">Block Strings</a></h6> Block strings are sequences of characters wrapped in triple-quotes (<code>"""</code>). White space, line terminators, quote, and backslash characters may all be used unescaped to enable verbatim text. Characters must all be valid <a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a>. Since block strings represent freeform text often used in indented positions, the string value semantics of a block string excludes uniform indentation and blank initial and trailing lines via <a href="#BlockStringValue()" data-name="BlockStringValue">BlockStringValue</a>(). For example, the following operation containing a block string: <pre id="example-fe73f" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L853-L863"><a href="#example-fe73f">Example № 25</a><code>mutation { sendEmail(message: """ Hello, World! Yours, GraphQL. """) } </code></pre> Is identical to the standard quoted string: <pre id="example-c6521" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L867-L871"><a href="#example-c6521">Example № 26</a><code>mutation { sendEmail(message: "Hello,\n World!\n\nYours,\n GraphQL.") } </code></pre> Since block string values strip leading and trailing empty lines, there is no single canonical printed block string for a given value. Because block strings typically represent freeform text, it is considered easier to read if they begin and end with an empty line. <pre id="example-8e831" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L878-L883"><a href="#example-8e831">Example № 27</a><code>""" This starts with and ends with an empty line, which makes it easier to read. """ </code></pre> <pre id="example-b874e" class="spec-counter-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L885-L888"><a href="#example-b874e">Counter Example № 28</a><code>"""This does not start with or end with any empty lines, which makes it a little harder to read.""" </code></pre> <div id="note-65771" class="spec-note" data-source="spec/Section%202%20--%20Language.md#L890-L892"> <a href="#note-65771">Note</a> If non-printable ASCII characters are needed in a string value, a standard quoted string with appropriate escape sequences must be used instead of a block string.</div> </section> <section id="sec-String-Value.Semantics" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L894"><a href="#sec-String-Value.Semantics" title="link to this subsection">Semantics</a></h6> <div class="spec-semantic d2" data-source="spec/Section%202%20--%20Language.md#L896-L898"> <a href="#StringValue" data-name="StringValue">StringValue</a><div class="spec-rhs">""</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L898">Return an empty sequence.</li> </ol> </div> <div class="spec-semantic d2" data-source="spec/Section%202%20--%20Language.md#L900-L902"> <a href="#StringValue" data-name="StringValue">StringValue</a><div class="spec-rhs">"<a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a>list"</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L902">Return the sequence of all <a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a> code points.</li> </ol> </div> <div class="spec-semantic d2" data-source="spec/Section%202%20--%20Language.md#L904-L906"> <a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a><div class="spec-rhs"><a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a>"\<a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a></div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L906">Return the code point <a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a>.</li> </ol> </div> <div class="spec-semantic d2" data-source="spec/Section%202%20--%20Language.md#L908-L912"> <a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a><div class="spec-rhs">\u<a href="#EscapedUnicode" data-name="EscapedUnicode">EscapedUnicode</a></div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L910-L911">Let <var data-name="value">value</var> be the 16-bit hexadecimal value represented by the sequence of hexadecimal digits within <a href="#EscapedUnicode" data-name="EscapedUnicode">EscapedUnicode</a>.</li> <li data-source="spec/Section%202%20--%20Language.md#L912">Return the code point <var data-name="value">value</var>.</li> </ol> </div> <div class="spec-semantic d2" data-source="spec/Section%202%20--%20Language.md#L914-L917"> <a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a><div class="spec-rhs">\<a href="#EscapedCharacter" data-name="EscapedCharacter">EscapedCharacter</a></div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L916-L917">Return the code point represented by <a href="#EscapedCharacter" data-name="EscapedCharacter">EscapedCharacter</a> according to the table below.</li> </ol> </div> <table> <thead> <tr data-source="spec/Section%202%20--%20Language.md#L919"> <th>Escaped Character</th> <th>Code Point</th> <th>Character Name</th> </tr> </thead> <tbody> <tr data-source="spec/Section%202%20--%20Language.md#L921"> <td>"</td> <td>U+0022</td> <td>double quote</td> </tr> <tr data-source="spec/Section%202%20--%20Language.md#L922"> <td>\</td> <td>U+005C</td> <td>reverse solidus (back slash)</td> </tr> <tr data-source="spec/Section%202%20--%20Language.md#L923"> <td>/</td> <td>U+002F</td> <td>solidus (forward slash)</td> </tr> <tr data-source="spec/Section%202%20--%20Language.md#L924"> <td>b</td> <td>U+0008</td> <td>backspace</td> </tr> <tr data-source="spec/Section%202%20--%20Language.md#L925"> <td>f</td> <td>U+000C</td> <td>form feed</td> </tr> <tr data-source="spec/Section%202%20--%20Language.md#L926"> <td>n</td> <td>U+000A</td> <td>line feed (new line)</td> </tr> <tr data-source="spec/Section%202%20--%20Language.md#L927"> <td>r</td> <td>U+000D</td> <td>carriage return</td> </tr> <tr data-source="spec/Section%202%20--%20Language.md#L928"> <td>t</td> <td>U+0009</td> <td>horizontal tab</td> </tr> </tbody> </table> <div class="spec-semantic d2" data-source="spec/Section%202%20--%20Language.md#L930-L935"> <a href="#StringValue" data-name="StringValue">StringValue</a><div class="spec-rhs">"""<a href="#BlockStringCharacter" data-name="BlockStringCharacter">BlockStringCharacter</a>listopt"""</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L932-L934">Let <var data-name="rawValue">rawValue</var> be the Unicode character sequence of all <a href="#BlockStringCharacter" data-name="BlockStringCharacter">BlockStringCharacter</a> Unicode character values (which may be an empty sequence).</li> <li data-source="spec/Section%202%20--%20Language.md#L935">Return the result of <a href="#BlockStringValue()" data-name="BlockStringValue">BlockStringValue</a>(<var data-name="rawValue">rawValue</var>).</li> </ol> </div> <div class="spec-semantic d2" data-source="spec/Section%202%20--%20Language.md#L937-L939"> <a href="#BlockStringCharacter" data-name="BlockStringCharacter">BlockStringCharacter</a><div class="spec-rhs"><a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a>"""\"""</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L939">Return the character value of <a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a>.</li> </ol> </div> <div class="spec-semantic d2" data-source="spec/Section%202%20--%20Language.md#L941-L943"> <a href="#BlockStringCharacter" data-name="BlockStringCharacter">BlockStringCharacter</a><div class="spec-rhs">\"""</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L943">Return the character sequence <code>"""</code>.</li> </ol> </div> <div class="spec-algo" id="BlockStringValue()" data-source="spec/Section%202%20--%20Language.md#L945-L972"> <a href="#BlockStringValue()" data-name="BlockStringValue">BlockStringValue</a>(<var data-name="rawValue">rawValue</var>)<ol> <li data-source="spec/Section%202%20--%20Language.md#L947">Let <var data-name="lines">lines</var> be the result of splitting <var data-name="rawValue">rawValue</var> by <a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a>.</li> <li data-source="spec/Section%202%20--%20Language.md#L948">Let <var data-name="commonIndent">commonIndent</var> be null.</li> <li data-source="spec/Section%202%20--%20Language.md#L949-L956">For each <var data-name="line">line</var> in <var data-name="lines">lines</var>:<ol> <li data-source="spec/Section%202%20--%20Language.md#L950">If <var data-name="line">line</var> is the first item in <var data-name="lines">lines</var>, continue to the next line.</li> <li data-source="spec/Section%202%20--%20Language.md#L951">Let <var data-name="length">length</var> be the number of characters in <var data-name="line">line</var>.</li> <li data-source="spec/Section%202%20--%20Language.md#L952-L953">Let <var data-name="indent">indent</var> be the number of leading consecutive <a href="#WhiteSpace" data-name="WhiteSpace">WhiteSpace</a> characters in <var data-name="line">line</var>.</li> <li data-source="spec/Section%202%20--%20Language.md#L954-L956">If <var data-name="indent">indent</var> is less than <var data-name="length">length</var>:<ol> <li data-source="spec/Section%202%20--%20Language.md#L955-L956">If <var data-name="commonIndent">commonIndent</var> is null or <var data-name="indent">indent</var> is less than <var data-name="commonIndent">commonIndent</var>:<ol> <li data-source="spec/Section%202%20--%20Language.md#L956">Let <var data-name="commonIndent">commonIndent</var> be <var data-name="indent">indent</var>.</li> </ol> </li> </ol> </li> </ol> </li> <li data-source="spec/Section%202%20--%20Language.md#L957-L960">If <var data-name="commonIndent">commonIndent</var> is not null:<ol> <li data-source="spec/Section%202%20--%20Language.md#L958-L960">For each <var data-name="line">line</var> in <var data-name="lines">lines</var>:<ol> <li data-source="spec/Section%202%20--%20Language.md#L959">If <var data-name="line">line</var> is the first item in <var data-name="lines">lines</var>, continue to the next line.</li> <li data-source="spec/Section%202%20--%20Language.md#L960">Remove <var data-name="commonIndent">commonIndent</var> characters from the beginning of <var data-name="line">line</var>.</li> </ol> </li> </ol> </li> <li data-source="spec/Section%202%20--%20Language.md#L961-L962">While the first item <var data-name="line">line</var> in <var data-name="lines">lines</var> contains only <a href="#WhiteSpace" data-name="WhiteSpace">WhiteSpace</a>:<ol> <li data-source="spec/Section%202%20--%20Language.md#L962">Remove the first item from <var data-name="lines">lines</var>.</li> </ol> </li> <li data-source="spec/Section%202%20--%20Language.md#L963-L964">While the last item <var data-name="line">line</var> in <var data-name="lines">lines</var> contains only <a href="#WhiteSpace" data-name="WhiteSpace">WhiteSpace</a>:<ol> <li data-source="spec/Section%202%20--%20Language.md#L964">Remove the last item from <var data-name="lines">lines</var>.</li> </ol> </li> <li data-source="spec/Section%202%20--%20Language.md#L965">Let <var data-name="formatted">formatted</var> be the empty character sequence.</li> <li data-source="spec/Section%202%20--%20Language.md#L966-L971">For each <var data-name="line">line</var> in <var data-name="lines">lines</var>:<ol> <li data-source="spec/Section%202%20--%20Language.md#L967-L968">If <var data-name="line">line</var> is the first item in <var data-name="lines">lines</var>:<ol> <li data-source="spec/Section%202%20--%20Language.md#L968">Append <var data-name="formatted">formatted</var> with <var data-name="line">line</var>.</li> </ol> </li> <li data-source="spec/Section%202%20--%20Language.md#L969-L971">Otherwise:<ol> <li data-source="spec/Section%202%20--%20Language.md#L970">Append <var data-name="formatted">formatted</var> with a line feed character (U+000A).</li> <li data-source="spec/Section%202%20--%20Language.md#L971">Append <var data-name="formatted">formatted</var> with <var data-name="line">line</var>.</li> </ol> </li> </ol> </li> <li data-source="spec/Section%202%20--%20Language.md#L972">Return <var data-name="formatted">formatted</var>.</li> </ol> </div> </section> </section> <section id="sec-Null-Value" secid="2.9.5"> <h3 data-source="spec/Section%202%20--%20Language.md#L975"><a href="#sec-Null-Value">2.9.5</a>Null Value</h3> <div class="spec-production" id="NullValue" data-source="spec/Section%202%20--%20Language.md#L977"> <a href="#NullValue" data-name="NullValue">NullValue</a><div class="spec-rhs">null</div> </div> Null values are represented as the keyword null. GraphQL has two semantically different ways to represent the lack of a value: <ul> <li data-source="spec/Section%202%20--%20Language.md#L983">Explicitly providing the literal value: null.</li> <li data-source="spec/Section%202%20--%20Language.md#L984">Implicitly not providing a value at all.</li> </ul> For example, these two field calls are similar, but are not identical: <pre id="example-1c7eb" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L988-L993"><a href="#example-1c7eb">Example № 29</a><code>{ field(arg: null) field } </code></pre> The first has explicitly provided null to the argument “arg”, while the second has implicitly not provided a value to the argument “arg”. These two forms may be interpreted differently. For example, a mutation representing deleting a field vs not altering a field, respectively. Neither form may be used for an input expecting a Non-Null type. <div id="note-eab9b" class="spec-note" data-source="spec/Section%202%20--%20Language.md#L1001-L1003"> <a href="#note-eab9b">Note</a> The same two methods of representing the lack of a value are possible via variables by either providing the variable value as null or not providing a variable value at all.</div> </section> <section id="sec-Enum-Value" secid="2.9.6"> <h3 data-source="spec/Section%202%20--%20Language.md#L1006"><a href="#sec-Enum-Value">2.9.6</a>Enum Value</h3> <div class="spec-production" id="EnumValue" data-source="spec/Section%202%20--%20Language.md#L1008"> <a href="#EnumValue" data-name="EnumValue">EnumValue</a><div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>truefalsenull</div> </div> Enum values are represented as unquoted names (ex. <code>MOBILE_WEB</code>). It is recommended that Enum values be “all caps”. Enum values are only used in contexts where the precise enumeration type is known. Therefore it’s not necessary to supply an enumeration type name in the literal. </section> <section id="sec-List-Value" secid="2.9.7"> <h3 data-source="spec/Section%202%20--%20Language.md#L1016"><a href="#sec-List-Value">2.9.7</a>List Value</h3> <div class="spec-production" id="ListValue" data-source="spec/Section%202%20--%20Language.md#L1018-L1020"> <a href="#ListValue" data-name="ListValue">ListValue</a>Const<div class="spec-rhs">[]</div> <div class="spec-rhs">[<a href="#Value" data-name="Value">Value</a>Constlist]</div> </div> Lists are ordered sequences of values wrapped in square-brackets <code>[ ]</code>. The values of a List literal may be any value literal or variable (ex. <code>[1, 2, 3]</code>). Commas are optional throughout GraphQL so trailing commas are allowed and repeated commas do not represent missing values. <section id="sec-List-Value.Semantics" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L1028"><a href="#sec-List-Value.Semantics" title="link to this subsection">Semantics</a></h6> <div class="spec-semantic" data-source="spec/Section%202%20--%20Language.md#L1030-L1032"> <a href="#ListValue" data-name="ListValue">ListValue</a><div class="spec-rhs">[]</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L1032">Return a new empty list value.</li> </ol> </div> <div class="spec-semantic" data-source="spec/Section%202%20--%20Language.md#L1034-L1040"> <a href="#ListValue" data-name="ListValue">ListValue</a><div class="spec-rhs">[<a href="#Value" data-name="Value">Value</a>list]</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L1036">Let <var data-name="inputList">inputList</var> be a new empty list value.</li> <li data-source="spec/Section%202%20--%20Language.md#L1037-L1039">For each <a href="#Value" data-name="Value">Value</a>list<ol> <li data-source="spec/Section%202%20--%20Language.md#L1038">Let <var data-name="value">value</var> be the result of evaluating <a href="#Value" data-name="Value">Value</a>.</li> <li data-source="spec/Section%202%20--%20Language.md#L1039">Append <var data-name="value">value</var> to <var data-name="inputList">inputList</var>.</li> </ol> </li> <li data-source="spec/Section%202%20--%20Language.md#L1040">Return <var data-name="inputList">inputList</var></li> </ol> </div> </section> </section> <section id="sec-Input-Object-Values" secid="2.9.8"> <h3 data-source="spec/Section%202%20--%20Language.md#L1043"><a href="#sec-Input-Object-Values">2.9.8</a>Input Object Values</h3> <div class="spec-production" id="ObjectValue" data-source="spec/Section%202%20--%20Language.md#L1045-L1047"> <a href="#ObjectValue" data-name="ObjectValue">ObjectValue</a>Const<div class="spec-rhs">{}</div> <div class="spec-rhs">{<a href="#ObjectField" data-name="ObjectField">ObjectField</a>Constlist}</div> </div> <div class="spec-production" id="ObjectField" data-source="spec/Section%202%20--%20Language.md#L1049"> <a href="#ObjectField" data-name="ObjectField">ObjectField</a>Const<div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>:<a href="#Value" data-name="Value">Value</a>Const</div> </div> Input object literal values are unordered lists of keyed input values wrapped in curly-braces <code>{ }</code>. The values of an object literal may be any input value literal or variable (ex. <code>{ name: "Hello world", score: 1.0 }</code>). We refer to literal representation of input objects as “object literals.” <section id="sec-Input-Object-Values.Input-object-fields-are-unordered" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L1056"><a href="#sec-Input-Object-Values.Input-object-fields-are-unordered" title="link to this subsection">Input object fields are unordered</a></h6> Input object fields may be provided in any syntactic order and maintain identical semantic meaning. These two operations are semantically identical: <pre id="example-09646" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L1063-L1067"><a href="#example-09646">Example № 30</a><code>{ nearestThing(location: { lon: 12.43, lat: -53.211 }) } </code></pre> <pre id="example-6ebee" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L1069-L1073"><a href="#example-6ebee">Example № 31</a><code>{ nearestThing(location: { lat: -53.211, lon: 12.43 }) } </code></pre> </section> <section id="sec-Input-Object-Values.Semantics" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L1075"><a href="#sec-Input-Object-Values.Semantics" title="link to this subsection">Semantics</a></h6> <div class="spec-semantic" data-source="spec/Section%202%20--%20Language.md#L1077-L1079"> <a href="#ObjectValue" data-name="ObjectValue">ObjectValue</a><div class="spec-rhs">{}</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L1079">Return a new input object value with no fields.</li> </ol> </div> <div class="spec-semantic" data-source="spec/Section%202%20--%20Language.md#L1081-L1088"> <a href="#ObjectValue" data-name="ObjectValue">ObjectValue</a><div class="spec-rhs">{<a href="#ObjectField" data-name="ObjectField">ObjectField</a>list}</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L1083">Let <var data-name="inputObject">inputObject</var> be a new input object value with no fields.</li> <li data-source="spec/Section%202%20--%20Language.md#L1084-L1087">For each <var data-name="field">field</var> in <a href="#ObjectField" data-name="ObjectField">ObjectField</a>list<ol> <li data-source="spec/Section%202%20--%20Language.md#L1085">Let <var data-name="name">name</var> be <a href="#Name" data-name="Name">Name</a> in <var data-name="field">field</var>.</li> <li data-source="spec/Section%202%20--%20Language.md#L1086">Let <var data-name="value">value</var> be the result of evaluating <a href="#Value" data-name="Value">Value</a> in <var data-name="field">field</var>.</li> <li data-source="spec/Section%202%20--%20Language.md#L1087">Add a field to <var data-name="inputObject">inputObject</var> of name <var data-name="name">name</var> containing value <var data-name="value">value</var>.</li> </ol> </li> <li data-source="spec/Section%202%20--%20Language.md#L1088">Return <var data-name="inputObject">inputObject</var></li> </ol> </div> </section> </section> </section> <section id="sec-Language.Variables" secid="2.10"> <h2 data-source="spec/Section%202%20--%20Language.md#L1091"><a href="#sec-Language.Variables">2.10</a>Variables</h2> <div class="spec-production" id="Variable" data-source="spec/Section%202%20--%20Language.md#L1093"> <a href="#Variable" data-name="Variable">Variable</a><div class="spec-rhs">$<a href="#Name" data-name="Name">Name</a></div> </div> <div class="spec-production" id="VariableDefinitions" data-source="spec/Section%202%20--%20Language.md#L1095"> <a href="#VariableDefinitions" data-name="VariableDefinitions">VariableDefinitions</a><div class="spec-rhs">(<a href="#VariableDefinition" data-name="VariableDefinition">VariableDefinition</a>list)</div> </div> <div class="spec-production" id="VariableDefinition" data-source="spec/Section%202%20--%20Language.md#L1097"> <a href="#VariableDefinition" data-name="VariableDefinition">VariableDefinition</a><div class="spec-rhs"><a href="#Variable" data-name="Variable">Variable</a>:<a href="#Type" data-name="Type">Type</a><a href="#DefaultValue" data-name="DefaultValue">DefaultValue</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt</div> </div> <div class="spec-production" id="DefaultValue" data-source="spec/Section%202%20--%20Language.md#L1099"> <a href="#DefaultValue" data-name="DefaultValue">DefaultValue</a><div class="spec-rhs">=<a href="#Value" data-name="Value">Value</a>Const</div> </div> A GraphQL operation can be parameterized with variables, maximizing reuse, and avoiding costly string building in clients at runtime. If not defined as constant (for example, in <a href="#DefaultValue" data-name="DefaultValue">DefaultValue</a>), a <a href="#Variable" data-name="Variable">Variable</a> can be supplied for an input value. Variables must be defined at the top of an operation and are in scope throughout the execution of that operation. Values for those variables are provided to a GraphQL service as part of a request so they may be substituted in during execution. In this example, we want to fetch a profile picture size based on the size of a particular device: <pre id="example-7f690" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L1115-L1123"><a href="#example-7f690">Example № 32</a><code>query getZuckProfile($devicePicSize: Int) { user(id: 4) { id name profilePic(size: $devicePicSize) } } </code></pre> If providing JSON for the variables’ values, we could request a <code>profilePic</code> of size <code>60</code>: <pre id="example-98958" class="spec-example" data-language="json" data-source="spec/Section%202%20--%20Language.md#L1128-L1132"><a href="#example-98958">Example № 33</a><code>{ "devicePicSize": 60 } </code></pre> <section id="sec-Language.Variables.Variable-use-within-Fragments" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L1134"><a href="#sec-Language.Variables.Variable-use-within-Fragments" title="link to this subsection">Variable use within Fragments</a></h6> Variables can be used within fragments. Variables have global scope with a given operation, so a variable used within a fragment must be declared in any top-level operation that transitively consumes that fragment. If a variable is referenced in a fragment and is included by an operation that does not define that variable, that operation is invalid (see <a href="#sec-All-Variable-Uses-Defined">All Variable Uses Defined</a>). </section> </section> <section id="sec-Type-References" secid="2.11"> <h2 data-source="spec/Section%202%20--%20Language.md#L1142"><a href="#sec-Type-References">2.11</a>Type References</h2> <div class="spec-production" id="Type" data-source="spec/Section%202%20--%20Language.md#L1144-L1147"> <a href="#Type" data-name="Type">Type</a><div class="spec-rhs"><a href="#NamedType" data-name="NamedType">NamedType</a></div> <div class="spec-rhs"><a href="#ListType" data-name="ListType">ListType</a></div> <div class="spec-rhs"><a href="#NonNullType" data-name="NonNullType">NonNullType</a></div> </div> <div class="spec-production" id="NamedType" data-source="spec/Section%202%20--%20Language.md#L1149"> <a href="#NamedType" data-name="NamedType">NamedType</a><div class="spec-rhs"><a href="#Name" data-name="Name">Name</a></div> </div> <div class="spec-production" id="ListType" data-source="spec/Section%202%20--%20Language.md#L1151"> <a href="#ListType" data-name="ListType">ListType</a><div class="spec-rhs">[<a href="#Type" data-name="Type">Type</a>]</div> </div> <div class="spec-production" id="NonNullType" data-source="spec/Section%202%20--%20Language.md#L1153-L1155"> <a href="#NonNullType" data-name="NonNullType">NonNullType</a><div class="spec-rhs"><a href="#NamedType" data-name="NamedType">NamedType</a>!</div> <div class="spec-rhs"><a href="#ListType" data-name="ListType">ListType</a>!</div> </div> GraphQL describes the types of data expected by arguments and variables. Input types may be lists of another input type, or a non-null variant of any other input type. <section id="sec-Type-References.Semantics" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L1161"><a href="#sec-Type-References.Semantics" title="link to this subsection">Semantics</a></h6> <div class="spec-semantic" data-source="spec/Section%202%20--%20Language.md#L1163-L1168"> <a href="#Type" data-name="Type">Type</a><div class="spec-rhs"><a href="#Name" data-name="Name">Name</a></div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L1165">Let <var data-name="name">name</var> be the string value of <a href="#Name" data-name="Name">Name</a></li> <li data-source="spec/Section%202%20--%20Language.md#L1166">Let <var data-name="type">type</var> be the type defined in the Schema named <var data-name="name">name</var></li> <li data-source="spec/Section%202%20--%20Language.md#L1167"><var data-name="type">type</var> must not be null</li> <li data-source="spec/Section%202%20--%20Language.md#L1168">Return <var data-name="type">type</var></li> </ol> </div> <div class="spec-semantic" data-source="spec/Section%202%20--%20Language.md#L1170-L1174"> <a href="#Type" data-name="Type">Type</a><div class="spec-rhs">[<a href="#Type" data-name="Type">Type</a>]</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L1172">Let <var data-name="itemType">itemType</var> be the result of evaluating <a href="#Type" data-name="Type">Type</a></li> <li data-source="spec/Section%202%20--%20Language.md#L1173">Let <var data-name="type">type</var> be a List type where <var data-name="itemType">itemType</var> is the contained type.</li> <li data-source="spec/Section%202%20--%20Language.md#L1174">Return <var data-name="type">type</var></li> </ol> </div> <div class="spec-semantic" data-source="spec/Section%202%20--%20Language.md#L1176-L1180"> <a href="#Type" data-name="Type">Type</a><div class="spec-rhs"><a href="#Type" data-name="Type">Type</a>!</div> <ol> <li data-source="spec/Section%202%20--%20Language.md#L1178">Let <var data-name="nullableType">nullableType</var> be the result of evaluating <a href="#Type" data-name="Type">Type</a></li> <li data-source="spec/Section%202%20--%20Language.md#L1179">Let <var data-name="type">type</var> be a Non-Null type where <var data-name="nullableType">nullableType</var> is the contained type.</li> <li data-source="spec/Section%202%20--%20Language.md#L1180">Return <var data-name="type">type</var></li> </ol> </div> </section> </section> <section id="sec-Language.Directives" secid="2.12"> <h2 data-source="spec/Section%202%20--%20Language.md#L1183"><a href="#sec-Language.Directives">2.12</a>Directives</h2> <div class="spec-production" id="Directives" data-source="spec/Section%202%20--%20Language.md#L1185"> <a href="#Directives" data-name="Directives">Directives</a>Const<div class="spec-rhs"><a href="#Directive" data-name="Directive">Directive</a>Constlist</div> </div> <div class="spec-production" id="Directive" data-source="spec/Section%202%20--%20Language.md#L1187"> <a href="#Directive" data-name="Directive">Directive</a>Const<div class="spec-rhs">@<a href="#Name" data-name="Name">Name</a><a href="#Arguments" data-name="Arguments">Arguments</a>Constopt</div> </div> Directives provide a way to describe alternate runtime execution and type validation behavior in a GraphQL document. In some cases, you need to provide options to alter GraphQL’s execution behavior in ways field arguments will not suffice, such as conditionally including or skipping a field. Directives provide this by describing additional information to the executor. Directives have a name along with a list of arguments which may accept values of any input type. Directives can be used to describe additional information for types, fields, fragments and operations. As future versions of GraphQL adopt new configurable execution capabilities, they may be exposed via directives. GraphQL services and tools may also provide any additional <a href="#custom-directive" data-name="custom-directive">custom directive</a> beyond those described here. <section id="sec-Language.Directives.Directive-order-is-significant" class="subsec"> <h6 data-source="spec/Section%202%20--%20Language.md#L1206"><a href="#sec-Language.Directives.Directive-order-is-significant" title="link to this subsection">Directive order is significant</a></h6> Directives may be provided in a specific syntactic order which may have semantic interpretation. These two type definitions may have different semantic meaning: <pre id="example-2a4f9" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L1212-L1218"><a href="#example-2a4f9">Example № 34</a><code>type Person @addExternalFields(source: "profiles") @excludeField(name: "photo") { name: String } </code></pre> <pre id="example-c1f24" class="spec-example" data-language="graphql" data-source="spec/Section%202%20--%20Language.md#L1220-L1226"><a href="#example-c1f24">Example № 35</a><code>type Person @excludeField(name: "photo") @addExternalFields(source: "profiles") { name: String } </code></pre> </section> </section> </section> <section id="sec-Type-System" secid="3"> <h1 data-source="spec/Section%203%20--%20Type%20System.md#L1"><a href="#sec-Type-System">3</a>Type System</h1> The GraphQL Type system describes the capabilities of a GraphQL service and is used to determine if a requested operation is valid, to guarantee the type of response results, and describes the input types of variables to determine if values provided at request time are valid. <div class="spec-production" id="TypeSystemDocument" data-source="spec/Section%203%20--%20Type%20System.md#L8"> <a href="#TypeSystemDocument" data-name="TypeSystemDocument">TypeSystemDocument</a><div class="spec-rhs"><a href="#TypeSystemDefinition" data-name="TypeSystemDefinition">TypeSystemDefinition</a>list</div> </div> <div class="spec-production" id="TypeSystemDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L10-L13"> <a href="#TypeSystemDefinition" data-name="TypeSystemDefinition">TypeSystemDefinition</a><div class="spec-rhs"><a href="#SchemaDefinition" data-name="SchemaDefinition">SchemaDefinition</a></div> <div class="spec-rhs"><a href="#TypeDefinition" data-name="TypeDefinition">TypeDefinition</a></div> <div class="spec-rhs"><a href="#DirectiveDefinition" data-name="DirectiveDefinition">DirectiveDefinition</a></div> </div> The GraphQL language includes an <a href="https://en.wikipedia.org/wiki/Interface_description_language">IDL</a> used to describe a GraphQL service’s type system. Tools may use this definition language to provide utilities such as client code generation or service boot-strapping. GraphQL tools or services which only seek to execute GraphQL requests and not construct a new GraphQL schema may choose not to allow <a href="#TypeSystemDefinition" data-name="TypeSystemDefinition">TypeSystemDefinition</a>. Tools which only seek to produce schema and not execute requests may choose to only allow <a href="#TypeSystemDocument" data-name="TypeSystemDocument">TypeSystemDocument</a> and not allow <a href="#ExecutableDefinition" data-name="ExecutableDefinition">ExecutableDefinition</a> or <a href="#TypeSystemExtension" data-name="TypeSystemExtension">TypeSystemExtension</a> but should provide a descriptive error if present. <div id="note-d5e8e" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L26-L27"> <a href="#note-d5e8e">Note</a> The type system definition language is used throughout the remainder of this specification document when illustrating example type systems.</div> <section id="sec-Type-System-Extensions" secid="3.1"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L30"><a href="#sec-Type-System-Extensions">3.1</a>Type System Extensions</h2> <div class="spec-production" id="TypeSystemExtensionDocument" data-source="spec/Section%203%20--%20Type%20System.md#L32"> <a href="#TypeSystemExtensionDocument" data-name="TypeSystemExtensionDocument">TypeSystemExtensionDocument</a><div class="spec-rhs"><a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a>list</div> </div> <div class="spec-production" id="TypeSystemDefinitionOrExtension" data-source="spec/Section%203%20--%20Type%20System.md#L34-L36"> <a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a><div class="spec-rhs"><a href="#TypeSystemDefinition" data-name="TypeSystemDefinition">TypeSystemDefinition</a></div> <div class="spec-rhs"><a href="#TypeSystemExtension" data-name="TypeSystemExtension">TypeSystemExtension</a></div> </div> <div class="spec-production" id="TypeSystemExtension" data-source="spec/Section%203%20--%20Type%20System.md#L38-L40"> <a href="#TypeSystemExtension" data-name="TypeSystemExtension">TypeSystemExtension</a><div class="spec-rhs"><a href="#SchemaExtension" data-name="SchemaExtension">SchemaExtension</a></div> <div class="spec-rhs"><a href="#TypeExtension" data-name="TypeExtension">TypeExtension</a></div> </div> Type system extensions are used to represent a GraphQL type system which has been extended from some original type system. For example, this might be used by a local service to represent data a GraphQL client only accesses locally, or by a GraphQL service which is itself an extension of another GraphQL service. Tools which only seek to produce and extend schema and not execute requests may choose to only allow <a href="#TypeSystemExtensionDocument" data-name="TypeSystemExtensionDocument">TypeSystemExtensionDocument</a> and not allow <a href="#ExecutableDefinition" data-name="ExecutableDefinition">ExecutableDefinition</a> but should provide a descriptive error if present. </section> <section id="sec-Descriptions" secid="3.2"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L52"><a href="#sec-Descriptions">3.2</a>Descriptions</h2> <div class="spec-production" id="Description" data-source="spec/Section%203%20--%20Type%20System.md#L54"> <a href="#Description" data-name="Description">Description</a><div class="spec-rhs"><a href="#StringValue" data-name="StringValue">StringValue</a></div> </div> Documentation is a first-class feature of GraphQL type systems. To ensure the documentation of a GraphQL service remains consistent with its capabilities, descriptions of GraphQL definitions are provided alongside their definitions and made available via introspection. To allow GraphQL service designers to easily publish documentation alongside the capabilities of a GraphQL service, GraphQL descriptions are defined using the Markdown syntax (as specified by <a href="https://commonmark.org/">CommonMark</a>). In the type system definition language, these description strings (often BlockString) occur immediately before the definition they describe. GraphQL schema and all other definitions (e.g. types, fields, arguments, etc.) which can be described should provide a <a href="#Description" data-name="Description">Description</a> unless they are considered self descriptive. As an example, this simple GraphQL schema is well described: <pre id="example-916f4" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L73-L113"><a href="#example-916f4">Example № 36</a><code>""" A simple GraphQL schema which is well described. """ schema { query: Query } """ Root type for all your query operations """ type Query { """ Translates a string from a given language into a different language. """ translate( "The original language that `text` is provided in." fromLanguage: Language "The translated language to be returned." toLanguage: Language "The text to be translated." text: String ): String } """ The set of languages supported by `translate`. """ enum Language { "English" EN "French" FR "Chinese" CH } </code></pre> </section> <section id="sec-Schema" secid="3.3"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L116"><a href="#sec-Schema">3.3</a>Schema</h2> <div class="spec-production" id="SchemaDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L118"> <a href="#SchemaDefinition" data-name="SchemaDefinition">SchemaDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optschema<a href="#Directives" data-name="Directives">Directives</a>Constopt{<a href="#RootOperationTypeDefinition" data-name="RootOperationTypeDefinition">RootOperationTypeDefinition</a>list}</div> </div> <div class="spec-production" id="RootOperationTypeDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L120"> <a href="#RootOperationTypeDefinition" data-name="RootOperationTypeDefinition">RootOperationTypeDefinition</a><div class="spec-rhs"><a href="#OperationType" data-name="OperationType">OperationType</a>:<a href="#NamedType" data-name="NamedType">NamedType</a></div> </div> A GraphQL service’s collective type system capabilities are referred to as that service’s “schema”. A schema is defined in terms of the types and directives it supports as well as the root operation types for each kind of operation: query, mutation, and subscription; this determines the place in the type system where those operations begin. A GraphQL schema must itself be internally valid. This section describes the rules for this validation process where relevant. All types within a GraphQL schema must have unique names. No two provided types may have the same name. No provided type may have a name which conflicts with any built in types (including Scalar and Introspection types). All directives within a GraphQL schema must have unique names. All types and directives defined within a schema must not have a name which begins with "__" (two underscores), as this is used exclusively by GraphQL’s introspection system. <section id="sec-Root-Operation-Types" secid="3.3.1"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L141"><a href="#sec-Root-Operation-Types">3.3.1</a>Root Operation Types</h3> A schema defines the initial root operation type for each kind of operation it supports: query, mutation, and subscription; this determines the place in the type system where those operations begin. The query root operation type must be provided and must be an Object type. The mutation root operation type is optional; if it is not provided, the service does not support mutations. If it is provided, it must be an Object type. Similarly, the subscription root operation type is also optional; if it is not provided, the service does not support subscriptions. If it is provided, it must be an Object type. The query, mutation, and subscription root types must all be different types if provided. The fields on the query root operation type indicate what fields are available at the top level of a GraphQL query operation. For example, this example operation: <pre id="example-081b4" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L165-L169"><a href="#example-081b4">Example № 37</a><code>query { myName } </code></pre> is only valid when the query root operation type has a field named “myName”: <pre id="example-50137" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L173-L177"><a href="#example-50137">Example № 38</a><code>type Query { myName: String } </code></pre> Similarly, the following mutation is only valid if the mutation root operation type has a field named “setName”. <pre id="example-d1ed8" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L182-L188"><a href="#example-d1ed8">Example № 39</a><code>mutation { setName(name: "Zuck") { newName } } </code></pre> When using the type system definition language, a document must include at most one schema definition. In this example, a GraphQL schema is defined with both query and mutation root operation types: <pre id="example-e2969" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L196-L209"><a href="#example-e2969">Example № 40</a><code>schema { query: MyQueryRootType mutation: MyMutationRootType } type MyQueryRootType { someField: String } type MyMutationRootType { setSomeField(to: String): String } </code></pre> <section id="sec-Root-Operation-Types.Default-Root-Operation-Type-Names" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L211"><a href="#sec-Root-Operation-Types.Default-Root-Operation-Type-Names" title="link to this subsection">Default Root Operation Type Names</a></h6> While any type can be the root operation type for a GraphQL operation, the type system definition language can omit the schema definition when the query, mutation, and subscription root types are named "Query", "Mutation", and "Subscription" respectively. Likewise, when representing a GraphQL schema using the type system definition language, a schema definition should be omitted if it only uses the default root operation type names. This example describes a valid complete GraphQL schema, despite not explicitly including a schema definition. The "Query" type is presumed to be the query root operation type of the schema. <pre id="example-9d70f" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L226-L230"><a href="#example-9d70f">Example № 41</a><code>type Query { someField: String } </code></pre> </section> </section> <section id="sec-Schema-Extension" secid="3.3.2"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L232"><a href="#sec-Schema-Extension">3.3.2</a>Schema Extension</h3> <div class="spec-production" id="SchemaExtension" data-source="spec/Section%203%20--%20Type%20System.md#L234-L236"> <a href="#SchemaExtension" data-name="SchemaExtension">SchemaExtension</a><div class="spec-rhs">extendschema<a href="#Directives" data-name="Directives">Directives</a>Constopt{<a href="#RootOperationTypeDefinition" data-name="RootOperationTypeDefinition">RootOperationTypeDefinition</a>list}</div> <div class="spec-rhs">extendschema<a href="#Directives" data-name="Directives">Directives</a>Const{</div> </div> Schema extensions are used to represent a schema which has been extended from an original schema. For example, this might be used by a GraphQL service which adds additional operation types, or additional directives to an existing schema. <div id="note-c9cd2" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L242-L244"> <a href="#note-c9cd2">Note</a> Schema extensions without additional operation type definitions must not be followed by a { (such as a query shorthand) to avoid parsing ambiguity. The same limitation applies to the type definitions and extensions below.</div> <section id="sec-Schema-Extension.Schema-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L246"><a href="#sec-Schema-Extension.Schema-Validation" title="link to this subsection">Schema Validation</a></h6> Schema extensions have the potential to be invalid if incorrectly defined. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L250">The Schema must already be defined.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L251-L252">Any non-repeatable directives provided must not already apply to the original Schema.</li> </ol> </section> </section> </section> <section id="sec-Types" secid="3.4"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L255"><a href="#sec-Types">3.4</a>Types</h2> <div class="spec-production" id="TypeDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L257-L263"> <a href="#TypeDefinition" data-name="TypeDefinition">TypeDefinition</a><div class="spec-rhs"><a href="#ScalarTypeDefinition" data-name="ScalarTypeDefinition">ScalarTypeDefinition</a></div> <div class="spec-rhs"><a href="#ObjectTypeDefinition" data-name="ObjectTypeDefinition">ObjectTypeDefinition</a></div> <div class="spec-rhs"><a href="#InterfaceTypeDefinition" data-name="InterfaceTypeDefinition">InterfaceTypeDefinition</a></div> <div class="spec-rhs"><a href="#UnionTypeDefinition" data-name="UnionTypeDefinition">UnionTypeDefinition</a></div> <div class="spec-rhs"><a href="#EnumTypeDefinition" data-name="EnumTypeDefinition">EnumTypeDefinition</a></div> <div class="spec-rhs"><a href="#InputObjectTypeDefinition" data-name="InputObjectTypeDefinition">InputObjectTypeDefinition</a></div> </div> The fundamental unit of any GraphQL Schema is the type. There are six kinds of named type definitions in GraphQL, and two wrapping types. The most basic type is a <code>Scalar</code>. A scalar represents a primitive value, like a string or an integer. Oftentimes, the possible responses for a scalar field are enumerable. GraphQL offers an <code>Enum</code> type in those cases, where the type specifies the space of valid responses. Scalars and Enums form the leaves in response trees; the intermediate levels are <code>Object</code> types, which define a set of fields, where each field is another type in the system, allowing the definition of arbitrary type hierarchies. GraphQL supports two abstract types: interfaces and unions. An <code>Interface</code> defines a list of fields; <code>Object</code> types and other Interface types which implement this Interface are guaranteed to implement those fields. Whenever a field claims it will return an Interface type, it will return a valid implementing Object type during execution. A <code>Union</code> defines a list of possible types; similar to interfaces, whenever the type system claims a union will be returned, one of the possible types will be returned. Finally, oftentimes it is useful to provide complex structs as inputs to GraphQL field arguments or variables; the <code>Input Object</code> type allows the schema to define exactly what data is expected. <section id="sec-Wrapping-Types" secid="3.4.1"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L293"><a href="#sec-Wrapping-Types">3.4.1</a>Wrapping Types</h3> All of the types so far are assumed to be both nullable and singular: e.g. a scalar string returns either null or a singular string. A GraphQL schema may describe that a field represents a list of another type; the <code>List</code> type is provided for this reason, and wraps another type. Similarly, the <code>Non-Null</code> type wraps another type, and denotes that the resulting value will never be null (and that a field error cannot result in a null value). These two types are referred to as “wrapping types”; non-wrapping types are referred to as “named types”. A wrapping type has an underlying named type, found by continually unwrapping the type until a named type is found. </section> <section id="sec-Input-and-Output-Types" secid="3.4.2"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L310"><a href="#sec-Input-and-Output-Types">3.4.2</a>Input and Output Types</h3> Types are used throughout GraphQL to describe both the values accepted as input to arguments and variables as well as the values output by fields. These two uses categorize types as input types and output types. Some kinds of types, like Scalar and Enum types, can be used as both input types and output types; other kinds of types can only be used in one or the other. Input Object types can only be used as input types. Object, Interface, and Union types can only be used as output types. Lists and Non-Null types may be used as input types or output types depending on how the wrapped type may be used. <div class="spec-algo" id="IsInputType()" data-source="spec/Section%203%20--%20Type%20System.md#L321-L327"> <a href="#IsInputType()" data-name="IsInputType">IsInputType</a>(<var data-name="type">type</var>)<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L322-L324">If <var data-name="type">type</var> is a List type or Non-Null type:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L323">Let <var data-name="unwrappedType">unwrappedType</var> be the unwrapped type of <var data-name="type">type</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L324">Return IsInputType(<var data-name="unwrappedType">unwrappedType</var>)</li> </ol> </li> <li data-source="spec/Section%203%20--%20Type%20System.md#L325-L326">If <var data-name="type">type</var> is a Scalar, Enum, or Input Object type:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L326">Return true</li> </ol> </li> <li data-source="spec/Section%203%20--%20Type%20System.md#L327">Return false</li> </ol> </div> <div class="spec-algo" id="IsOutputType()" data-source="spec/Section%203%20--%20Type%20System.md#L329-L335"> <a href="#IsOutputType()" data-name="IsOutputType">IsOutputType</a>(<var data-name="type">type</var>)<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L330-L332">If <var data-name="type">type</var> is a List type or Non-Null type:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L331">Let <var data-name="unwrappedType">unwrappedType</var> be the unwrapped type of <var data-name="type">type</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L332">Return IsOutputType(<var data-name="unwrappedType">unwrappedType</var>)</li> </ol> </li> <li data-source="spec/Section%203%20--%20Type%20System.md#L333-L334">If <var data-name="type">type</var> is a Scalar, Object, Interface, Union, or Enum type:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L334">Return true</li> </ol> </li> <li data-source="spec/Section%203%20--%20Type%20System.md#L335">Return false</li> </ol> </div> </section> <section id="sec-Type-Extensions" secid="3.4.3"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L338"><a href="#sec-Type-Extensions">3.4.3</a>Type Extensions</h3> <div class="spec-production" id="TypeExtension" data-source="spec/Section%203%20--%20Type%20System.md#L340-L346"> <a href="#TypeExtension" data-name="TypeExtension">TypeExtension</a><div class="spec-rhs"><a href="#ScalarTypeExtension" data-name="ScalarTypeExtension">ScalarTypeExtension</a></div> <div class="spec-rhs"><a href="#ObjectTypeExtension" data-name="ObjectTypeExtension">ObjectTypeExtension</a></div> <div class="spec-rhs"><a href="#InterfaceTypeExtension" data-name="InterfaceTypeExtension">InterfaceTypeExtension</a></div> <div class="spec-rhs"><a href="#UnionTypeExtension" data-name="UnionTypeExtension">UnionTypeExtension</a></div> <div class="spec-rhs"><a href="#EnumTypeExtension" data-name="EnumTypeExtension">EnumTypeExtension</a></div> <div class="spec-rhs"><a href="#InputObjectTypeExtension" data-name="InputObjectTypeExtension">InputObjectTypeExtension</a></div> </div> Type extensions are used to represent a GraphQL type which has been extended from some original type. For example, this might be used by a local service to represent additional fields a GraphQL client only accesses locally. </section> </section> <section id="sec-Scalars" secid="3.5"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L353"><a href="#sec-Scalars">3.5</a>Scalars</h2> <div class="spec-production" id="ScalarTypeDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L355"> <a href="#ScalarTypeDefinition" data-name="ScalarTypeDefinition">ScalarTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optscalar<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt</div> </div> Scalar types represent primitive leaf values in a GraphQL type system. GraphQL responses take the form of a hierarchical tree; the leaves of this tree are typically GraphQL Scalar types (but may also be Enum types or null values). GraphQL provides a number of built-in scalars which are fully defined in the sections below, however type systems may also add additional custom scalars to introduce additional semantic meaning. <section id="sec-Scalars.Built-in-Scalars" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L365"><a href="#sec-Scalars.Built-in-Scalars" title="link to this subsection">Built-in Scalars</a></h6> GraphQL specifies a basic set of well-defined Scalar types: Int, Float, String, Boolean, and ID. A GraphQL framework should support all of these types, and a GraphQL service which provides a type by these names must adhere to the behavior described for them in this document. As an example, a service must not include a type called Int and use it to represent 64-bit numbers, internationalization information, or anything other than what is defined in this document. When returning the set of types from the <code>__Schema</code> introspection type, all referenced built-in scalars must be included. If a built-in scalar type is not referenced anywhere in a schema (there is no field, argument, or input field of that type) then it must not be included. When representing a GraphQL schema using the type system definition language, all built-in scalars must be omitted for brevity. </section> <section id="sec-Scalars.Custom-Scalars" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L383"><a href="#sec-Scalars.Custom-Scalars" title="link to this subsection">Custom Scalars</a></h6> GraphQL services may use custom scalar types in addition to the built-in scalars. For example, a GraphQL service could define a scalar called <code>UUID</code> which, while serialized as a string, conforms to <a href="https://tools.ietf.org/html/rfc4122">RFC 4122</a>. When querying a field of type <code>UUID</code>, you can then rely on the ability to parse the result with a RFC 4122 compliant parser. Another example of a potentially useful custom scalar is <code>URL</code>, which serializes as a string, but is guaranteed by the server to be a valid URL. When defining a custom scalar, GraphQL services should provide a <dfn id="scalar-specification-url"><a href="#scalar-specification-url" data-name="scalar-specification-url">scalar specification URL</a></dfn> via the <code>@specifiedBy</code> directive or the <code>specifiedByURL</code> introspection field. This URL must link to a human-readable specification of the data format, serialization, and coercion rules for the scalar. For example, a GraphQL service providing a <code>UUID</code> scalar may link to RFC 4122, or some custom document defining a reasonable subset of that RFC. If a <a href="#scalar-specification-url" data-name="scalar-specification-url">scalar specification URL</a> is present, systems and tools that are aware of it should conform to its described rules. <pre id="example-9e6a3" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L403-L406"><a href="#example-9e6a3">Example № 42</a><code>scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") scalar URL @specifiedBy(url: "https://tools.ietf.org/html/rfc3986") </code></pre> Custom <a href="#scalar-specification-url" data-name="scalar-specification-url">scalar specification URL</a>s should provide a single, stable format to avoid ambiguity. If the linked specification is in flux, the service should link to a fixed version rather than to a resource which might change. Custom <a href="#scalar-specification-url" data-name="scalar-specification-url">scalar specification URL</a>s should not be changed once defined. Doing so would likely disrupt tooling or could introduce breaking changes within the linked specification’s contents. Built-in scalar types must not provide a <a href="#scalar-specification-url" data-name="scalar-specification-url">scalar specification URL</a> as they are specified by this document. <div id="note-b68f7" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L419-L420"> <a href="#note-b68f7">Note</a> Custom scalars should also summarize the specified format and provide examples in their description.</div> </section> <section id="sec-Scalars.Result-Coercion-and-Serialization" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L422"><a href="#sec-Scalars.Result-Coercion-and-Serialization" title="link to this subsection">Result Coercion and Serialization</a></h6> A GraphQL service, when preparing a field of a given scalar type, must uphold the contract the scalar type describes, either by coercing the value or producing a <a href="#sec-Errors.Field-errors">field error</a> if a value cannot be coerced or if coercion may result in data loss. A GraphQL service may decide to allow coercing different internal types to the expected return type. For example when coercing a field of type Int a boolean true value may produce 1 or a string value "123" may be parsed as base-10 123. However if internal type coercion cannot be reasonably performed without losing information, then it must raise a field error. Since this coercion behavior is not observable to clients of the GraphQL service, the precise rules of coercion are left to the implementation. The only requirement is that the service must yield values which adhere to the expected Scalar type. GraphQL scalars are serialized according to the serialization format being used. There may be a most appropriate serialized primitive for each given scalar type, and the service should produce each primitive where appropriate. See <a href="#sec-Serialization-Format">Serialization Format</a> for more detailed information on the serialization of scalars in common JSON and other formats. </section> <section id="sec-Scalars.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L447"><a href="#sec-Scalars.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> If a GraphQL service expects a scalar type as input to an argument, coercion is observable and the rules must be well defined. If an input value does not match a coercion rule, a <a href="#sec-Errors.Request-errors">request error</a> must be raised (input values are validated before execution begins). GraphQL has different constant literals to represent integer and floating-point input values, and coercion rules may apply differently depending on which type of input value is encountered. GraphQL may be parameterized by variables, the values of which are often serialized when sent over a transport like HTTP. Since some common serializations (ex. JSON) do not discriminate between integer and floating-point values, they are interpreted as an integer input value if they have an empty fractional part (ex. <code>1.0</code>) and otherwise as floating-point input value. For all types below, with the exception of Non-Null, if the explicit value null is provided, then the result of input coercion is null. </section> <section id="sec-Int" secid="3.5.1"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L467"><a href="#sec-Int">3.5.1</a>Int</h3> The Int scalar type represents a signed 32-bit numeric non-fractional value. Response formats that support a 32-bit integer or a number type should use that type to represent this scalar. <section id="sec-Int.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L473"><a href="#sec-Int.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> Fields returning the type Int expect to encounter 32-bit integer internal values. GraphQL services may coerce non-integer internal values to integers when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning <code>1</code> for the floating-point number <code>1.0</code>, or returning <code>123</code> for the string <code>"123"</code>. In scenarios where coercion may lose data, raising a field error is more appropriate. For example, a floating-point number <code>1.2</code> should raise a field error instead of being truncated to <code>1</code>. If the integer internal value represents a value less than -231 or greater than or equal to 231, a field error should be raised. </section> <section id="sec-Int.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L488"><a href="#sec-Int.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> When expected as an input type, only integer input values are accepted. All other input values, including strings with numeric content, must raise a request error indicating an incorrect type. If the integer input value represents a value less than -231 or greater than or equal to 231, a request error should be raised. <div id="note-0770a" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L496-L498"> <a href="#note-0770a">Note</a> Numeric integer values larger than 32-bit should either use String or a custom-defined Scalar type, as not all platforms and transports support encoding integer numbers larger than 32-bit.</div> </section> </section> <section id="sec-Float" secid="3.5.2"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L501"><a href="#sec-Float">3.5.2</a>Float</h3> The Float scalar type represents signed double-precision finite values as specified by <a href="https://en.wikipedia.org/wiki/IEEE_floating_point">IEEE 754</a>. Response formats that support an appropriate double-precision number type should use that type to represent this scalar. <section id="sec-Float.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L508"><a href="#sec-Float.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> Fields returning the type Float expect to encounter double-precision floating-point internal values. GraphQL services may coerce non-floating-point internal values to Float when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning <code>1.0</code> for the integer number <code>1</code>, or <code>123.0</code> for the string <code>"123"</code>. Non-finite floating-point internal values (NaN and Infinity) cannot be coerced to Float and must raise a field error. </section> <section id="sec-Float.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L521"><a href="#sec-Float.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> When expected as an input type, both integer and float input values are accepted. Integer input values are coerced to Float by adding an empty fractional part, for example <code>1.0</code> for the integer input value <code>1</code>. All other input values, including strings with numeric content, must raise a request error indicating an incorrect type. If the input value otherwise represents a value not representable by finite IEEE 754 (e.g. NaN, Infinity, or a value outside the available precision), a request error must be raised. </section> </section> <section id="sec-String" secid="3.5.3"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L532"><a href="#sec-String">3.5.3</a>String</h3> The String scalar type represents textual data, represented as a sequence of Unicode code points. The String type is most often used by GraphQL to represent free-form human-readable text. How the String is encoded internally (for example UTF-8) is left to the service implementation. All response serialization formats must support a string representation (for example, JSON Unicode strings), and that representation must be used to serialize this type. <section id="sec-String.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L541"><a href="#sec-String.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> Fields returning the type String expect to encounter Unicode string values. GraphQL services may coerce non-string raw values to String when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning the string <code>"true"</code> for a boolean true value, or the string <code>"1"</code> for the integer <code>1</code>. </section> <section id="sec-String.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L550"><a href="#sec-String.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> When expected as an input type, only valid Unicode string input values are accepted. All other input values must raise a request error indicating an incorrect type. </section> </section> <section id="sec-Boolean" secid="3.5.4"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L557"><a href="#sec-Boolean">3.5.4</a>Boolean</h3> The Boolean scalar type represents <code>true</code> or <code>false</code>. Response formats should use a built-in boolean type if supported; otherwise, they should use their representation of the integers <code>1</code> and <code>0</code>. <section id="sec-Boolean.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L563"><a href="#sec-Boolean.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> Fields returning the type Boolean expect to encounter boolean internal values. GraphQL services may coerce non-boolean raw values to Boolean when reasonable without losing information, otherwise they must raise a field error. Examples of this may include returning <code>true</code> for non-zero numbers. </section> <section id="sec-Boolean.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L571"><a href="#sec-Boolean.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> When expected as an input type, only boolean input values are accepted. All other input values must raise a request error indicating an incorrect type. </section> </section> <section id="sec-ID" secid="3.5.5"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L577"><a href="#sec-ID">3.5.5</a>ID</h3> The ID scalar type represents a unique identifier, often used to refetch an object or as the key for a cache. The ID type is serialized in the same way as a String; however, it is not intended to be human-readable. While it is often numeric, it should always serialize as a String. <section id="sec-ID.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L584"><a href="#sec-ID.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> GraphQL is agnostic to ID format, and serializes to string to ensure consistency across many formats ID could represent, from small auto-increment numbers, to large 128-bit random numbers, to base64 encoded values, or string values of a format like <a href="https://en.wikipedia.org/wiki/Globally_unique_identifier">GUID</a>. GraphQL services should coerce as appropriate given the ID formats they expect. When coercion is not possible they must raise a field error. </section> <section id="sec-ID.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L594"><a href="#sec-ID.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> When expected as an input type, any string (such as <code>"4"</code>) or integer (such as <code>4</code> or <code>-4</code>) input value should be coerced to ID as appropriate for the ID formats a given GraphQL service expects. Any other input value, including float input values (such as <code>4.0</code>), must raise a request error indicating an incorrect type. </section> </section> <section id="sec-Scalar-Extensions" secid="3.5.6"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L603"><a href="#sec-Scalar-Extensions">3.5.6</a>Scalar Extensions</h3> <div class="spec-production" id="ScalarTypeExtension" data-source="spec/Section%203%20--%20Type%20System.md#L605-L606"> <a href="#ScalarTypeExtension" data-name="ScalarTypeExtension">ScalarTypeExtension</a><div class="spec-rhs">extendscalar<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Const</div> </div> Scalar type extensions are used to represent a scalar type which has been extended from some original scalar type. For example, this might be used by a GraphQL tool or service which adds directives to an existing scalar. <section id="sec-Scalar-Extensions.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L612"><a href="#sec-Scalar-Extensions.Type-Validation" title="link to this subsection">Type Validation</a></h6> Scalar type extensions have the potential to be invalid if incorrectly defined. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L616">The named type must already be defined and must be a Scalar type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L617-L618">Any non-repeatable directives provided must not already apply to the original Scalar type.</li> </ol> </section> </section> </section> <section id="sec-Objects" secid="3.6"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L621"><a href="#sec-Objects">3.6</a>Objects</h2> <div class="spec-production" id="ObjectTypeDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L623-L625"> <a href="#ObjectTypeDefinition" data-name="ObjectTypeDefinition">ObjectTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>opttype<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#FieldsDefinition" data-name="FieldsDefinition">FieldsDefinition</a></div> <div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>opttype<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt{</div> </div> <div class="spec-production" id="ImplementsInterfaces" data-source="spec/Section%203%20--%20Type%20System.md#L627-L629"> <a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a><div class="spec-rhs"><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>&<a href="#NamedType" data-name="NamedType">NamedType</a></div> <div class="spec-rhs">implements&opt<a href="#NamedType" data-name="NamedType">NamedType</a></div> </div> <div class="spec-production" id="FieldsDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L631"> <a href="#FieldsDefinition" data-name="FieldsDefinition">FieldsDefinition</a><div class="spec-rhs">{<a href="#FieldDefinition" data-name="FieldDefinition">FieldDefinition</a>list}</div> </div> <div class="spec-production" id="FieldDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L633"> <a href="#FieldDefinition" data-name="FieldDefinition">FieldDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>opt<a href="#Name" data-name="Name">Name</a><a href="#ArgumentsDefinition" data-name="ArgumentsDefinition">ArgumentsDefinition</a>opt:<a href="#Type" data-name="Type">Type</a><a href="#Directives" data-name="Directives">Directives</a>Constopt</div> </div> GraphQL operations are hierarchical and composed, describing a tree of information. While Scalar types describe the leaf values of these hierarchical operations, Objects describe the intermediate levels. GraphQL Objects represent a list of named fields, each of which yield a value of a specific type. Object values should be serialized as ordered maps, where the selected field names (or aliases) are the keys and the result of evaluating the field is the value, ordered by the order in which they appear in the selection set. All fields defined within an Object type must not have a name which begins with "__" (two underscores), as this is used exclusively by GraphQL’s introspection system. For example, a type <code>Person</code> could be described as: <pre id="example-ccb01" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L651-L657"><a href="#example-ccb01">Example № 43</a><code>type Person { name: String age: Int picture: Url } </code></pre> Where <code>name</code> is a field that will yield a String value, and <code>age</code> is a field that will yield an Int value, and <code>picture</code> is a field that will yield a <code>Url</code> value. A query of an object value must select at least one field. This selection of fields will yield an ordered map containing exactly the subset of the object queried, which should be represented in the order in which they were queried. Only fields that are declared on the object type may validly be queried on that object. For example, selecting all the fields of <code>Person</code>: <pre id="example-1743a" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L671-L677"><a href="#example-1743a">Example № 44</a><code>{ name age picture } </code></pre> Would yield the object: <pre id="example-71184" class="spec-example" data-language="json" data-source="spec/Section%203%20--%20Type%20System.md#L681-L687"><a href="#example-71184">Example № 45</a><code>{ "name": "Mark Zuckerberg", "age": 30, "picture": "http://some.cdn/picture.jpg" } </code></pre> While selecting a subset of fields: <pre id="example-3964f" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L691-L696"><a href="#example-3964f">Example № 46</a><code>{ age name } </code></pre> Must only yield exactly that subset: <pre id="example-600a0" class="spec-example" data-language="json" data-source="spec/Section%203%20--%20Type%20System.md#L700-L705"><a href="#example-600a0">Example № 47</a><code>{ "age": 30, "name": "Mark Zuckerberg" } </code></pre> A field of an Object type may be a Scalar, Enum, another Object type, an Interface, or a Union. Additionally, it may be any wrapping type whose underlying base type is one of those five. For example, the <code>Person</code> type might include a <code>relationship</code>: <pre id="example-49198" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L713-L720"><a href="#example-49198">Example № 48</a><code>type Person { name: String age: Int picture: Url relationship: Person } </code></pre> Valid operations must supply a nested field set for any field that returns an object, so this operation is not valid: <pre id="example-729a1" class="spec-counter-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L725-L730"><a href="#example-729a1">Counter Example № 49</a><code>{ name relationship } </code></pre> However, this example is valid: <pre id="example-bb999" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L734-L741"><a href="#example-bb999">Example № 50</a><code>{ name relationship { name } } </code></pre> And will yield the subset of each object type queried: <pre id="example-352cc" class="spec-example" data-language="json" data-source="spec/Section%203%20--%20Type%20System.md#L745-L752"><a href="#example-352cc">Example № 51</a><code>{ "name": "Mark Zuckerberg", "relationship": { "name": "Priscilla Chan" } } </code></pre> <section id="sec-Objects.Field-Ordering" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L754"><a href="#sec-Objects.Field-Ordering" title="link to this subsection">Field Ordering</a></h6> When querying an Object, the resulting mapping of fields are conceptually ordered in the same order in which they were encountered during execution, excluding fragments for which the type does not apply and fields or fragments that are skipped via <code>@skip</code> or <code>@include</code> directives. This ordering is correctly produced when using the <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>() algorithm. Response serialization formats capable of representing ordered maps should maintain this ordering. Serialization formats which can only represent unordered maps (such as JSON) should retain this order textually. That is, if two fields <code>{foo, bar}</code> were queried in that order, the resulting JSON serialization should contain <code>{"foo": "...", "bar": "..."}</code> in the same order. Producing a response where fields are represented in the same order in which they appear in the request improves human readability during debugging and enables more efficient parsing of responses if the order of properties can be anticipated. If a fragment is spread before other fields, the fields that fragment specifies occur in the response before the following fields. <pre id="example-7924b" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L776-L787"><a href="#example-7924b">Example № 52</a><code>{ foo ...Frag qux } fragment Frag on Query { bar baz } </code></pre> Produces the ordered result: <pre id="example-1455b" class="spec-example" data-language="json" data-source="spec/Section%203%20--%20Type%20System.md#L791-L798"><a href="#example-1455b">Example № 53</a><code>{ "foo": 1, "bar": 2, "baz": 3, "qux": 4 } </code></pre> If a field is queried multiple times in a selection, it is ordered by the first time it is encountered. However fragments for which the type does not apply does not affect ordering. <pre id="example-70ded" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L804-L822"><a href="#example-70ded">Example № 54</a><code>{ foo ...Ignored ...Matching bar } fragment Ignored on UnknownType { qux baz } fragment Matching on Query { bar qux foo } </code></pre> Produces the ordered result: <pre id="example-2e0e9" class="spec-example" data-language="json" data-source="spec/Section%203%20--%20Type%20System.md#L826-L832"><a href="#example-2e0e9">Example № 55</a><code>{ "foo": 1, "bar": 2, "qux": 3 } </code></pre> Also, if directives result in fields being excluded, they are not considered in the ordering of fields. <pre id="example-50762" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L837-L843"><a href="#example-50762">Example № 56</a><code>{ foo @skip(if: true) bar foo } </code></pre> Produces the ordered result: <pre id="example-dd904" class="spec-example" data-language="json" data-source="spec/Section%203%20--%20Type%20System.md#L847-L852"><a href="#example-dd904">Example № 57</a><code>{ "bar": 1, "foo": 2 } </code></pre> </section> <section id="sec-Objects.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L854"><a href="#sec-Objects.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> Determining the result of coercing an object is the heart of the GraphQL executor, so this is covered in that section of the spec. </section> <section id="sec-Objects.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L859"><a href="#sec-Objects.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> Objects are never valid inputs. </section> <section id="sec-Objects.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L863"><a href="#sec-Objects.Type-Validation" title="link to this subsection">Type Validation</a></h6> Object types have the potential to be invalid if incorrectly defined. This set of rules must be adhered to by every Object type in a GraphQL schema. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L868">An Object type must define one or more fields.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L869-L879">For each field of an Object type:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L870-L871">The field must have a unique name within that Object type; no two fields may share the same name.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L872-L873">The field must not have a name which begins with the characters "__" (two underscores).</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L874">The field must return a type where <a href="#IsOutputType()" data-name="IsOutputType">IsOutputType</a>(<var data-name="fieldType">fieldType</var>) returns true.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L875-L879">For each argument of the field:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L876-L877">The argument must not have a name which begins with the characters "__" (two underscores).</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L878-L879">The argument must accept a type where <a href="#IsInputType()" data-name="IsInputType">IsInputType</a>(<var data-name="argumentType">argumentType</var>) returns true.</li> </ol> </li> </ol> </li> <li data-source="spec/Section%203%20--%20Type%20System.md#L880">An object type may declare that it implements one or more unique interfaces.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L881-L884">An object type must be a super-set of all interfaces it implements:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L882">Let this object type be <var data-name="objectType">objectType</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L883-L884">For each interface declared implemented as <var data-name="interfaceType">interfaceType</var>, <a href="#IsValidImplementation()" data-name="IsValidImplementation">IsValidImplementation</a>(<var data-name="objectType">objectType</var>, <var data-name="interfaceType">interfaceType</var>) must be true.</li> </ol> </li> </ol> <div class="spec-algo" id="IsValidImplementation()" data-source="spec/Section%203%20--%20Type%20System.md#L886-L906"> <a href="#IsValidImplementation()" data-name="IsValidImplementation">IsValidImplementation</a>(<var data-name="type">type</var>, <var data-name="implementedType">implementedType</var>)<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L888-L889">If <var data-name="implementedType">implementedType</var> declares it implements any interfaces, <var data-name="type">type</var> must also declare it implements those interfaces.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L890-L906"><var data-name="type">type</var> must include a field of the same name for every field defined in <var data-name="implementedType">implementedType</var>.<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L892">Let <var data-name="field">field</var> be that named field on <var data-name="type">type</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L893">Let <var data-name="implementedField">implementedField</var> be that named field on <var data-name="implementedType">implementedType</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L894-L897"><var data-name="field">field</var> must include an argument of the same name for every argument defined in <var data-name="implementedField">implementedField</var>.<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L896-L897">That named argument on <var data-name="field">field</var> must accept the same type (invariant) as that named argument on <var data-name="implementedField">implementedField</var>.</li> </ol> </li> <li data-source="spec/Section%203%20--%20Type%20System.md#L898-L900"><var data-name="field">field</var> may include additional arguments not defined in <var data-name="implementedField">implementedField</var>, but any additional argument must not be required, e.g. must not be of a non-nullable type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L901-L906"><var data-name="field">field</var> must return a type which is equal to or a sub-type of (covariant) the return type of <var data-name="implementedField">implementedField</var> field’s return type:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L903">Let <var data-name="fieldType">fieldType</var> be the return type of <var data-name="field">field</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L904">Let <var data-name="implementedFieldType">implementedFieldType</var> be the return type of <var data-name="implementedField">implementedField</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L905-L906"><a href="#IsValidImplementationFieldType()" data-name="IsValidImplementationFieldType">IsValidImplementationFieldType</a>(<var data-name="fieldType">fieldType</var>, <var data-name="implementedFieldType">implementedFieldType</var>) must be true.</li> </ol> </li> </ol> </li> </ol> </div> <div class="spec-algo" id="IsValidImplementationFieldType()" data-source="spec/Section%203%20--%20Type%20System.md#L908-L927"> <a href="#IsValidImplementationFieldType()" data-name="IsValidImplementationFieldType">IsValidImplementationFieldType</a>(<var data-name="fieldType">fieldType</var>, <var data-name="implementedFieldType">implementedFieldType</var>)<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L909-L914">If <var data-name="fieldType">fieldType</var> is a Non-Null type:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L910">Let <var data-name="nullableType">nullableType</var> be the unwrapped nullable type of <var data-name="fieldType">fieldType</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L911-L913">Let <var data-name="implementedNullableType">implementedNullableType</var> be the unwrapped nullable type of <var data-name="implementedFieldType">implementedFieldType</var> if it is a Non-Null type, otherwise let it be <var data-name="implementedFieldType">implementedFieldType</var> directly.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L914">Return <a href="#IsValidImplementationFieldType()" data-name="IsValidImplementationFieldType">IsValidImplementationFieldType</a>(<var data-name="nullableType">nullableType</var>, <var data-name="implementedNullableType">implementedNullableType</var>).</li> </ol> </li> <li data-source="spec/Section%203%20--%20Type%20System.md#L915-L919">If <var data-name="fieldType">fieldType</var> is a List type and <var data-name="implementedFieldType">implementedFieldType</var> is also a List type:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L916">Let <var data-name="itemType">itemType</var> be the unwrapped item type of <var data-name="fieldType">fieldType</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L917-L918">Let <var data-name="implementedItemType">implementedItemType</var> be the unwrapped item type of <var data-name="implementedFieldType">implementedFieldType</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L919">Return <a href="#IsValidImplementationFieldType()" data-name="IsValidImplementationFieldType">IsValidImplementationFieldType</a>(<var data-name="itemType">itemType</var>, <var data-name="implementedItemType">implementedItemType</var>).</li> </ol> </li> <li data-source="spec/Section%203%20--%20Type%20System.md#L920">If <var data-name="fieldType">fieldType</var> is the same type as <var data-name="implementedFieldType">implementedFieldType</var> then return true.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L921-L923">If <var data-name="fieldType">fieldType</var> is an Object type and <var data-name="implementedFieldType">implementedFieldType</var> is a Union type and <var data-name="fieldType">fieldType</var> is a possible type of <var data-name="implementedFieldType">implementedFieldType</var> then return true.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L924-L926">If <var data-name="fieldType">fieldType</var> is an Object or Interface type and <var data-name="implementedFieldType">implementedFieldType</var> is an Interface type and <var data-name="fieldType">fieldType</var> declares it implements <var data-name="implementedFieldType">implementedFieldType</var> then return true.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L927">Otherwise return false.</li> </ol> </div> </section> <section id="sec-Field-Arguments" secid="3.6.1"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L930"><a href="#sec-Field-Arguments">3.6.1</a>Field Arguments</h3> <div class="spec-production" id="ArgumentsDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L932"> <a href="#ArgumentsDefinition" data-name="ArgumentsDefinition">ArgumentsDefinition</a><div class="spec-rhs">(<a href="#InputValueDefinition" data-name="InputValueDefinition">InputValueDefinition</a>list)</div> </div> <div class="spec-production" id="InputValueDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L934"> <a href="#InputValueDefinition" data-name="InputValueDefinition">InputValueDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>opt<a href="#Name" data-name="Name">Name</a>:<a href="#Type" data-name="Type">Type</a><a href="#DefaultValue" data-name="DefaultValue">DefaultValue</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt</div> </div> Object fields are conceptually functions which yield values. Occasionally object fields can accept arguments to further specify the return value. Object field arguments are defined as a list of all possible argument names and their expected input types. All arguments defined within a field must not have a name which begins with "__" (two underscores), as this is used exclusively by GraphQL’s introspection system. For example, a <code>Person</code> type with a <code>picture</code> field could accept an argument to determine what size of an image to return. <pre id="example-fb0d5" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L948-L953"><a href="#example-fb0d5">Example № 58</a><code>type Person { name: String picture(size: Int): Url } </code></pre> Operations can optionally specify arguments to their fields to provide these arguments. This example operation: <pre id="example-81f19" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L960-L965"><a href="#example-81f19">Example № 59</a><code>{ name picture(size: 600) } </code></pre> May return the result: <pre id="example-31f7a" class="spec-example" data-language="json" data-source="spec/Section%203%20--%20Type%20System.md#L969-L974"><a href="#example-31f7a">Example № 60</a><code>{ "name": "Mark Zuckerberg", "picture": "http://some.cdn/picture_600.jpg" } </code></pre> The type of an object field argument must be an input type (any type except an Object, Interface, or Union type). </section> <section id="sec-Field-Deprecation" secid="3.6.2"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L980"><a href="#sec-Field-Deprecation">3.6.2</a>Field Deprecation</h3> Fields in an object may be marked as deprecated as deemed necessary by the application. It is still legal to include these fields in a selection set (to ensure existing clients are not broken by the change), but the fields should be appropriately treated in documentation and tooling. When using the type system definition language, <code>@deprecated</code> directives are used to indicate that a field is deprecated: <pre id="example-013ef" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L990-L994"><a href="#example-013ef">Example № 61</a><code>type ExampleType { oldField: String @deprecated } </code></pre> </section> <section id="sec-Object-Extensions" secid="3.6.3"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L997"><a href="#sec-Object-Extensions">3.6.3</a>Object Extensions</h3> <div class="spec-production" id="ObjectTypeExtension" data-source="spec/Section%203%20--%20Type%20System.md#L999-L1002"> <a href="#ObjectTypeExtension" data-name="ObjectTypeExtension">ObjectTypeExtension</a><div class="spec-rhs">extendtype<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#FieldsDefinition" data-name="FieldsDefinition">FieldsDefinition</a></div> <div class="spec-rhs">extendtype<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Const{</div> <div class="spec-rhs">extendtype<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>{</div> </div> Object type extensions are used to represent a type which has been extended from some original type. For example, this might be used to represent local data, or by a GraphQL service which is itself an extension of another GraphQL service. In this example, a local data field is added to a <code>Story</code> type: <pre id="example-8bda7" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1010-L1014"><a href="#example-8bda7">Example № 62</a><code>extend type Story { isHiddenLocally: Boolean } </code></pre> Object type extensions may choose not to add additional fields, instead only adding interfaces or directives. In this example, a directive is added to a <code>User</code> type without adding fields: <pre id="example-605bd" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1021-L1023"><a href="#example-605bd">Example № 63</a><code>extend type User @addedDirective </code></pre> <section id="sec-Object-Extensions.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1025"><a href="#sec-Object-Extensions.Type-Validation" title="link to this subsection">Type Validation</a></h6> Object type extensions have the potential to be invalid if incorrectly defined. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1029">The named type must already be defined and must be an Object type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1030-L1031">The fields of an Object type extension must have unique names; no two fields may share the same name.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1032-L1033">Any fields of an Object type extension must not be already defined on the original Object type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1034-L1035">Any non-repeatable directives provided must not already apply to the original Object type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1036-L1037">Any interfaces provided must not be already implemented by the original Object type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1038-L1039">The resulting extended object type must be a super-set of all interfaces it implements.</li> </ol> </section> </section> </section> <section id="sec-Interfaces" secid="3.7"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L1042"><a href="#sec-Interfaces">3.7</a>Interfaces</h2> <div class="spec-production" id="InterfaceTypeDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L1044-L1046"> <a href="#InterfaceTypeDefinition" data-name="InterfaceTypeDefinition">InterfaceTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optinterface<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#FieldsDefinition" data-name="FieldsDefinition">FieldsDefinition</a></div> <div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optinterface<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt{</div> </div> GraphQL interfaces represent a list of named fields and their arguments. GraphQL objects and interfaces can then implement these interfaces which requires that the implementing type will define all fields defined by those interfaces. Fields on a GraphQL interface have the same rules as fields on a GraphQL object; their type can be Scalar, Object, Enum, Interface, or Union, or any wrapping type whose base type is one of those five. For example, an interface <code>NamedEntity</code> may describe a required field and types such as <code>Person</code> or <code>Business</code> may then implement this interface to guarantee this field will always exist. Types may also implement multiple interfaces. For example, <code>Business</code> implements both the <code>NamedEntity</code> and <code>ValuedEntity</code> interfaces in the example below. <pre id="example-ab5e5" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1063-L1082"><a href="#example-ab5e5">Example № 64</a><code>interface NamedEntity { name: String } interface ValuedEntity { value: Int } type Person implements NamedEntity { name: String age: Int } type Business implements NamedEntity & ValuedEntity { name: String value: Int employeeCount: Int } </code></pre> Fields which yield an interface are useful when one of many Object types are expected, but some fields should be guaranteed. To continue the example, a <code>Contact</code> might refer to <code>NamedEntity</code>. <pre id="example-00227" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1089-L1095"><a href="#example-00227">Example № 65</a><code>type Contact { entity: NamedEntity phoneNumber: String address: String } </code></pre> This allows us to write a selection set for a <code>Contact</code> that can select the common fields. <pre id="example-bc3fd" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1100-L1107"><a href="#example-bc3fd">Example № 66</a><code>{ entity { name } phoneNumber } </code></pre> When selecting fields on an interface type, only those fields declared on the interface may be queried. In the above example, <code>entity</code> returns a <code>NamedEntity</code>, and <code>name</code> is defined on <code>NamedEntity</code>, so it is valid. However, the following would not be a valid selection set against <code>Contact</code>: <pre id="example-0c812" class="spec-counter-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1114-L1122"><a href="#example-0c812">Counter Example № 67</a><code>{ entity { name age } phoneNumber } </code></pre> because <code>entity</code> refers to a <code>NamedEntity</code>, and <code>age</code> is not defined on that interface. Querying for <code>age</code> is only valid when the result of <code>entity</code> is a <code>Person</code>; this can be expressed using a fragment or an inline fragment: <pre id="example-47576" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1128-L1138"><a href="#example-47576">Example № 68</a><code>{ entity { name ... on Person { age } } phoneNumber } </code></pre> <section id="sec-Interfaces.Interfaces-Implementing-Interfaces" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1140"><a href="#sec-Interfaces.Interfaces-Implementing-Interfaces" title="link to this subsection">Interfaces Implementing Interfaces</a></h6> When defining an interface that implements another interface, the implementing interface must define each field that is specified by the implemented interface. For example, the interface Resource must define the field id to implement the Node interface: <pre id="example-ba6cb" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1147-L1156"><a href="#example-ba6cb">Example № 69</a><code>interface Node { id: ID! } interface Resource implements Node { id: ID! url: String } </code></pre> Transitively implemented interfaces (interfaces implemented by the interface that is being implemented) must also be defined on an implementing type or interface. For example, <code>Image</code> cannot implement <code>Resource</code> without also implementing <code>Node</code>: <pre id="example-4c7ed" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1163-L1178"><a href="#example-4c7ed">Example № 70</a><code>interface Node { id: ID! } interface Resource implements Node { id: ID! url: String } interface Image implements Resource & Node { id: ID! url: String thumbnail: String } </code></pre> Interface definitions must not contain cyclic references nor implement themselves. This example is invalid because <code>Node</code> and <code>Named</code> implement themselves and each other: <pre id="example-9b199" class="spec-counter-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1184-L1194"><a href="#example-9b199">Counter Example № 71</a><code>interface Node implements Named & Node { id: ID! name: String } interface Named implements Node & Named { id: ID! name: String } </code></pre> </section> <section id="sec-Interfaces.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1197"><a href="#sec-Interfaces.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> The interface type should have some way of determining which object a given result corresponds to. Once it has done so, the result coercion of the interface is the same as the result coercion of the object. </section> <section id="sec-Interfaces.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1203"><a href="#sec-Interfaces.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> Interfaces are never valid inputs. </section> <section id="sec-Interfaces.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1207"><a href="#sec-Interfaces.Type-Validation" title="link to this subsection">Type Validation</a></h6> Interface types have the potential to be invalid if incorrectly defined. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1211">An Interface type must define one or more fields.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1212-L1223">For each field of an Interface type:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1213-L1214">The field must have a unique name within that Interface type; no two fields may share the same name.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1215-L1216">The field must not have a name which begins with the characters "__" (two underscores).</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1217-L1218">The field must return a type where <a href="#IsOutputType()" data-name="IsOutputType">IsOutputType</a>(<var data-name="fieldType">fieldType</var>) returns true.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1219-L1223">For each argument of the field:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1220-L1221">The argument must not have a name which begins with the characters "__" (two underscores).</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1222-L1223">The argument must accept a type where <a href="#IsInputType()" data-name="IsInputType">IsInputType</a>(<var data-name="argumentType">argumentType</var>) returns true.</li> </ol> </li> </ol> </li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1224-L1225">An interface type may declare that it implements one or more unique interfaces, but may not implement itself.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1226-L1229">An interface type must be a super-set of all interfaces it implements:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1227">Let this interface type be <var data-name="implementingType">implementingType</var>.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1228-L1229">For each interface declared implemented as <var data-name="implementedType">implementedType</var>, <a href="#IsValidImplementation()" data-name="IsValidImplementation">IsValidImplementation</a>(<var data-name="implementingType">implementingType</var>, <var data-name="implementedType">implementedType</var>) must be true.</li> </ol> </li> </ol> </section> <section id="sec-Interface-Extensions" secid="3.7.1"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L1232"><a href="#sec-Interface-Extensions">3.7.1</a>Interface Extensions</h3> <div class="spec-production" id="InterfaceTypeExtension" data-source="spec/Section%203%20--%20Type%20System.md#L1234-L1237"> <a href="#InterfaceTypeExtension" data-name="InterfaceTypeExtension">InterfaceTypeExtension</a><div class="spec-rhs">extendinterface<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#FieldsDefinition" data-name="FieldsDefinition">FieldsDefinition</a></div> <div class="spec-rhs">extendinterface<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Const{</div> <div class="spec-rhs">extendinterface<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>{</div> </div> Interface type extensions are used to represent an interface which has been extended from some original interface. For example, this might be used to represent common local data on many types, or by a GraphQL service which is itself an extension of another GraphQL service. In this example, an extended data field is added to a <code>NamedEntity</code> type along with the types which implement it: <pre id="example-9d45f" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1247-L1259"><a href="#example-9d45f">Example № 72</a><code>extend interface NamedEntity { nickname: String } extend type Person { nickname: String } extend type Business { nickname: String } </code></pre> Interface type extensions may choose not to add additional fields, instead only adding directives. In this example, a directive is added to a <code>NamedEntity</code> type without adding fields: <pre id="example-02d28" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1267-L1269"><a href="#example-02d28">Example № 73</a><code>extend interface NamedEntity @addedDirective </code></pre> <section id="sec-Interface-Extensions.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1271"><a href="#sec-Interface-Extensions.Type-Validation" title="link to this subsection">Type Validation</a></h6> Interface type extensions have the potential to be invalid if incorrectly defined. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1275">The named type must already be defined and must be an Interface type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1276-L1277">The fields of an Interface type extension must have unique names; no two fields may share the same name.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1278-L1279">Any fields of an Interface type extension must not be already defined on the original Interface type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1280-L1282">Any Object or Interface type which implemented the original Interface type must also be a super-set of the fields of the Interface type extension (which may be due to Object type extension).</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1283-L1284">Any non-repeatable directives provided must not already apply to the original Interface type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1285-L1286">The resulting extended Interface type must be a super-set of all Interfaces it implements.</li> </ol> </section> </section> </section> <section id="sec-Unions" secid="3.8"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L1289"><a href="#sec-Unions">3.8</a>Unions</h2> <div class="spec-production" id="UnionTypeDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L1291"> <a href="#UnionTypeDefinition" data-name="UnionTypeDefinition">UnionTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optunion<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#UnionMemberTypes" data-name="UnionMemberTypes">UnionMemberTypes</a>opt</div> </div> <div class="spec-production" id="UnionMemberTypes" data-source="spec/Section%203%20--%20Type%20System.md#L1293-L1295"> <a href="#UnionMemberTypes" data-name="UnionMemberTypes">UnionMemberTypes</a><div class="spec-rhs"><a href="#UnionMemberTypes" data-name="UnionMemberTypes">UnionMemberTypes</a>|<a href="#NamedType" data-name="NamedType">NamedType</a></div> <div class="spec-rhs">=|opt<a href="#NamedType" data-name="NamedType">NamedType</a></div> </div> GraphQL Unions represent an object that could be one of a list of GraphQL Object types, but provides for no guaranteed fields between those types. They also differ from interfaces in that Object types declare what interfaces they implement, but are not aware of what unions contain them. With interfaces and objects, only those fields defined on the type can be queried directly; to query other fields on an interface, typed fragments must be used. This is the same as for unions, but unions do not define any fields, so no fields may be queried on this type without the use of type refining fragments or inline fragments (with the exception of the meta-field <var data-name="__typename">__typename</var>). For example, we might define the following types: <pre id="example-255de" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1311-L1327"><a href="#example-255de">Example № 74</a><code>union SearchResult = Photo | Person type Person { name: String age: Int } type Photo { height: Int width: Int } type SearchQuery { firstSearchResult: SearchResult } </code></pre> In this example, a query operation wants the name if the result was a Person, and the height if it was a photo. However because a union itself defines no fields, this could be ambiguous and is invalid. <pre id="example-38dc1" class="spec-counter-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1333-L1340"><a href="#example-38dc1">Counter Example № 75</a><code>{ firstSearchResult { name height } } </code></pre> A valid operation includes typed fragments (in this example, inline fragments): <pre id="example-f8163" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1344-L1355"><a href="#example-f8163">Example № 76</a><code>{ firstSearchResult { ... on Person { name } ... on Photo { height } } } </code></pre> Union members may be defined with an optional leading <code>|</code> character to aid formatting when representing a longer list of possible types: <pre id="example-0fbc6" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1360-L1364"><a href="#example-0fbc6">Example № 77</a><code>union SearchResult = | Photo | Person </code></pre> <section id="sec-Unions.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1366"><a href="#sec-Unions.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> The union type should have some way of determining which object a given result corresponds to. Once it has done so, the result coercion of the union is the same as the result coercion of the object. </section> <section id="sec-Unions.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1372"><a href="#sec-Unions.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> Unions are never valid inputs. </section> <section id="sec-Unions.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1376"><a href="#sec-Unions.Type-Validation" title="link to this subsection">Type Validation</a></h6> Union types have the potential to be invalid if incorrectly defined. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1380">A Union type must include one or more unique member types.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1381-L1383">The member types of a Union type must all be Object base types; Scalar, Interface and Union types must not be member types of a Union. Similarly, wrapping types must not be member types of a Union.</li> </ol> </section> <section id="sec-Union-Extensions" secid="3.8.1"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L1386"><a href="#sec-Union-Extensions">3.8.1</a>Union Extensions</h3> <div class="spec-production" id="UnionTypeExtension" data-source="spec/Section%203%20--%20Type%20System.md#L1388-L1390"> <a href="#UnionTypeExtension" data-name="UnionTypeExtension">UnionTypeExtension</a><div class="spec-rhs">extendunion<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#UnionMemberTypes" data-name="UnionMemberTypes">UnionMemberTypes</a></div> <div class="spec-rhs">extendunion<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Const</div> </div> Union type extensions are used to represent a union type which has been extended from some original union type. For example, this might be used to represent additional local data, or by a GraphQL service which is itself an extension of another GraphQL service. <section id="sec-Union-Extensions.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1397"><a href="#sec-Union-Extensions.Type-Validation" title="link to this subsection">Type Validation</a></h6> Union type extensions have the potential to be invalid if incorrectly defined. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1401">The named type must already be defined and must be a Union type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1402-L1404">The member types of a Union type extension must all be Object base types; Scalar, Interface and Union types must not be member types of a Union. Similarly, wrapping types must not be member types of a Union.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1405">All member types of a Union type extension must be unique.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1406-L1407">All member types of a Union type extension must not already be a member of the original Union type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1408-L1409">Any non-repeatable directives provided must not already apply to the original Union type.</li> </ol> </section> </section> </section> <section id="sec-Enums" secid="3.9"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L1411"><a href="#sec-Enums">3.9</a>Enums</h2> <div class="spec-production" id="EnumTypeDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L1413-L1415"> <a href="#EnumTypeDefinition" data-name="EnumTypeDefinition">EnumTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optenum<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#EnumValuesDefinition" data-name="EnumValuesDefinition">EnumValuesDefinition</a></div> <div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optenum<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt{</div> </div> <div class="spec-production" id="EnumValuesDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L1417"> <a href="#EnumValuesDefinition" data-name="EnumValuesDefinition">EnumValuesDefinition</a><div class="spec-rhs">{<a href="#EnumValueDefinition" data-name="EnumValueDefinition">EnumValueDefinition</a>list}</div> </div> <div class="spec-production" id="EnumValueDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L1419"> <a href="#EnumValueDefinition" data-name="EnumValueDefinition">EnumValueDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>opt<a href="#EnumValue" data-name="EnumValue">EnumValue</a><a href="#Directives" data-name="Directives">Directives</a>Constopt</div> </div> GraphQL Enum types, like Scalar types, also represent leaf values in a GraphQL type system. However Enum types describe the set of possible values. Enums are not references for a numeric value, but are unique values in their own right. They may serialize as a string: the name of the represented value. In this example, an Enum type called <code>Direction</code> is defined: <pre id="example-36555" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1429-L1436"><a href="#example-36555">Example № 78</a><code>enum Direction { NORTH EAST SOUTH WEST } </code></pre> <section id="sec-Enums.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1438"><a href="#sec-Enums.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> GraphQL services must return one of the defined set of possible values. If a reasonable coercion is not possible they must raise a field error. </section> <section id="sec-Enums.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1443"><a href="#sec-Enums.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> GraphQL has a constant literal to represent enum input values. GraphQL string literals must not be accepted as an enum input and instead raise a request error. Variable transport serializations which have a different representation for non-string symbolic values (for example, <a href="https://github.com/edn-format/edn">EDN</a>) should only allow such values as enum input values. Otherwise, for most transport serializations that do not, strings may be interpreted as the enum input value with the same name. </section> <section id="sec-Enums.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1454"><a href="#sec-Enums.Type-Validation" title="link to this subsection">Type Validation</a></h6> Enum types have the potential to be invalid if incorrectly defined. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1458">An Enum type must define one or more unique enum values.</li> </ol> </section> <section id="sec-Enum-Extensions" secid="3.9.1"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L1461"><a href="#sec-Enum-Extensions">3.9.1</a>Enum Extensions</h3> <div class="spec-production" id="EnumTypeExtension" data-source="spec/Section%203%20--%20Type%20System.md#L1463-L1465"> <a href="#EnumTypeExtension" data-name="EnumTypeExtension">EnumTypeExtension</a><div class="spec-rhs">extendenum<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#EnumValuesDefinition" data-name="EnumValuesDefinition">EnumValuesDefinition</a></div> <div class="spec-rhs">extendenum<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Const{</div> </div> Enum type extensions are used to represent an enum type which has been extended from some original enum type. For example, this might be used to represent additional local data, or by a GraphQL service which is itself an extension of another GraphQL service. <section id="sec-Enum-Extensions.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1472"><a href="#sec-Enum-Extensions.Type-Validation" title="link to this subsection">Type Validation</a></h6> Enum type extensions have the potential to be invalid if incorrectly defined. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1476">The named type must already be defined and must be an Enum type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1477">All values of an Enum type extension must be unique.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1478-L1479">All values of an Enum type extension must not already be a value of the original Enum.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1480-L1481">Any non-repeatable directives provided must not already apply to the original Enum type.</li> </ol> </section> </section> </section> <section id="sec-Input-Objects" secid="3.10"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L1484"><a href="#sec-Input-Objects">3.10</a>Input Objects</h2> <div class="spec-production" id="InputObjectTypeDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L1486-L1488"> <a href="#InputObjectTypeDefinition" data-name="InputObjectTypeDefinition">InputObjectTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optinput<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#InputFieldsDefinition" data-name="InputFieldsDefinition">InputFieldsDefinition</a></div> <div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optinput<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt{</div> </div> <div class="spec-production" id="InputFieldsDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L1490"> <a href="#InputFieldsDefinition" data-name="InputFieldsDefinition">InputFieldsDefinition</a><div class="spec-rhs">{<a href="#InputValueDefinition" data-name="InputValueDefinition">InputValueDefinition</a>list}</div> </div> Fields may accept arguments to configure their behavior. These inputs are often scalars or enums, but they sometimes need to represent more complex values. A GraphQL Input Object defines a set of input fields; the input fields are either scalars, enums, or other input objects. This allows arguments to accept arbitrarily complex structs. In this example, an Input Object called <code>Point2D</code> describes <code>x</code> and <code>y</code> inputs: <pre id="example-45e4e" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1501-L1506"><a href="#example-45e4e">Example № 79</a><code>input Point2D { x: Float y: Float } </code></pre> <div id="note-7a6d2" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L1508-L1512"> <a href="#note-7a6d2">Note</a> The GraphQL Object type (<a href="#ObjectTypeDefinition" data-name="ObjectTypeDefinition">ObjectTypeDefinition</a>) defined above is inappropriate for re-use here, because Object types can contain fields that define arguments or contain references to interfaces and unions, neither of which is appropriate for use as an input argument. For this reason, input objects have a separate type in the system.</div> <section id="sec-Input-Objects.Circular-References" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1514"><a href="#sec-Input-Objects.Circular-References" title="link to this subsection">Circular References</a></h6> Input Objects are allowed to reference other Input Objects as field types. A circular reference occurs when an Input Object references itself either directly or through referenced Input Objects. Circular references are generally allowed, however they may not be defined as an unbroken chain of Non-Null singular fields. Such Input Objects are invalid because there is no way to provide a legal value for them. This example of a circularly-referenced input type is valid as the field <code>self</code> may be omitted or the value null. <pre id="example-e9cda" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1527-L1532"><a href="#example-e9cda">Example № 80</a><code>input Example { self: Example value: String } </code></pre> This example is also valid as the field <code>self</code> may be an empty List. <pre id="example-2f832" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1536-L1541"><a href="#example-2f832">Example № 81</a><code>input Example { self: [Example!]! value: String } </code></pre> This example of a circularly-referenced input type is invalid as the field <code>self</code> cannot be provided a finite value. <pre id="example-e70c9" class="spec-counter-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1546-L1551"><a href="#example-e70c9">Counter Example № 82</a><code>input Example { value: String self: Example! } </code></pre> This example is also invalid, as there is a non-null singular circular reference via the <code>First.second</code> and <code>Second.first</code> fields. <pre id="example-31c9f" class="spec-counter-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1556-L1566"><a href="#example-31c9f">Counter Example № 83</a><code>input First { second: Second! value: String } input Second { first: First! value: String } </code></pre> </section> <section id="sec-Input-Objects.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1568"><a href="#sec-Input-Objects.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> An input object is never a valid result. Input Object types cannot be the return type of an Object or Interface field. </section> <section id="sec-Input-Objects.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1573"><a href="#sec-Input-Objects.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> The value for an input object should be an input object literal or an unordered map supplied by a variable, otherwise a request error must be raised. In either case, the input object literal or unordered map must not contain any entries with names not defined by a field of this input object type, otherwise a response error must be raised. The result of coercion is an unordered map with an entry for each field both defined by the input object type and for which a value exists. The resulting map is constructed with the following rules: <ul> <li data-source="spec/Section%203%20--%20Type%20System.md#L1585-L1589">If no value is provided for a defined input object field and that field definition provides a default value, the default value should be used. If no default value is provided and the input object field’s type is non-null, an error should be raised. Otherwise, if the field is not required, then no entry is added to the coerced unordered map.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1591-L1594">If the value null was provided for an input object field, and the field’s type is not a non-null type, an entry in the coerced unordered map is given the value null. In other words, there is a semantic difference between the explicitly provided value null versus having not provided a value.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1596-L1598">If a literal value is provided for an input object field, an entry in the coerced unordered map is given the result of coercing that value according to the input coercion rules for the type of that field.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1600-L1605">If a variable is provided for an input object field, the runtime value of that variable must be used. If the runtime value is null and the field type is non-null, a field error must be raised. If no runtime value is provided, the variable definition’s default value should be used. If the variable definition does not provide a default value, the input object field definition’s default value should be used.</li> </ul> Following are examples of input coercion for an input object type with a <code>String</code> field <code>a</code> and a required (non-null) <code>Int!</code> field <code>b</code>: <pre id="example-704b8" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1610-L1615"><a href="#example-704b8">Example № 84</a><code>input ExampleInputObject { a: String b: Int! } </code></pre> <table> <thead> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1617"> <th>Literal Value</th> <th>Variables</th> <th>Coerced Value</th> </tr> </thead> <tbody> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1619"> <td><code>{ a: "abc", b: 123 }</code></td> <td><code>{}</code></td> <td><code>{ a: "abc", b: 123 }</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1620"> <td><code>{ a: null, b: 123 }</code></td> <td><code>{}</code></td> <td><code>{ a: null, b: 123 }</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1621"> <td><code>{ b: 123 }</code></td> <td><code>{}</code></td> <td><code>{ b: 123 }</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1622"> <td><code>{ a: $var, b: 123 }</code></td> <td><code>{ var: null }</code></td> <td><code>{ a: null, b: 123 }</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1623"> <td><code>{ a: $var, b: 123 }</code></td> <td><code>{}</code></td> <td><code>{ b: 123 }</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1624"> <td><code>{ b: $var }</code></td> <td><code>{ var: 123 }</code></td> <td><code>{ b: 123 }</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1625"> <td><code>$var</code></td> <td><code>{ var: { b: 123 } }</code></td> <td><code>{ b: 123 }</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1626"> <td><code>"abc123"</code></td> <td><code>{}</code></td> <td>Error: Incorrect value</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1627"> <td><code>$var</code></td> <td><code>{ var: "abc123" }</code></td> <td>Error: Incorrect value</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1628"> <td><code>{ a: "abc", b: "123" }</code></td> <td><code>{}</code></td> <td>Error: Incorrect value for field <var data-name="b">b</var></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1629"> <td><code>{ a: "abc" }</code></td> <td><code>{}</code></td> <td>Error: Missing required field <var data-name="b">b</var></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1630"> <td><code>{ b: $var }</code></td> <td><code>{}</code></td> <td>Error: Missing required field <var data-name="b">b</var>.</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1631"> <td><code>$var</code></td> <td><code>{ var: { a: "abc" } }</code></td> <td>Error: Missing required field <var data-name="b">b</var></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1632"> <td><code>{ a: "abc", b: null }</code></td> <td><code>{}</code></td> <td>Error: <var data-name="b">b</var> must be non-null.</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1633"> <td><code>{ b: $var }</code></td> <td><code>{ var: null }</code></td> <td>Error: <var data-name="b">b</var> must be non-null.</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1634"> <td><code>{ b: 123, c: "xyz" }</code></td> <td><code>{}</code></td> <td>Error: Unexpected field <var data-name="c">c</var></td> </tr> </tbody> </table> </section> <section id="sec-Input-Objects.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1636"><a href="#sec-Input-Objects.Type-Validation" title="link to this subsection">Type Validation</a></h6> <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1638">An Input Object type must define one or more input fields.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1639-L1645">For each input field of an Input Object type:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1640-L1641">The input field must have a unique name within that Input Object type; no two input fields may share the same name.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1642-L1643">The input field must not have a name which begins with the characters "__" (two underscores).</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1644-L1645">The input field must accept a type where <a href="#IsInputType()" data-name="IsInputType">IsInputType</a>(<var data-name="inputFieldType">inputFieldType</var>) returns true.</li> </ol> </li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1646-L1648">If an Input Object references itself either directly or through referenced Input Objects, at least one of the fields in the chain of references must be either a nullable or a List type.</li> </ol> </section> <section id="sec-Input-Object-Extensions" secid="3.10.1"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L1651"><a href="#sec-Input-Object-Extensions">3.10.1</a>Input Object Extensions</h3> <div class="spec-production" id="InputObjectTypeExtension" data-source="spec/Section%203%20--%20Type%20System.md#L1653-L1655"> <a href="#InputObjectTypeExtension" data-name="InputObjectTypeExtension">InputObjectTypeExtension</a><div class="spec-rhs">extendinput<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#InputFieldsDefinition" data-name="InputFieldsDefinition">InputFieldsDefinition</a></div> <div class="spec-rhs">extendinput<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Const{</div> </div> Input object type extensions are used to represent an input object type which has been extended from some original input object type. For example, this might be used by a GraphQL service which is itself an extension of another GraphQL service. <section id="sec-Input-Object-Extensions.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1661"><a href="#sec-Input-Object-Extensions.Type-Validation" title="link to this subsection">Type Validation</a></h6> Input object type extensions have the potential to be invalid if incorrectly defined. <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1665">The named type must already be defined and must be a Input Object type.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1666">All fields of an Input Object type extension must have unique names.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1667-L1668">All fields of an Input Object type extension must not already be a field of the original Input Object.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1669-L1670">Any non-repeatable directives provided must not already apply to the original Input Object type.</li> </ol> </section> </section> </section> <section id="sec-List" secid="3.11"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L1673"><a href="#sec-List">3.11</a>List</h2> A GraphQL list is a special collection type which declares the type of each item in the List (referred to as the item type of the list). List values are serialized as ordered lists, where each item in the list is serialized as per the item type. To denote that a field uses a List type the item type is wrapped in square brackets like this: <code>pets: [Pet]</code>. Nesting lists is allowed: <code>matrix: [[Int]]</code>. <section id="sec-List.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1683"><a href="#sec-List.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> GraphQL services must return an ordered list as the result of a list type. Each item in the list must be the result of a result coercion of the item type. If a reasonable coercion is not possible it must raise a field error. In particular, if a non-list is returned, the coercion should fail, as this indicates a mismatch in expectations between the type system and the implementation. If a list’s item type is nullable, then errors occurring during preparation or coercion of an individual item in the list must result in a the value null at that position in the list along with a field error added to the response. If a list’s item type is non-null, a field error occurring at an individual item in the list must result in a field error for the entire list. <div id="note-6f554" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L1698-L1699"> <a href="#note-6f554">Note</a> See <a href="#sec-Handling-Field-Errors">Handling Field Errors</a> for more about this behavior.</div> </section> <section id="sec-List.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1701"><a href="#sec-List.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> When expected as an input, list values are accepted only when each item in the list can be accepted by the list’s item type. If the value passed as an input to a list type is not a list and not the null value, then the result of input coercion is a list of size one, where the single item value is the result of input coercion for the list’s item type on the provided value (note this may apply recursively for nested lists). This allows inputs which accept one or many arguments (sometimes referred to as “var args”) to declare their input type as a list while for the common case of a single value, a client can just pass that value directly rather than constructing the list. Following are examples of input coercion with various list types and values: <table> <thead> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1718"> <th>Expected Type</th> <th>Provided Value</th> <th>Coerced Value</th> </tr> </thead> <tbody> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1720"> <td><code>[Int]</code></td> <td><code>[1, 2, 3]</code></td> <td><code>[1, 2, 3]</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1721"> <td><code>[Int]</code></td> <td><code>[1, "b", true]</code></td> <td>Error: Incorrect item value</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1722"> <td><code>[Int]</code></td> <td><code>1</code></td> <td><code>[1]</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1723"> <td><code>[Int]</code></td> <td><code>null</code></td> <td><code>null</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1724"> <td><code>[[Int]]</code></td> <td><code>[[1], [2, 3]]</code></td> <td><code>[[1], [2, 3]]</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1725"> <td><code>[[Int]]</code></td> <td><code>[1, 2, 3]</code></td> <td>Error: Incorrect item value</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1726"> <td><code>[[Int]]</code></td> <td><code>1</code></td> <td><code>[[1]]</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1727"> <td><code>[[Int]]</code></td> <td><code>null</code></td> <td><code>null</code></td> </tr> </tbody> </table> </section> </section> <section id="sec-Non-Null" secid="3.12"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L1730"><a href="#sec-Non-Null">3.12</a>Non-Null</h2> By default, all types in GraphQL are nullable; the null value is a valid response for all of the above types. To declare a type that disallows null, the GraphQL Non-Null type can be used. This type wraps an underlying type, and this type acts identically to that wrapped type, with the exception that null is not a valid response for the wrapping type. A trailing exclamation mark is used to denote a field that uses a Non-Null type like this: <code>name: String!</code>. <section id="sec-Non-Null.Nullable-vs-Optional" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1740"><a href="#sec-Non-Null.Nullable-vs-Optional" title="link to this subsection">Nullable vs. Optional</a></h6> Fields are always optional within the context of a selection set, a field may be omitted and the selection set is still valid. However fields that return Non-Null types will never return the value null if queried. Inputs (such as field arguments), are always optional by default. However a non-null input type is required. In addition to not accepting the value null, it also does not accept omission. For the sake of simplicity nullable types are always optional and non-null types are always required. </section> <section id="sec-Non-Null.Result-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1751"><a href="#sec-Non-Null.Result-Coercion" title="link to this subsection">Result Coercion</a></h6> In all of the above result coercions, null was considered a valid value. To coerce the result of a Non-Null type, the coercion of the wrapped type should be performed. If that result was not null, then the result of coercing the Non-Null type is that result. If that result was null, then a field error must be raised. <div id="note-ad65b" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L1759-L1761"> <a href="#note-ad65b">Note</a> When a field error is raised on a non-null value, the error propagates to the parent field. For more information on this process, see “Errors and Non-Nullability” within the Execution section.</div> </section> <section id="sec-Non-Null.Input-Coercion" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1763"><a href="#sec-Non-Null.Input-Coercion" title="link to this subsection">Input Coercion</a></h6> If an argument or input-object field of a Non-Null type is not provided, is provided with the literal value null, or is provided with a variable that was either not provided a value at runtime, or was provided the value null, then a request error must be raised. If the value provided to the Non-Null type is provided with a literal value other than null, or a Non-Null variable value, it is coerced using the input coercion for the wrapped type. A non-null argument cannot be omitted: <pre id="example-32bbf" class="spec-counter-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1776-L1780"><a href="#example-32bbf">Counter Example № 85</a><code>{ fieldWithNonNullArg } </code></pre> The value null cannot be provided to a non-null argument: <pre id="example-da489" class="spec-counter-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1784-L1788"><a href="#example-da489">Counter Example № 86</a><code>{ fieldWithNonNullArg(nonNullArg: null) } </code></pre> A variable of a nullable type cannot be provided to a non-null argument: <pre id="example-6d129" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1792-L1796"><a href="#example-6d129">Example № 87</a><code>query withNullableVariable($var: String) { fieldWithNonNullArg(nonNullArg: $var) } </code></pre> <div id="note-97a45" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L1798-L1799"> <a href="#note-97a45">Note</a> The Validation section defines providing a nullable variable type to a non-null input type as invalid.</div> </section> <section id="sec-Non-Null.Type-Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1801"><a href="#sec-Non-Null.Type-Validation" title="link to this subsection">Type Validation</a></h6> <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1803">A Non-Null type must not wrap another Non-Null type.</li> </ol> </section> <section id="sec-Combining-List-and-Non-Null" secid="3.12.1"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L1806"><a href="#sec-Combining-List-and-Non-Null">3.12.1</a>Combining List and Non-Null</h3> The List and Non-Null wrapping types can compose, representing more complex types. The rules for result coercion and input coercion of Lists and Non-Null types apply in a recursive fashion. For example if the inner item type of a List is Non-Null (e.g. <code>[T!]</code>), then that List may not contain any null items. However if the inner type of a Non-Null is a List (e.g. <code>[T]!</code>), then null is not accepted however an empty list is accepted. Following are examples of result coercion with various types and values: <table> <thead> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1819"> <th>Expected Type</th> <th>Internal Value</th> <th>Coerced Result</th> </tr> </thead> <tbody> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1821"> <td><code>[Int]</code></td> <td><code>[1, 2, 3]</code></td> <td><code>[1, 2, 3]</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1822"> <td><code>[Int]</code></td> <td><code>null</code></td> <td><code>null</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1823"> <td><code>[Int]</code></td> <td><code>[1, 2, null]</code></td> <td><code>[1, 2, null]</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1824"> <td><code>[Int]</code></td> <td><code>[1, 2, Error]</code></td> <td><code>[1, 2, null]</code> (With logged error)</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1825"> <td><code>[Int]!</code></td> <td><code>[1, 2, 3]</code></td> <td><code>[1, 2, 3]</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1826"> <td><code>[Int]!</code></td> <td><code>null</code></td> <td>Error: Value cannot be null</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1827"> <td><code>[Int]!</code></td> <td><code>[1, 2, null]</code></td> <td><code>[1, 2, null]</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1828"> <td><code>[Int]!</code></td> <td><code>[1, 2, Error]</code></td> <td><code>[1, 2, null]</code> (With logged error)</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1829"> <td><code>[Int!]</code></td> <td><code>[1, 2, 3]</code></td> <td><code>[1, 2, 3]</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1830"> <td><code>[Int!]</code></td> <td><code>null</code></td> <td><code>null</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1831"> <td><code>[Int!]</code></td> <td><code>[1, 2, null]</code></td> <td><code>null</code> (With logged coercion error)</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1832"> <td><code>[Int!]</code></td> <td><code>[1, 2, Error]</code></td> <td><code>null</code> (With logged error)</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1833"> <td><code>[Int!]!</code></td> <td><code>[1, 2, 3]</code></td> <td><code>[1, 2, 3]</code></td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1834"> <td><code>[Int!]!</code></td> <td><code>null</code></td> <td>Error: Value cannot be null</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1835"> <td><code>[Int!]!</code></td> <td><code>[1, 2, null]</code></td> <td>Error: Item cannot be null</td> </tr> <tr data-source="spec/Section%203%20--%20Type%20System.md#L1836"> <td><code>[Int!]!</code></td> <td><code>[1, 2, Error]</code></td> <td>Error: Error occurred in item</td> </tr> </tbody> </table> </section> </section> <section id="sec-Type-System.Directives" secid="3.13"> <h2 data-source="spec/Section%203%20--%20Type%20System.md#L1839"><a href="#sec-Type-System.Directives">3.13</a>Directives</h2> <div class="spec-production" id="DirectiveDefinition" data-source="spec/Section%203%20--%20Type%20System.md#L1841"> <a href="#DirectiveDefinition" data-name="DirectiveDefinition">DirectiveDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optdirective@<a href="#Name" data-name="Name">Name</a><a href="#ArgumentsDefinition" data-name="ArgumentsDefinition">ArgumentsDefinition</a>optrepeatableopton<a href="#DirectiveLocations" data-name="DirectiveLocations">DirectiveLocations</a></div> </div> <div class="spec-production" id="DirectiveLocations" data-source="spec/Section%203%20--%20Type%20System.md#L1843-L1845"> <a href="#DirectiveLocations" data-name="DirectiveLocations">DirectiveLocations</a><div class="spec-rhs"><a href="#DirectiveLocations" data-name="DirectiveLocations">DirectiveLocations</a>|<a href="#DirectiveLocation" data-name="DirectiveLocation">DirectiveLocation</a></div> <div class="spec-rhs">|opt<a href="#DirectiveLocation" data-name="DirectiveLocation">DirectiveLocation</a></div> </div> <div class="spec-production" id="DirectiveLocation" data-source="spec/Section%203%20--%20Type%20System.md#L1847-L1849"> <a href="#DirectiveLocation" data-name="DirectiveLocation">DirectiveLocation</a><div class="spec-rhs"><a href="#ExecutableDirectiveLocation" data-name="ExecutableDirectiveLocation">ExecutableDirectiveLocation</a></div> <div class="spec-rhs"><a href="#TypeSystemDirectiveLocation" data-name="TypeSystemDirectiveLocation">TypeSystemDirectiveLocation</a></div> </div> <div class="spec-production" id="ExecutableDirectiveLocation" data-source="spec/Section%203%20--%20Type%20System.md#L1851-L1859"> <a href="#ExecutableDirectiveLocation" data-name="ExecutableDirectiveLocation">ExecutableDirectiveLocation</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">QUERY</td></tr> <tr> <td class="spec-rhs">MUTATION</td></tr> <tr> <td class="spec-rhs">SUBSCRIPTION</td></tr> <tr> <td class="spec-rhs">FIELD</td></tr> <tr> <td class="spec-rhs">FRAGMENT_DEFINITION</td></tr> <tr> <td class="spec-rhs">FRAGMENT_SPREAD</td></tr> <tr> <td class="spec-rhs">INLINE_FRAGMENT</td></tr> <tr> <td class="spec-rhs">VARIABLE_DEFINITION</td></tr> </table></div></div> </div> <div class="spec-production" id="TypeSystemDirectiveLocation" data-source="spec/Section%203%20--%20Type%20System.md#L1861-L1872"> <a href="#TypeSystemDirectiveLocation" data-name="TypeSystemDirectiveLocation">TypeSystemDirectiveLocation</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">SCHEMA</td></tr> <tr> <td class="spec-rhs">SCALAR</td></tr> <tr> <td class="spec-rhs">OBJECT</td></tr> <tr> <td class="spec-rhs">FIELD_DEFINITION</td></tr> <tr> <td class="spec-rhs">ARGUMENT_DEFINITION</td></tr> <tr> <td class="spec-rhs">INTERFACE</td></tr> <tr> <td class="spec-rhs">UNION</td></tr> <tr> <td class="spec-rhs">ENUM</td></tr> <tr> <td class="spec-rhs">ENUM_VALUE</td></tr> <tr> <td class="spec-rhs">INPUT_OBJECT</td></tr> <tr> <td class="spec-rhs">INPUT_FIELD_DEFINITION</td></tr> </table></div></div> </div> A GraphQL schema describes directives which are used to annotate various parts of a GraphQL document as an indicator that they should be evaluated differently by a validator, executor, or client tool such as a code generator. <section id="sec-Type-System.Directives.Built-in-Directives" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1878"><a href="#sec-Type-System.Directives.Built-in-Directives" title="link to this subsection">Built-in Directives</a></h6> A <dfn id="built-in-directive"><a href="#built-in-directive" data-name="built-in-directive">built-in directive</a></dfn> is any directive defined within this specification. GraphQL implementations should provide the <code>@skip</code> and <code>@include</code> directives. GraphQL implementations that support the type system definition language must provide the <code>@deprecated</code> directive if representing deprecated portions of the schema. GraphQL implementations that support the type system definition language should provide the <code>@specifiedBy</code> directive if representing custom scalar definitions. When representing a GraphQL schema using the type system definition language any <a href="#built-in-directive" data-name="built-in-directive">built-in directive</a> may be omitted for brevity. When introspecting a GraphQL service all provided directives, including any <a href="#built-in-directive" data-name="built-in-directive">built-in directive</a>, must be included in the set of returned directives. </section> <section id="sec-Type-System.Directives.Custom-Directives" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1898"><a href="#sec-Type-System.Directives.Custom-Directives" title="link to this subsection">Custom Directives</a></h6> GraphQL services and client tooling may provide any additional <dfn id="custom-directive"><a href="#custom-directive" data-name="custom-directive">custom directive</a></dfn> beyond those defined in this document. Directives are the preferred way to extend GraphQL with custom or experimental behavior. <div id="note-39239" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L1904-L1911"> <a href="#note-39239">Note</a> When defining a <a href="#custom-directive" data-name="custom-directive">custom directive</a>, it is recommended to prefix the directive’s name to make its scope of usage clear and to prevent a collision with <a href="#built-in-directive" data-name="built-in-directive">built-in directive</a> which may be specified by future versions of this document (which will not include <code>_</code> in their name). For example, a <a href="#custom-directive" data-name="custom-directive">custom directive</a> used by Facebook’s GraphQL service should be named <code>@fb_auth</code> instead of <code>@auth</code>. This is especially recommended for proposed additions to this specification which can change during the <a href="https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md">RFC process</a>. For example a work in progress version of <code>@live</code> should be named <code>@rfc_live</code>.</div> Directives must only be used in the locations they are declared to belong in. In this example, a directive is defined which can be used to annotate a field: <pre id="example-060af" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1916-L1922"><a href="#example-060af">Example № 88</a><code>directive @example on FIELD fragment SomeFragment on SomeType { field @example } </code></pre> Directive locations may be defined with an optional leading <code>|</code> character to aid formatting when representing a longer list of possible locations: <pre id="example-79697" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1927-L1932"><a href="#example-79697">Example № 89</a><code>directive @example on | FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT </code></pre> Directives can also be used to annotate the type system definition language as well, which can be a useful tool for supplying additional metadata in order to generate GraphQL execution services, produce client generated runtime code, or many other useful extensions of the GraphQL semantics. In this example, the directive <code>@example</code> annotates field and argument definitions: <pre id="example-c3a06" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1941-L1947"><a href="#example-c3a06">Example № 90</a><code>directive @example on FIELD_DEFINITION | ARGUMENT_DEFINITION type SomeType { field(arg: Int @example): String @example } </code></pre> A directive may be defined as repeatable by including the “repeatable” keyword. Repeatable directives are often useful when the same directive should be used with different arguments at a single location, especially in cases where additional information needs to be provided to a type or schema extension via a directive: <pre id="example-67869" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1955-L1963"><a href="#example-67869">Example № 91</a><code>directive @delegateField(name: String!) repeatable on OBJECT | INTERFACE type Book @delegateField(name: "pageCount") @delegateField(name: "author") { id: ID! } extend type Book @delegateField(name: "index") </code></pre> While defining a directive, it must not reference itself directly or indirectly: <pre id="example-79945" class="spec-counter-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1967-L1969"><a href="#example-79945">Counter Example № 92</a><code>directive @invalidExample(arg: String @invalidExample) on ARGUMENT_DEFINITION </code></pre> <div id="note-921fb" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L1971-L1972"> <a href="#note-921fb">Note</a> The order in which directives appear may be significant, including repeatable directives.</div> </section> <section id="sec-Type-System.Directives.Validation" class="subsec"> <h6 data-source="spec/Section%203%20--%20Type%20System.md#L1974"><a href="#sec-Type-System.Directives.Validation" title="link to this subsection">Validation</a></h6> <ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1976-L1977">A directive definition must not contain the use of a directive which references itself directly.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1978-L1980">A directive definition must not contain the use of a directive which references itself indirectly by referencing a Type or Directive which transitively includes a reference to this directive.</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1981-L1982">The directive must not have a name which begins with the characters "__" (two underscores).</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1983-L1987">For each argument of the directive:<ol> <li data-source="spec/Section%203%20--%20Type%20System.md#L1984-L1985">The argument must not have a name which begins with the characters "__" (two underscores).</li> <li data-source="spec/Section%203%20--%20Type%20System.md#L1986-L1987">The argument must accept a type where <a href="#IsInputType()" data-name="IsInputType">IsInputType</a>(<var data-name="argumentType">argumentType</var>) returns true.</li> </ol> </li> </ol> </section> <section id="sec--skip" secid="3.13.1"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L1989"><a href="#sec--skip">3.13.1</a>@skip</h3> <pre data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L1991-L1993"><code>directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT </code></pre> The <code>@skip</code> <a href="#built-in-directive" data-name="built-in-directive">built-in directive</a> may be provided for fields, fragment spreads, and inline fragments, and allows for conditional exclusion during execution as described by the <code>if</code> argument. In this example <code>experimentalField</code> will only be queried if the variable <code>$someTest</code> has the value <code>false</code>. <pre id="example-cb6b7" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L2002-L2006"><a href="#example-cb6b7">Example № 93</a><code>query myQuery($someTest: Boolean!) { experimentalField @skip(if: $someTest) } </code></pre> </section> <section id="sec--include" secid="3.13.2"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L2009"><a href="#sec--include">3.13.2</a>@include</h3> <pre data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L2011-L2013"><code>directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT </code></pre> The <code>@include</code> <a href="#built-in-directive" data-name="built-in-directive">built-in directive</a> may be provided for fields, fragment spreads, and inline fragments, and allows for conditional inclusion during execution as described by the <code>if</code> argument. In this example <code>experimentalField</code> will only be queried if the variable <code>$someTest</code> has the value <code>true</code> <pre id="example-aa3a0" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L2022-L2026"><a href="#example-aa3a0">Example № 94</a><code>query myQuery($someTest: Boolean!) { experimentalField @include(if: $someTest) } </code></pre> <div id="note-f3059" class="spec-note" data-source="spec/Section%203%20--%20Type%20System.md#L2028-L2033"> <a href="#note-f3059">Note</a> Neither <code>@skip</code> nor <code>@include</code> has precedence over the other. In the case that both the <code>@skip</code> and <code>@include</code> directives are provided on the same field or fragment, it must be queried only if the <code>@skip</code> condition is false and the <code>@include</code> condition is true. Stated conversely, the field or fragment must not be queried if either the <code>@skip</code> condition is true or the <code>@include</code> condition is false.</div> </section> <section id="sec--deprecated" secid="3.13.3"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L2036"><a href="#sec--deprecated">3.13.3</a>@deprecated</h3> <pre data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L2038-L2042"><code>directive @deprecated( reason: String = "No longer supported" ) on FIELD_DEFINITION | ENUM_VALUE </code></pre> The <code>@deprecated</code> <a href="#built-in-directive" data-name="built-in-directive">built-in directive</a> is used within the type system definition language to indicate deprecated portions of a GraphQL service’s schema, such as deprecated fields on a type or deprecated enum values. Deprecations include a reason for why it is deprecated, which is formatted using Markdown syntax (as specified by <a href="https://commonmark.org/">CommonMark</a>). In this example type definition, <code>oldField</code> is deprecated in favor of using <code>newField</code>. <pre id="example-d0cdc" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L2054-L2059"><a href="#example-d0cdc">Example № 95</a><code>type ExampleType { newField: String oldField: String @deprecated(reason: "Use `newField`.") } </code></pre> </section> <section id="sec--specifiedBy" secid="3.13.4"> <h3 data-source="spec/Section%203%20--%20Type%20System.md#L2062"><a href="#sec--specifiedBy">3.13.4</a>@specifiedBy</h3> <pre data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L2064-L2066"><code>directive @specifiedBy(url: String!) on SCALAR </code></pre> The <code>@specifiedBy</code> <a href="#built-in-directive" data-name="built-in-directive">built-in directive</a> is used within the type system definition language to provide a <a href="#scalar-specification-url" data-name="scalar-specification-url">scalar specification URL</a> for specifying the behavior of <a href="#sec-Scalars.Custom-Scalars">custom scalar types</a>. The URL should point to a human-readable specification of the data format, serialization, and coercion rules. It must not appear on built-in scalar types. In this example, a custom scalar type for <code>UUID</code> is defined with a URL pointing to the relevant IETF specification. <pre id="example-e5b0d" class="spec-example" data-language="graphql" data-source="spec/Section%203%20--%20Type%20System.md#L2077-L2079"><a href="#example-e5b0d">Example № 96</a><code>scalar UUID @specifiedBy(url: "https://tools.ietf.org/html/rfc4122") </code></pre> </section> </section> </section> <section id="sec-Introspection" secid="4"> <h1 data-source="spec/Section%204%20--%20Introspection.md#L1"><a href="#sec-Introspection">4</a>Introspection</h1> A GraphQL service supports introspection over its schema. This schema is queried using GraphQL itself, creating a powerful platform for tool-building. Take an example request for a trivial app. In this case there is a User type with three fields: id, name, and birthday. For example, given a service with the following type definition: <pre id="example-3005e" class="spec-example" data-language="graphql" data-source="spec/Section%204%20--%20Introspection.md#L11-L17"><a href="#example-3005e">Example № 97</a><code>type User { id: String name: String birthday: Date } </code></pre> A request containing the operation: <pre id="example-2efd3" class="spec-example" data-language="graphql" data-source="spec/Section%204%20--%20Introspection.md#L21-L33"><a href="#example-2efd3">Example № 98</a><code>{ __type(name: "User") { name fields { name type { name } } } } </code></pre> would produce the result: <pre id="example-47d72" class="spec-example" data-language="json" data-source="spec/Section%204%20--%20Introspection.md#L37-L57"><a href="#example-47d72">Example № 99</a><code>{ "__type": { "name": "User", "fields": [ { "name": "id", "type": { "name": "String" } }, { "name": "name", "type": { "name": "String" } }, { "name": "birthday", "type": { "name": "Date" } } ] } } </code></pre> <section id="sec-Introspection.Reserved-Names" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L59"><a href="#sec-Introspection.Reserved-Names" title="link to this subsection">Reserved Names</a></h6> Types and fields required by the GraphQL introspection system that are used in the same context as user-defined types and fields are prefixed with "__" two underscores. This in order to avoid naming collisions with user-defined GraphQL types. Otherwise, any <a href="#Name" data-name="Name">Name</a> within a GraphQL type system must not start with two underscores "__". </section> <section id="sec-Type-Name-Introspection" secid="4.1"> <h2 data-source="spec/Section%204%20--%20Introspection.md#L69"><a href="#sec-Type-Name-Introspection">4.1</a>Type Name Introspection</h2> GraphQL supports type name introspection within any selection set in an operation, with the single exception of selections at the root of a subscription operation. Type name introspection is accomplished via the meta-field <code>__typename: String!</code> on any Object, Interface, or Union. It returns the name of the concrete Object type at that point during execution. This is most often used when querying against Interface or Union types to identify which actual Object type of the possible types has been returned. As a meta-field, <code>__typename</code> is implicit and does not appear in the fields list in any defined type. <div id="note-bc213" class="spec-note" data-source="spec/Section%204%20--%20Introspection.md#L83-L84"> <a href="#note-bc213">Note</a> <code>__typename</code> may not be included as a root field in a subscription operation.</div> </section> <section id="sec-Schema-Introspection" secid="4.2"> <h2 data-source="spec/Section%204%20--%20Introspection.md#L86"><a href="#sec-Schema-Introspection">4.2</a>Schema Introspection</h2> The schema introspection system is accessible from the meta-fields <code>__schema</code> and <code>__type</code> which are accessible from the type of the root of a query operation. <pre data-language="graphql" data-source="spec/Section%204%20--%20Introspection.md#L92-L95"><code>__schema: __Schema! __type(name: String!): __Type </code></pre> Like all meta-fields, these are implicit and do not appear in the fields list in the root type of the query operation. <section id="sec-Schema-Introspection.First-Class-Documentation" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L100"><a href="#sec-Schema-Introspection.First-Class-Documentation" title="link to this subsection">First Class Documentation</a></h6> All types in the introspection system provide a <code>description</code> field of type <code>String</code> to allow type designers to publish documentation in addition to capabilities. A GraphQL service may return the <code>description</code> field using Markdown syntax (as specified by <a href="https://commonmark.org/">CommonMark</a>). Therefore it is recommended that any tool that displays <code>description</code> use a CommonMark-compliant Markdown renderer. </section> <section id="sec-Schema-Introspection.Deprecation" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L109"><a href="#sec-Schema-Introspection.Deprecation" title="link to this subsection">Deprecation</a></h6> To support the management of backwards compatibility, GraphQL fields and enum values can indicate whether or not they are deprecated (<code>isDeprecated: Boolean</code>) and a description of why it is deprecated (<code>deprecationReason: String</code>). Tools built using GraphQL introspection should respect deprecation by discouraging deprecated use through information hiding or developer-facing warnings. </section> <section id="sec-Schema-Introspection.Schema-Introspection-Schema" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L119"><a href="#sec-Schema-Introspection.Schema-Introspection-Schema" title="link to this subsection">Schema Introspection Schema</a></h6> The schema introspection system is itself represented as a GraphQL schema. Below are the full set of type system definitions providing schema introspection, which are fully defined in the sections below. <pre data-language="graphql" data-source="spec/Section%204%20--%20Introspection.md#L125-L218"><code>type __Schema { description: String types: [__Type!]! queryType: __Type! mutationType: __Type subscriptionType: __Type directives: [__Directive!]! } type __Type { kind: __TypeKind! name: String description: String # must be non-null for OBJECT and INTERFACE, otherwise null. fields(includeDeprecated: Boolean = false): [__Field!] # must be non-null for OBJECT and INTERFACE, otherwise null. interfaces: [__Type!] # must be non-null for INTERFACE and UNION, otherwise null. possibleTypes: [__Type!] # must be non-null for ENUM, otherwise null. enumValues(includeDeprecated: Boolean = false): [__EnumValue!] # must be non-null for INPUT_OBJECT, otherwise null. inputFields: [__InputValue!] # must be non-null for NON_NULL and LIST, otherwise null. ofType: __Type # may be non-null for custom SCALAR, otherwise null. specifiedByURL: String } enum __TypeKind { SCALAR OBJECT INTERFACE UNION ENUM INPUT_OBJECT LIST NON_NULL } type __Field { name: String! description: String args: [__InputValue!]! type: __Type! isDeprecated: Boolean! deprecationReason: String } type __InputValue { name: String! description: String type: __Type! defaultValue: String } type __EnumValue { name: String! description: String isDeprecated: Boolean! deprecationReason: String } type __Directive { name: String! description: String locations: [__DirectiveLocation!]! args: [__InputValue!]! isRepeatable: Boolean! } enum __DirectiveLocation { QUERY MUTATION SUBSCRIPTION FIELD FRAGMENT_DEFINITION FRAGMENT_SPREAD INLINE_FRAGMENT VARIABLE_DEFINITION SCHEMA SCALAR OBJECT FIELD_DEFINITION ARGUMENT_DEFINITION INTERFACE UNION ENUM ENUM_VALUE INPUT_OBJECT INPUT_FIELD_DEFINITION } </code></pre> </section> <section id="sec-The-__Schema-Type" secid="4.2.1"> <h3 data-source="spec/Section%204%20--%20Introspection.md#L220"><a href="#sec-The-__Schema-Type">4.2.1</a>The __Schema Type</h3> The <code>__Schema</code> type is returned from the <code>__schema</code> meta-field and provides all information about the schema of a GraphQL service. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L227"><code>description</code> may return a String or null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L228"><code>queryType</code> is the root type of a query operation.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L229-L230"><code>mutationType</code> is the root type of a mutation operation, if supported. Otherwise null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L231-L232"><code>subscriptionType</code> is the root type of a subscription operation, if supported. Otherwise null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L233-L235"><code>types</code> must return the set of all named types contained within this schema. Any named type which can be found through a field of any introspection type must be included in this set.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L236-L237"><code>directives</code> must return the set of all directives available within this schema including all built-in directives.</li> </ul> </section> <section id="sec-The-__Type-Type" secid="4.2.2"> <h3 data-source="spec/Section%204%20--%20Introspection.md#L240"><a href="#sec-The-__Type-Type">4.2.2</a>The __Type Type</h3> <code>__Type</code> is at the core of the type introspection system, it represents all types in the system: both named types (e.g. Scalars and Object types) and type modifiers (e.g. List and Non-Null types). Type modifiers are used to modify the type presented in the field <code>ofType</code>. This modified type may recursively be a modified type, representing lists, non-nullables, and combinations thereof, ultimately modifying a named type. There are several different kinds of type. In each kind, different fields are actually valid. All possible kinds are listed in the <code>__TypeKind</code> enum. Each sub-section below defines the expected fields of <code>__Type</code> given each possible value of the <code>__TypeKind</code> enum: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L256">"SCALAR"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L257">"OBJECT"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L258">"INTERFACE"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L259">"UNION"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L260">"ENUM"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L261">"INPUT_OBJECT"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L262">"LIST"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L263">"NON_NULL"</li> </ul> <section id="sec-The-__Type-Type.Scalar" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L265"><a href="#sec-The-__Type-Type.Scalar" title="link to this subsection">Scalar</a></h6> Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields. Also represents <a href="#sec-Scalars.Custom-Scalars">Custom scalars</a> which may provide <code>specifiedByURL</code> as a <a href="#scalar-specification-url" data-name="scalar-specification-url">scalar specification URL</a>. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L274"><code>kind</code> must return <code>__TypeKind.SCALAR</code>.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L275"><code>name</code> must return a String.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L276"><code>description</code> may return a String or null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L277-L278"><code>specifiedByURL</code> may return a String (in the form of a URL) for custom scalars, otherwise must be null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L279">All other fields must return null.</li> </ul> </section> <section id="sec-The-__Type-Type.Object" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L282"><a href="#sec-The-__Type-Type.Object" title="link to this subsection">Object</a></h6> Object types represent concrete instantiations of sets of fields. The introspection types (e.g. <code>__Type</code>, <code>__Field</code>, etc) are examples of objects. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L289"><code>kind</code> must return <code>__TypeKind.OBJECT</code>.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L290"><code>name</code> must return a String.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L291"><code>description</code> may return a String or null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L292-L294"><code>fields</code> must return the set of fields that can be selected for this type.<ul> <li data-source="spec/Section%204%20--%20Introspection.md#L293-L294">Accepts the argument <code>includeDeprecated</code> which defaults to false. If true, deprecated fields are also returned.</li> </ul> </li> <li data-source="spec/Section%204%20--%20Introspection.md#L295-L296"><code>interfaces</code> must return the set of interfaces that an object implements (if none, <code>interfaces</code> must return the empty set).</li> <li data-source="spec/Section%204%20--%20Introspection.md#L297">All other fields must return null.</li> </ul> </section> <section id="sec-The-__Type-Type.Union" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L300"><a href="#sec-The-__Type-Type.Union" title="link to this subsection">Union</a></h6> Unions are an abstract type where no common fields are declared. The possible types of a union are explicitly listed out in <code>possibleTypes</code>. Types can be made parts of unions without modification of that type. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L308"><code>kind</code> must return <code>__TypeKind.UNION</code>.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L309"><code>name</code> must return a String.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L310"><code>description</code> may return a String or null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L311-L312"><code>possibleTypes</code> returns the list of types that can be represented within this union. They must be object types.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L313">All other fields must return null.</li> </ul> </section> <section id="sec-The-__Type-Type.Interface" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L316"><a href="#sec-The-__Type-Type.Interface" title="link to this subsection">Interface</a></h6> Interfaces are an abstract type where there are common fields declared. Any type that implements an interface must define all the fields with names and types exactly matching. The implementations of this interface are explicitly listed out in <code>possibleTypes</code>. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L325"><code>kind</code> must return <code>__TypeKind.INTERFACE</code>.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L326"><code>name</code> must return a String.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L327"><code>description</code> may return a String or null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L328-L330"><code>fields</code> must return the set of fields required by this interface.<ul> <li data-source="spec/Section%204%20--%20Introspection.md#L329-L330">Accepts the argument <code>includeDeprecated</code> which defaults to false. If true, deprecated fields are also returned.</li> </ul> </li> <li data-source="spec/Section%204%20--%20Introspection.md#L331-L332"><code>interfaces</code> must return the set of interfaces that an object implements (if none, <code>interfaces</code> must return the empty set).</li> <li data-source="spec/Section%204%20--%20Introspection.md#L333-L334"><code>possibleTypes</code> returns the list of types that implement this interface. They must be object types.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L335">All other fields must return null.</li> </ul> </section> <section id="sec-The-__Type-Type.Enum" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L338"><a href="#sec-The-__Type-Type.Enum" title="link to this subsection">Enum</a></h6> Enums are special scalars that can only have a defined set of values. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L344"><code>kind</code> must return <code>__TypeKind.ENUM</code>.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L345"><code>name</code> must return a String.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L346"><code>description</code> may return a String or null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L347-L350"><code>enumValues</code> must return the set of enum values as a list of <code>__EnumValue</code>. There must be at least one and they must have unique names.<ul> <li data-source="spec/Section%204%20--%20Introspection.md#L349-L350">Accepts the argument <code>includeDeprecated</code> which defaults to false. If true, deprecated enum values are also returned.</li> </ul> </li> <li data-source="spec/Section%204%20--%20Introspection.md#L351">All other fields must return null.</li> </ul> </section> <section id="sec-The-__Type-Type.Input-Object" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L354"><a href="#sec-The-__Type-Type.Input-Object" title="link to this subsection">Input Object</a></h6> Input objects are composite types defined as a list of named input values. They are only used as inputs to arguments and variables and cannot be a field return type. For example the input object <code>Point</code> could be defined as: <pre id="example-a0e6d" class="spec-example" data-language="graphql" data-source="spec/Section%204%20--%20Introspection.md#L362-L367"><a href="#example-a0e6d">Example № 100</a><code>input Point { x: Int y: Int } </code></pre> Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L371"><code>kind</code> must return <code>__TypeKind.INPUT_OBJECT</code>.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L372"><code>name</code> must return a String.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L373"><code>description</code> may return a String or null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L374"><code>inputFields</code> must return the set of input fields as a list of <code>__InputValue</code>.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L375">All other fields must return null.</li> </ul> </section> <section id="sec-The-__Type-Type.List" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L378"><a href="#sec-The-__Type-Type.List" title="link to this subsection">List</a></h6> Lists represent sequences of values in GraphQL. A List type is a type modifier: it wraps another type instance in the <code>ofType</code> field, which defines the type of each item in the list. The modified type in the <code>ofType</code> field may itself be a modified type, allowing the representation of Lists of Lists, or Lists of Non-Nulls. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L389"><code>kind</code> must return <code>__TypeKind.LIST</code>.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L390"><code>ofType</code> must return a type of any kind.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L391">All other fields must return null.</li> </ul> </section> <section id="sec-The-__Type-Type.Non-Null" class="subsec"> <h6 data-source="spec/Section%204%20--%20Introspection.md#L394"><a href="#sec-The-__Type-Type.Non-Null" title="link to this subsection">Non-Null</a></h6> GraphQL types are nullable. The value null is a valid response for field type. A Non-Null type is a type modifier: it wraps another type instance in the <code>ofType</code> field. Non-null types do not allow null as a response, and indicate required inputs for arguments and input object fields. The modified type in the <code>ofType</code> field may itself be a modified List type, allowing the representation of Non-Null of Lists. However it must not be a modified Non-Null type to avoid a redundant Non-Null of Non-Null. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L408"><code>kind</code> must return <code>__TypeKind.NON_NULL</code>.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L409"><code>ofType</code> must return a type of any kind except Non-Null.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L410">All other fields must return null.</li> </ul> </section> </section> <section id="sec-The-__Field-Type" secid="4.2.3"> <h3 data-source="spec/Section%204%20--%20Introspection.md#L413"><a href="#sec-The-__Field-Type">4.2.3</a>The __Field Type</h3> The <code>__Field</code> type represents each field in an Object or Interface type. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L419"><code>name</code> must return a String</li> <li data-source="spec/Section%204%20--%20Introspection.md#L420"><code>description</code> may return a String or null</li> <li data-source="spec/Section%204%20--%20Introspection.md#L421-L422"><code>args</code> returns a List of <code>__InputValue</code> representing the arguments this field accepts.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L423-L424"><code>type</code> must return a <code>__Type</code> that represents the type of value returned by this field.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L425-L426"><code>isDeprecated</code> returns true if this field should no longer be used, otherwise false.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L427"><code>deprecationReason</code> optionally provides a reason why this field is deprecated.</li> </ul> </section> <section id="sec-The-__InputValue-Type" secid="4.2.4"> <h3 data-source="spec/Section%204%20--%20Introspection.md#L430"><a href="#sec-The-__InputValue-Type">4.2.4</a>The __InputValue Type</h3> The <code>__InputValue</code> type represents field and directive arguments as well as the <code>inputFields</code> of an input object. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L437"><code>name</code> must return a String</li> <li data-source="spec/Section%204%20--%20Introspection.md#L438"><code>description</code> may return a String or null</li> <li data-source="spec/Section%204%20--%20Introspection.md#L439-L440"><code>type</code> must return a <code>__Type</code> that represents the type this input value expects.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L441-L443"><code>defaultValue</code> may return a String encoding (using the GraphQL language) of the default value used by this input value in the condition a value is not provided at runtime. If this input value has no default value, returns null.</li> </ul> </section> <section id="sec-The-__EnumValue-Type" secid="4.2.5"> <h3 data-source="spec/Section%204%20--%20Introspection.md#L445"><a href="#sec-The-__EnumValue-Type">4.2.5</a>The __EnumValue Type</h3> The <code>__EnumValue</code> type represents one of possible values of an enum. Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L451"><code>name</code> must return a String</li> <li data-source="spec/Section%204%20--%20Introspection.md#L452"><code>description</code> may return a String or null</li> <li data-source="spec/Section%204%20--%20Introspection.md#L453-L454"><code>isDeprecated</code> returns true if this enum value should no longer be used, otherwise false.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L455"><code>deprecationReason</code> optionally provides a reason why this enum value is deprecated.</li> </ul> </section> <section id="sec-The-__Directive-Type" secid="4.2.6"> <h3 data-source="spec/Section%204%20--%20Introspection.md#L457"><a href="#sec-The-__Directive-Type">4.2.6</a>The __Directive Type</h3> The <code>__Directive</code> type represents a directive that a service supports. This includes both any <a href="#built-in-directive" data-name="built-in-directive">built-in directive</a> and any <a href="#custom-directive" data-name="custom-directive">custom directive</a>. Individual directives may only be used in locations that are explicitly supported. All possible locations are listed in the <code>__DirectiveLocation</code> enum: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L466">"QUERY"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L467">"MUTATION"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L468">"SUBSCRIPTION"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L469">"FIELD"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L470">"FRAGMENT_DEFINITION"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L471">"FRAGMENT_SPREAD"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L472">"INLINE_FRAGMENT"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L473">"VARIABLE_DEFINITION"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L474">"SCHEMA"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L475">"SCALAR"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L476">"OBJECT"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L477">"FIELD_DEFINITION"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L478">"ARGUMENT_DEFINITION"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L479">"INTERFACE"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L480">"UNION"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L481">"ENUM"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L482">"ENUM_VALUE"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L483">"INPUT_OBJECT"</li> <li data-source="spec/Section%204%20--%20Introspection.md#L484">"INPUT_FIELD_DEFINITION"</li> </ul> Fields: <ul> <li data-source="spec/Section%204%20--%20Introspection.md#L488"><code>name</code> must return a String</li> <li data-source="spec/Section%204%20--%20Introspection.md#L489"><code>description</code> may return a String or null</li> <li data-source="spec/Section%204%20--%20Introspection.md#L490-L491"><code>locations</code> returns a List of <code>__DirectiveLocation</code> representing the valid locations this directive may be placed.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L492-L493"><code>args</code> returns a List of <code>__InputValue</code> representing the arguments this directive accepts.</li> <li data-source="spec/Section%204%20--%20Introspection.md#L494-L496"><code>isRepeatable</code> must return a Boolean that indicates if the directive may be used repeatedly at a single location. </li> </ul> </section> </section> </section> <section id="sec-Validation" secid="5"> <h1 data-source="spec/Section%205%20--%20Validation.md#L1"><a href="#sec-Validation">5</a>Validation</h1> GraphQL does not just verify if a request is syntactically correct, but also ensures that it is unambiguous and mistake-free in the context of a given GraphQL schema. An invalid request is still technically executable, and will always produce a stable result as defined by the algorithms in the Execution section, however that result may be ambiguous, surprising, or unexpected relative to a request containing validation errors, so execution should only occur for valid requests. Typically validation is performed in the context of a request immediately before execution, however a GraphQL service may execute a request without explicitly validating it if that exact same request is known to have been validated before. For example: the request may be validated during development, provided it does not later change, or a service may validate a request once and memoize the result to avoid validating the same request again in the future. Any client-side or development-time tool should report validation errors and not allow the formulation or execution of requests known to be invalid at that given point in time. <section id="sec-Validation.Type-system-evolution" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L22"><a href="#sec-Validation.Type-system-evolution" title="link to this subsection">Type system evolution</a></h6> As GraphQL type system schema evolves over time by adding new types and new fields, it is possible that a request which was previously valid could later become invalid. Any change that can cause a previously valid request to become invalid is considered a breaking change. GraphQL services and schema maintainers are encouraged to avoid breaking changes, however in order to be more resilient to these breaking changes, sophisticated GraphQL systems may still allow for the execution of requests which at some point were known to be free of any validation errors, and have not changed since. </section> <section id="sec-Validation.Examples" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L33"><a href="#sec-Validation.Examples" title="link to this subsection">Examples</a></h6> For this section of this schema, we will assume the following type system in order to demonstrate examples: <pre id="example-19f2a" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L38-L90"><a href="#example-19f2a">Example № 101</a><code>type Query { dog: Dog } enum DogCommand { SIT DOWN HEEL } type Dog implements Pet { name: String! nickname: String barkVolume: Int doesKnowCommand(dogCommand: DogCommand!): Boolean! isHouseTrained(atOtherHomes: Boolean): Boolean! owner: Human } interface Sentient { name: String! } interface Pet { name: String! } type Alien implements Sentient { name: String! homePlanet: String } type Human implements Sentient { name: String! pets: [Pet!] } enum CatCommand { JUMP } type Cat implements Pet { name: String! nickname: String doesKnowCommand(catCommand: CatCommand!): Boolean! meowVolume: Int } union CatOrDog = Cat | Dog union DogOrHuman = Dog | Human union HumanOrAlien = Human | Alien </code></pre> </section> <section id="sec-Documents" secid="5.1"> <h2 data-source="spec/Section%205%20--%20Validation.md#L93"><a href="#sec-Documents">5.1</a>Documents</h2> <section id="sec-Executable-Definitions" secid="5.1.1"> <h3 data-source="spec/Section%205%20--%20Validation.md#L95"><a href="#sec-Executable-Definitions">5.1.1</a>Executable Definitions</h3> <section id="sec-Executable-Definitions.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L97"><a href="#sec-Executable-Definitions.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L99">For each definition <var data-name="definition">definition</var> in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L100-L101"><var data-name="definition">definition</var> must be <a href="#ExecutableDefinition" data-name="ExecutableDefinition">ExecutableDefinition</a> (it must not be <a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a>).</li> </ul> </section> <section id="sec-Executable-Definitions.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L103"><a href="#sec-Executable-Definitions.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> GraphQL execution will only consider the executable definitions Operation and Fragment. Type system definitions and extensions are not executable, and are not considered during execution. To avoid ambiguity, a document containing <a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a> is invalid for execution. GraphQL documents not intended to be directly executed may include <a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a>. For example, the following document is invalid for execution since the original executing schema may not know about the provided type extension: <pre id="example-12752" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L118-L129"><a href="#example-12752">Counter Example № 102</a><code>query getDogName { dog { name color } } extend type Dog { color: String } </code></pre> </section> </section> </section> <section id="sec-Validation.Operations" secid="5.2"> <h2 data-source="spec/Section%205%20--%20Validation.md#L131"><a href="#sec-Validation.Operations">5.2</a>Operations</h2> <section id="sec-Named-Operation-Definitions" secid="5.2.1"> <h3 data-source="spec/Section%205%20--%20Validation.md#L133"><a href="#sec-Named-Operation-Definitions">5.2.1</a>Named Operation Definitions</h3> <section id="sec-Operation-Name-Uniqueness" secid="5.2.1.1"> <h4 data-source="spec/Section%205%20--%20Validation.md#L135"><a href="#sec-Operation-Name-Uniqueness">5.2.1.1</a>Operation Name Uniqueness</h4> <section id="sec-Operation-Name-Uniqueness.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L137"><a href="#sec-Operation-Name-Uniqueness.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L139">For each operation definition <var data-name="operation">operation</var> in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L140">Let <var data-name="operationName">operationName</var> be the name of <var data-name="operation">operation</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L141-L143">If <var data-name="operationName">operationName</var> exists<ul> <li data-source="spec/Section%205%20--%20Validation.md#L142">Let <var data-name="operations">operations</var> be all operation definitions in the document named <var data-name="operationName">operationName</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L143"><var data-name="operations">operations</var> must be a set of one.</li> </ul> </li> </ul> </section> <section id="sec-Operation-Name-Uniqueness.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L145"><a href="#sec-Operation-Name-Uniqueness.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Each named operation definition must be unique within a document when referred to by its name. For example the following document is valid: <pre id="example-069e1" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L152-L166"><a href="#example-069e1">Example № 103</a><code>query getDogName { dog { name } } query getOwnerName { dog { owner { name } } } </code></pre> While this document is invalid: <pre id="example-5e409" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L170-L184"><a href="#example-5e409">Counter Example № 104</a><code>query getName { dog { name } } query getName { dog { owner { name } } } </code></pre> It is invalid even if the type of each operation is different: <pre id="example-77c2e" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L188-L200"><a href="#example-77c2e">Counter Example № 105</a><code>query dogOperation { dog { name } } mutation dogOperation { mutateDog { id } } </code></pre> </section> </section> </section> <section id="sec-Anonymous-Operation-Definitions" secid="5.2.2"> <h3 data-source="spec/Section%205%20--%20Validation.md#L202"><a href="#sec-Anonymous-Operation-Definitions">5.2.2</a>Anonymous Operation Definitions</h3> <section id="sec-Lone-Anonymous-Operation" secid="5.2.2.1"> <h4 data-source="spec/Section%205%20--%20Validation.md#L204"><a href="#sec-Lone-Anonymous-Operation">5.2.2.1</a>Lone Anonymous Operation</h4> <section id="sec-Lone-Anonymous-Operation.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L206"><a href="#sec-Lone-Anonymous-Operation.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L208">Let <var data-name="operations">operations</var> be all operation definitions in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L209">Let <var data-name="anonymous">anonymous</var> be all anonymous operation definitions in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L210-L211">If <var data-name="operations">operations</var> is a set of more than 1:<ul> <li data-source="spec/Section%205%20--%20Validation.md#L211"><var data-name="anonymous">anonymous</var> must be empty.</li> </ul> </li> </ul> </section> <section id="sec-Lone-Anonymous-Operation.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L213"><a href="#sec-Lone-Anonymous-Operation.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> GraphQL allows a short-hand form for defining query operations when only that one operation exists in the document. For example the following document is valid: <pre id="example-be853" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L220-L226"><a href="#example-be853">Example № 106</a><code>{ dog { name } } </code></pre> While this document is invalid: <pre id="example-44b85" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L230-L244"><a href="#example-44b85">Counter Example № 107</a><code>{ dog { name } } query getName { dog { owner { name } } } </code></pre> </section> </section> </section> <section id="sec-Subscription-Operation-Definitions" secid="5.2.3"> <h3 data-source="spec/Section%205%20--%20Validation.md#L246"><a href="#sec-Subscription-Operation-Definitions">5.2.3</a>Subscription Operation Definitions</h3> <section id="sec-Single-root-field" secid="5.2.3.1"> <h4 data-source="spec/Section%205%20--%20Validation.md#L248"><a href="#sec-Single-root-field">5.2.3.1</a>Single root field</h4> <section id="sec-Single-root-field.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L250"><a href="#sec-Single-root-field.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L252">For each subscription operation definition <var data-name="subscription">subscription</var> in the document</li> <li data-source="spec/Section%205%20--%20Validation.md#L253">Let <var data-name="subscriptionType">subscriptionType</var> be the root Subscription type in <var data-name="schema">schema</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L254">Let <var data-name="selectionSet">selectionSet</var> be the top level selection set on <var data-name="subscription">subscription</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L255">Let <var data-name="variableValues">variableValues</var> be the empty set.</li> <li data-source="spec/Section%205%20--%20Validation.md#L256-L257">Let <var data-name="groupedFieldSet">groupedFieldSet</var> be the result of <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>(<var data-name="subscriptionType">subscriptionType</var>, <var data-name="selectionSet">selectionSet</var>, <var data-name="variableValues">variableValues</var>).</li> <li data-source="spec/Section%205%20--%20Validation.md#L258-L259"><var data-name="groupedFieldSet">groupedFieldSet</var> must have exactly one entry, which must not be an introspection field.</li> </ul> </section> <section id="sec-Single-root-field.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L261"><a href="#sec-Single-root-field.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Subscription operations must have exactly one root field. Valid examples: <pre id="example-5bbc3" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L267-L274"><a href="#example-5bbc3">Example № 108</a><code>subscription sub { newMessage { body sender } } </code></pre> <pre id="example-13061" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L276-L287"><a href="#example-13061">Example № 109</a><code>subscription sub { ...newMessageFields } fragment newMessageFields on Subscription { newMessage { body sender } } </code></pre> Invalid: <pre id="example-3997d" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L291-L299"><a href="#example-3997d">Counter Example № 110</a><code>subscription sub { newMessage { body sender } disallowedSecondRootField } </code></pre> <pre id="example-18466" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L301-L313"><a href="#example-18466">Counter Example № 111</a><code>subscription sub { ...multipleSubscriptions } fragment multipleSubscriptions on Subscription { newMessage { body sender } disallowedSecondRootField } </code></pre> The root field of a subscription operation must not be an introspection field. The following example is also invalid: <pre id="example-a8fa1" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L318-L322"><a href="#example-a8fa1">Counter Example № 112</a><code>subscription sub { __typename } </code></pre> <div id="note-80ec0" class="spec-note" data-source="spec/Section%205%20--%20Validation.md#L324-L327"> <a href="#note-80ec0">Note</a> While each subscription must have exactly one root field, a document may contain any number of operations, each of which may contain different root fields. When executed, a document containing multiple subscription operations must provide the operation name as described in <a href="#GetOperation()" data-name="GetOperation">GetOperation</a>().</div> </section> </section> </section> </section> <section id="sec-Validation.Fields" secid="5.3"> <h2 data-source="spec/Section%205%20--%20Validation.md#L329"><a href="#sec-Validation.Fields">5.3</a>Fields</h2> <section id="sec-Field-Selections" secid="5.3.1"> <h3 data-source="spec/Section%205%20--%20Validation.md#L331"><a href="#sec-Field-Selections">5.3.1</a>Field Selections</h3> Field selections must exist on Object, Interface, and Union types. <section id="sec-Field-Selections.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L335"><a href="#sec-Field-Selections.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L337">For each <var data-name="selection">selection</var> in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L338">Let <var data-name="fieldName">fieldName</var> be the target field of <var data-name="selection">selection</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L339"><var data-name="fieldName">fieldName</var> must be defined on type in scope</li> </ul> </section> <section id="sec-Field-Selections.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L341"><a href="#sec-Field-Selections.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> The target field of a field selection must be defined on the scoped type of the selection set. There are no limitations on alias names. For example the following fragment would not pass validation: <pre id="example-48706" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L348-L356"><a href="#example-48706">Counter Example № 113</a><code>fragment fieldNotDefined on Dog { meowVolume } fragment aliasedLyingFieldTargetNotDefined on Dog { barkVolume: kawVolume } </code></pre> For interfaces, direct field selection can only be done on fields. Fields of concrete implementors are not relevant to the validity of the given interface-typed selection set. For example, the following is valid: <pre id="example-d34e0" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L364-L368"><a href="#example-d34e0">Example № 114</a><code>fragment interfaceFieldSelection on Pet { name } </code></pre> and the following is invalid: <pre id="example-db33b" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L372-L376"><a href="#example-db33b">Counter Example № 115</a><code>fragment definedOnImplementorsButNotInterface on Pet { nickname } </code></pre> Because unions do not define fields, fields may not be directly selected from a union-typed selection set, with the exception of the meta-field <var data-name="__typename">__typename</var>. Fields from a union-typed selection set must only be queried indirectly via a fragment. For example the following is valid: <pre id="example-245fa" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L385-L395"><a href="#example-245fa">Example № 116</a><code>fragment inDirectFieldSelectionOnUnion on CatOrDog { __typename ... on Pet { name } ... on Dog { barkVolume } } </code></pre> But the following is invalid: <pre id="example-252ad" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L399-L404"><a href="#example-252ad">Counter Example № 117</a><code>fragment directFieldSelectionOnUnion on CatOrDog { name barkVolume } </code></pre> </section> </section> <section id="sec-Field-Selection-Merging" secid="5.3.2"> <h3 data-source="spec/Section%205%20--%20Validation.md#L407"><a href="#sec-Field-Selection-Merging">5.3.2</a>Field Selection Merging</h3> <section id="sec-Field-Selection-Merging.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L409"><a href="#sec-Field-Selection-Merging.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L411">Let <var data-name="set">set</var> be any selection set defined in the GraphQL document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L412"><a href="#FieldsInSetCanMerge()" data-name="FieldsInSetCanMerge">FieldsInSetCanMerge</a>(<var data-name="set">set</var>) must be true.</li> </ul> <div class="spec-algo" id="FieldsInSetCanMerge()" data-source="spec/Section%205%20--%20Validation.md#L414-L426"> <a href="#FieldsInSetCanMerge()" data-name="FieldsInSetCanMerge">FieldsInSetCanMerge</a>(<var data-name="set">set</var>)<ol> <li data-source="spec/Section%205%20--%20Validation.md#L416-L417">Let <var data-name="fieldsForName">fieldsForName</var> be the set of selections with a given response name in <var data-name="set">set</var> including visiting fragments and inline fragments.</li> <li data-source="spec/Section%205%20--%20Validation.md#L418-L426">Given each pair of members <var data-name="fieldA">fieldA</var> and <var data-name="fieldB">fieldB</var> in <var data-name="fieldsForName">fieldsForName</var>:<ol> <li data-source="spec/Section%205%20--%20Validation.md#L419"><a href="#SameResponseShape()" data-name="SameResponseShape">SameResponseShape</a>(<var data-name="fieldA">fieldA</var>, <var data-name="fieldB">fieldB</var>) must be true.</li> <li data-source="spec/Section%205%20--%20Validation.md#L420-L426">If the parent types of <var data-name="fieldA">fieldA</var> and <var data-name="fieldB">fieldB</var> are equal or if either is not an Object Type:<ol> <li data-source="spec/Section%205%20--%20Validation.md#L422"><var data-name="fieldA">fieldA</var> and <var data-name="fieldB">fieldB</var> must have identical field names.</li> <li data-source="spec/Section%205%20--%20Validation.md#L423"><var data-name="fieldA">fieldA</var> and <var data-name="fieldB">fieldB</var> must have identical sets of arguments.</li> <li data-source="spec/Section%205%20--%20Validation.md#L424-L425">Let <var data-name="mergedSet">mergedSet</var> be the result of adding the selection set of <var data-name="fieldA">fieldA</var> and the selection set of <var data-name="fieldB">fieldB</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L426"><a href="#FieldsInSetCanMerge()" data-name="FieldsInSetCanMerge">FieldsInSetCanMerge</a>(<var data-name="mergedSet">mergedSet</var>) must be true.</li> </ol> </li> </ol> </li> </ol> </div> <div class="spec-algo" id="SameResponseShape()" data-source="spec/Section%205%20--%20Validation.md#L428-L451"> <a href="#SameResponseShape()" data-name="SameResponseShape">SameResponseShape</a>(<var data-name="fieldA">fieldA</var>, <var data-name="fieldB">fieldB</var>)<ol> <li data-source="spec/Section%205%20--%20Validation.md#L430">Let <var data-name="typeA">typeA</var> be the return type of <var data-name="fieldA">fieldA</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L431">Let <var data-name="typeB">typeB</var> be the return type of <var data-name="fieldB">fieldB</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L432-L435">If <var data-name="typeA">typeA</var> or <var data-name="typeB">typeB</var> is Non-Null.<ol> <li data-source="spec/Section%205%20--%20Validation.md#L433">If <var data-name="typeA">typeA</var> or <var data-name="typeB">typeB</var> is nullable, return false.</li> <li data-source="spec/Section%205%20--%20Validation.md#L434">Let <var data-name="typeA">typeA</var> be the nullable type of <var data-name="typeA">typeA</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L435">Let <var data-name="typeB">typeB</var> be the nullable type of <var data-name="typeB">typeB</var></li> </ol> </li> <li data-source="spec/Section%205%20--%20Validation.md#L436-L440">If <var data-name="typeA">typeA</var> or <var data-name="typeB">typeB</var> is List.<ol> <li data-source="spec/Section%205%20--%20Validation.md#L437">If <var data-name="typeA">typeA</var> or <var data-name="typeB">typeB</var> is not List, return false.</li> <li data-source="spec/Section%205%20--%20Validation.md#L438">Let <var data-name="typeA">typeA</var> be the item type of <var data-name="typeA">typeA</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L439">Let <var data-name="typeB">typeB</var> be the item type of <var data-name="typeB">typeB</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L440">Repeat from step 3.</li> </ol> </li> <li data-source="spec/Section%205%20--%20Validation.md#L441-L443">If <var data-name="typeA">typeA</var> or <var data-name="typeB">typeB</var> is Scalar or Enum.<ol> <li data-source="spec/Section%205%20--%20Validation.md#L442-L443">If <var data-name="typeA">typeA</var> and <var data-name="typeB">typeB</var> are the same type return true, otherwise return false.</li> </ol> </li> <li data-source="spec/Section%205%20--%20Validation.md#L444">Assert: <var data-name="typeA">typeA</var> and <var data-name="typeB">typeB</var> are both composite types.</li> <li data-source="spec/Section%205%20--%20Validation.md#L445-L446">Let <var data-name="mergedSet">mergedSet</var> be the result of adding the selection set of <var data-name="fieldA">fieldA</var> and the selection set of <var data-name="fieldB">fieldB</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L447-L448">Let <var data-name="fieldsForName">fieldsForName</var> be the set of selections with a given response name in <var data-name="mergedSet">mergedSet</var> including visiting fragments and inline fragments.</li> <li data-source="spec/Section%205%20--%20Validation.md#L449-L450">Given each pair of members <var data-name="subfieldA">subfieldA</var> and <var data-name="subfieldB">subfieldB</var> in <var data-name="fieldsForName">fieldsForName</var>:<ol> <li data-source="spec/Section%205%20--%20Validation.md#L450">If <a href="#SameResponseShape()" data-name="SameResponseShape">SameResponseShape</a>(<var data-name="subfieldA">subfieldA</var>, <var data-name="subfieldB">subfieldB</var>) is false, return false.</li> </ol> </li> <li data-source="spec/Section%205%20--%20Validation.md#L451">Return true.</li> </ol> </div> </section> <section id="sec-Field-Selection-Merging.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L453"><a href="#sec-Field-Selection-Merging.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> If multiple field selections with the same response names are encountered during execution, the field and arguments to execute and the resulting value should be unambiguous. Therefore any two field selections which might both be encountered for the same object are only valid if they are equivalent. During execution, the simultaneous execution of fields with the same response name is accomplished by <a href="#MergeSelectionSets()" data-name="MergeSelectionSets">MergeSelectionSets</a>() and <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>(). For simple hand-written GraphQL, this rule is obviously a clear developer error, however nested fragments can make this difficult to detect manually. The following selections correctly merge: <pre id="example-4e10c" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L468-L478"><a href="#example-4e10c">Example № 118</a><code>fragment mergeIdenticalFields on Dog { name name } fragment mergeIdenticalAliasesAndFields on Dog { otherName: name otherName: name } </code></pre> The following is not able to merge: <pre id="example-a2230" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L482-L487"><a href="#example-a2230">Counter Example № 119</a><code>fragment conflictingBecauseAlias on Dog { name: nickname name } </code></pre> Identical arguments are also merged if they have identical arguments. Both values and variables can be correctly merged. For example the following correctly merge: <pre id="example-b6369" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L494-L504"><a href="#example-b6369">Example № 120</a><code>fragment mergeIdenticalFieldsWithIdenticalArgs on Dog { doesKnowCommand(dogCommand: SIT) doesKnowCommand(dogCommand: SIT) } fragment mergeIdenticalFieldsWithIdenticalValues on Dog { doesKnowCommand(dogCommand: $dogCommand) doesKnowCommand(dogCommand: $dogCommand) } </code></pre> The following do not correctly merge: <pre id="example-00fbf" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L508-L528"><a href="#example-00fbf">Counter Example № 121</a><code>fragment conflictingArgsOnValues on Dog { doesKnowCommand(dogCommand: SIT) doesKnowCommand(dogCommand: HEEL) } fragment conflictingArgsValueAndVar on Dog { doesKnowCommand(dogCommand: SIT) doesKnowCommand(dogCommand: $dogCommand) } fragment conflictingArgsWithVars on Dog { doesKnowCommand(dogCommand: $varOne) doesKnowCommand(dogCommand: $varTwo) } fragment differingArgs on Dog { doesKnowCommand(dogCommand: SIT) doesKnowCommand } </code></pre> The following fields would not merge together, however both cannot be encountered against the same object, so they are safe: <pre id="example-a8406" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L533-L551"><a href="#example-a8406">Example № 122</a><code>fragment safeDifferingFields on Pet { ... on Dog { volume: barkVolume } ... on Cat { volume: meowVolume } } fragment safeDifferingArgs on Pet { ... on Dog { doesKnowCommand(dogCommand: SIT) } ... on Cat { doesKnowCommand(catCommand: JUMP) } } </code></pre> However, the field responses must be shapes which can be merged. For example, scalar values must not differ. In this example, <code>someValue</code> might be a <code>String</code> or an <code>Int</code>: <pre id="example-54e3d" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L557-L566"><a href="#example-54e3d">Counter Example № 123</a><code>fragment conflictingDifferingResponses on Pet { ... on Dog { someValue: nickname } ... on Cat { someValue: meowVolume } } </code></pre> </section> </section> <section id="sec-Leaf-Field-Selections" secid="5.3.3"> <h3 data-source="spec/Section%205%20--%20Validation.md#L569"><a href="#sec-Leaf-Field-Selections">5.3.3</a>Leaf Field Selections</h3> <section id="sec-Leaf-Field-Selections.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L571"><a href="#sec-Leaf-Field-Selections.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L573">For each <var data-name="selection">selection</var> in the document</li> <li data-source="spec/Section%205%20--%20Validation.md#L574">Let <var data-name="selectionType">selectionType</var> be the result type of <var data-name="selection">selection</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L575-L576">If <var data-name="selectionType">selectionType</var> is a scalar or enum:<ul> <li data-source="spec/Section%205%20--%20Validation.md#L576">The subselection set of that selection must be empty</li> </ul> </li> <li data-source="spec/Section%205%20--%20Validation.md#L577-L578">If <var data-name="selectionType">selectionType</var> is an interface, union, or object<ul> <li data-source="spec/Section%205%20--%20Validation.md#L578">The subselection set of that selection must NOT BE empty</li> </ul> </li> </ul> </section> <section id="sec-Leaf-Field-Selections.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L580"><a href="#sec-Leaf-Field-Selections.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Field selections on scalars or enums are never allowed, because they are the leaf nodes of any GraphQL operation. The following is valid. <pre id="example-e23c5" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L587-L591"><a href="#example-e23c5">Example № 124</a><code>fragment scalarSelection on Dog { barkVolume } </code></pre> The following is invalid. <pre id="example-13b69" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L595-L601"><a href="#example-13b69">Counter Example № 125</a><code>fragment scalarSelectionsNotAllowedOnInt on Dog { barkVolume { sinceWhen } } </code></pre> Conversely the leaf field selections of GraphQL operations must be of type scalar or enum. Leaf selections on objects, interfaces, and unions without subfields are disallowed. Let’s assume the following additions to the query root operation type of the schema: <pre id="example-9bada" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L610-L616"><a href="#example-9bada">Example № 126</a><code>extend type Query { human: Human pet: Pet catOrDog: CatOrDog } </code></pre> The following examples are invalid <pre id="example-d68ee" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L620-L632"><a href="#example-d68ee">Counter Example № 127</a><code>query directQueryOnObjectWithoutSubFields { human } query directQueryOnInterfaceWithoutSubFields { pet } query directQueryOnUnionWithoutSubFields { catOrDog } </code></pre> </section> </section> </section> <section id="sec-Validation.Arguments" secid="5.4"> <h2 data-source="spec/Section%205%20--%20Validation.md#L635"><a href="#sec-Validation.Arguments">5.4</a>Arguments</h2> Arguments are provided to both fields and directives. The following validation rules apply in both cases. <section id="sec-Argument-Names" secid="5.4.1"> <h3 data-source="spec/Section%205%20--%20Validation.md#L641"><a href="#sec-Argument-Names">5.4.1</a>Argument Names</h3> <section id="sec-Argument-Names.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L643"><a href="#sec-Argument-Names.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L645">For each <var data-name="argument">argument</var> in the document</li> <li data-source="spec/Section%205%20--%20Validation.md#L646">Let <var data-name="argumentName">argumentName</var> be the Name of <var data-name="argument">argument</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L647">Let <var data-name="argumentDefinition">argumentDefinition</var> be the argument definition provided by the parent field or definition named <var data-name="argumentName">argumentName</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L648"><var data-name="argumentDefinition">argumentDefinition</var> must exist.</li> </ul> </section> <section id="sec-Argument-Names.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L650"><a href="#sec-Argument-Names.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Every argument provided to a field or directive must be defined in the set of possible arguments of that field or directive. For example the following are valid: <pre id="example-dfd15" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L657-L665"><a href="#example-dfd15">Example № 128</a><code>fragment argOnRequiredArg on Dog { doesKnowCommand(dogCommand: SIT) } fragment argOnOptional on Dog { isHouseTrained(atOtherHomes: true) @include(if: true) } </code></pre> the following is invalid since <code>command</code> is not defined on <code>DogCommand</code>. <pre id="example-d5639" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L669-L673"><a href="#example-d5639">Counter Example № 129</a><code>fragment invalidArgName on Dog { doesKnowCommand(command: CLEAN_UP_HOUSE) } </code></pre> and this is also invalid as <code>unless</code> is not defined on <code>@include</code>. <pre id="example-df41e" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L677-L681"><a href="#example-df41e">Counter Example № 130</a><code>fragment invalidArgName on Dog { isHouseTrained(atOtherHomes: true) @include(unless: false) } </code></pre> In order to explore more complicated argument examples, let’s add the following to our type system: <pre id="example-73706" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L686-L700"><a href="#example-73706">Example № 131</a><code>type Arguments { multipleRequirements(x: Int!, y: Int!): Int! booleanArgField(booleanArg: Boolean): Boolean floatArgField(floatArg: Float): Float intArgField(intArg: Int): Int nonNullBooleanArgField(nonNullBooleanArg: Boolean!): Boolean! booleanListArgField(booleanListArg: [Boolean]!): [Boolean] optionalNonNullBooleanArgField(optionalBooleanArg: Boolean! = false): Boolean! } extend type Query { arguments: Arguments } </code></pre> Order does not matter in arguments. Therefore both the following examples are valid. <pre id="example-bda7e" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L704-L712"><a href="#example-bda7e">Example № 132</a><code>fragment multipleArgs on Arguments { multipleRequirements(x: 1, y: 2) } fragment multipleArgsReverseOrder on Arguments { multipleRequirements(y: 2, x: 1) } </code></pre> </section> </section> <section id="sec-Argument-Uniqueness" secid="5.4.2"> <h3 data-source="spec/Section%205%20--%20Validation.md#L715"><a href="#sec-Argument-Uniqueness">5.4.2</a>Argument Uniqueness</h3> Fields and directives treat arguments as a mapping of argument name to value. More than one argument with the same name in an argument set is ambiguous and invalid. <section id="sec-Argument-Uniqueness.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L721"><a href="#sec-Argument-Uniqueness.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L723">For each <var data-name="argument">argument</var> in the Document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L724">Let <var data-name="argumentName">argumentName</var> be the Name of <var data-name="argument">argument</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L725">Let <var data-name="arguments">arguments</var> be all Arguments named <var data-name="argumentName">argumentName</var> in the Argument Set which contains <var data-name="argument">argument</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L726"><var data-name="arguments">arguments</var> must be the set containing only <var data-name="argument">argument</var>.</li> </ul> </section> <section id="sec-Required-Arguments" secid="5.4.2.1"> <h4 data-source="spec/Section%205%20--%20Validation.md#L729"><a href="#sec-Required-Arguments">5.4.2.1</a>Required Arguments</h4> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L731">For each Field or Directive in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L732">Let <var data-name="arguments">arguments</var> be the arguments provided by the Field or Directive.</li> <li data-source="spec/Section%205%20--%20Validation.md#L733">Let <var data-name="argumentDefinitions">argumentDefinitions</var> be the set of argument definitions of that Field or Directive.</li> <li data-source="spec/Section%205%20--%20Validation.md#L734-L742">For each <var data-name="argumentDefinition">argumentDefinition</var> in <var data-name="argumentDefinitions">argumentDefinitions</var>:<ul> <li data-source="spec/Section%205%20--%20Validation.md#L735">Let <var data-name="type">type</var> be the expected type of <var data-name="argumentDefinition">argumentDefinition</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L736">Let <var data-name="defaultValue">defaultValue</var> be the default value of <var data-name="argumentDefinition">argumentDefinition</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L737-L742">If <var data-name="type">type</var> is Non-Null and <var data-name="defaultValue">defaultValue</var> does not exist:<ul> <li data-source="spec/Section%205%20--%20Validation.md#L738">Let <var data-name="argumentName">argumentName</var> be the name of <var data-name="argumentDefinition">argumentDefinition</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L739">Let <var data-name="argument">argument</var> be the argument in <var data-name="arguments">arguments</var> named <var data-name="argumentName">argumentName</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L740"><var data-name="argument">argument</var> must exist.</li> <li data-source="spec/Section%205%20--%20Validation.md#L741">Let <var data-name="value">value</var> be the value of <var data-name="argument">argument</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L742"><var data-name="value">value</var> must not be the null literal.</li> </ul> </li> </ul> </li> </ul> <section id="sec-Required-Arguments.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L744"><a href="#sec-Required-Arguments.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Arguments can be required. An argument is required if the argument type is non-null and does not have a default value. Otherwise, the argument is optional. For example the following are valid: <pre id="example-503bd" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L751-L759"><a href="#example-503bd">Example № 133</a><code>fragment goodBooleanArg on Arguments { booleanArgField(booleanArg: true) } fragment goodNonNullArg on Arguments { nonNullBooleanArgField(nonNullBooleanArg: true) } </code></pre> The argument can be omitted from a field with a nullable argument. Therefore the following fragment is valid: <pre id="example-1f1d2" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L765-L769"><a href="#example-1f1d2">Example № 134</a><code>fragment goodBooleanArgDefault on Arguments { booleanArgField } </code></pre> but this is not valid on a required argument. <pre id="example-f12a1" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L773-L777"><a href="#example-f12a1">Counter Example № 135</a><code>fragment missingRequiredArg on Arguments { nonNullBooleanArgField } </code></pre> Providing the explicit value null is also not valid since required arguments always have a non-null type. <pre id="example-0bc81" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L782-L786"><a href="#example-0bc81">Counter Example № 136</a><code>fragment missingRequiredArg on Arguments { nonNullBooleanArgField(nonNullBooleanArg: null) } </code></pre> </section> </section> </section> </section> <section id="sec-Validation.Fragments" secid="5.5"> <h2 data-source="spec/Section%205%20--%20Validation.md#L788"><a href="#sec-Validation.Fragments">5.5</a>Fragments</h2> <section id="sec-Fragment-Declarations" secid="5.5.1"> <h3 data-source="spec/Section%205%20--%20Validation.md#L790"><a href="#sec-Fragment-Declarations">5.5.1</a>Fragment Declarations</h3> <section id="sec-Fragment-Name-Uniqueness" secid="5.5.1.1"> <h4 data-source="spec/Section%205%20--%20Validation.md#L792"><a href="#sec-Fragment-Name-Uniqueness">5.5.1.1</a>Fragment Name Uniqueness</h4> <section id="sec-Fragment-Name-Uniqueness.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L794"><a href="#sec-Fragment-Name-Uniqueness.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L796">For each fragment definition <var data-name="fragment">fragment</var> in the document</li> <li data-source="spec/Section%205%20--%20Validation.md#L797">Let <var data-name="fragmentName">fragmentName</var> be the name of <var data-name="fragment">fragment</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L798">Let <var data-name="fragments">fragments</var> be all fragment definitions in the document named <var data-name="fragmentName">fragmentName</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L799"><var data-name="fragments">fragments</var> must be a set of one.</li> </ul> </section> <section id="sec-Fragment-Name-Uniqueness.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L801"><a href="#sec-Fragment-Name-Uniqueness.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Fragment definitions are referenced in fragment spreads by name. To avoid ambiguity, each fragment’s name must be unique within a document. Inline fragments are not considered fragment definitions, and are unaffected by this validation rule. For example the following document is valid: <pre id="example-3703b" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L811-L828"><a href="#example-3703b">Example № 137</a><code>{ dog { ...fragmentOne ...fragmentTwo } } fragment fragmentOne on Dog { name } fragment fragmentTwo on Dog { owner { name } } </code></pre> While this document is invalid: <pre id="example-2c3e3" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L832-L848"><a href="#example-2c3e3">Counter Example № 138</a><code>{ dog { ...fragmentOne } } fragment fragmentOne on Dog { name } fragment fragmentOne on Dog { owner { name } } </code></pre> </section> </section> <section id="sec-Fragment-Spread-Type-Existence" secid="5.5.1.2"> <h4 data-source="spec/Section%205%20--%20Validation.md#L851"><a href="#sec-Fragment-Spread-Type-Existence">5.5.1.2</a>Fragment Spread Type Existence</h4> <section id="sec-Fragment-Spread-Type-Existence.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L853"><a href="#sec-Fragment-Spread-Type-Existence.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L855">For each named spread <var data-name="namedSpread">namedSpread</var> in the document</li> <li data-source="spec/Section%205%20--%20Validation.md#L856">Let <var data-name="fragment">fragment</var> be the target of <var data-name="namedSpread">namedSpread</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L857">The target type of <var data-name="fragment">fragment</var> must be defined in the schema</li> </ul> </section> <section id="sec-Fragment-Spread-Type-Existence.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L859"><a href="#sec-Fragment-Spread-Type-Existence.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Fragments must be specified on types that exist in the schema. This applies for both named and inline fragments. If they are not defined in the schema, the fragment is invalid. For example the following fragments are valid: <pre id="example-1b2da" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L867-L883"><a href="#example-1b2da">Example № 139</a><code>fragment correctType on Dog { name } fragment inlineFragment on Dog { ... on Dog { name } } fragment inlineFragment2 on Dog { ... @include(if: true) { name } } </code></pre> and the following do not validate: <pre id="example-463f6" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L887-L897"><a href="#example-463f6">Counter Example № 140</a><code>fragment notOnExistingType on NotInSchema { name } fragment inlineNotExistingType on Dog { ... on NotInSchema { name } } </code></pre> </section> </section> <section id="sec-Fragments-On-Composite-Types" secid="5.5.1.3"> <h4 data-source="spec/Section%205%20--%20Validation.md#L900"><a href="#sec-Fragments-On-Composite-Types">5.5.1.3</a>Fragments On Composite Types</h4> <section id="sec-Fragments-On-Composite-Types.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L902"><a href="#sec-Fragments-On-Composite-Types.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L904">For each <var data-name="fragment">fragment</var> defined in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L905-L906">The target type of fragment must have kind UNION, INTERFACE, or OBJECT.</li> </ul> </section> <section id="sec-Fragments-On-Composite-Types.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L908"><a href="#sec-Fragments-On-Composite-Types.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Fragments can only be declared on unions, interfaces, and objects. They are invalid on scalars. They can only be applied on non-leaf fields. This rule applies to both inline and named fragments. The following fragment declarations are valid: <pre id="example-3c8d4" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L916-L930"><a href="#example-3c8d4">Example № 141</a><code>fragment fragOnObject on Dog { name } fragment fragOnInterface on Pet { name } fragment fragOnUnion on CatOrDog { ... on Dog { name } } </code></pre> and the following are invalid: <pre id="example-4d5e5" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L934-L944"><a href="#example-4d5e5">Counter Example № 142</a><code>fragment fragOnScalar on Int { something } fragment inlineFragOnScalar on Dog { ... on Boolean { somethingElse } } </code></pre> </section> </section> <section id="sec-Fragments-Must-Be-Used" secid="5.5.1.4"> <h4 data-source="spec/Section%205%20--%20Validation.md#L947"><a href="#sec-Fragments-Must-Be-Used">5.5.1.4</a>Fragments Must Be Used</h4> <section id="sec-Fragments-Must-Be-Used.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L949"><a href="#sec-Fragments-Must-Be-Used.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L951">For each <var data-name="fragment">fragment</var> defined in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L952"><var data-name="fragment">fragment</var> must be the target of at least one spread in the document</li> </ul> </section> <section id="sec-Fragments-Must-Be-Used.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L954"><a href="#sec-Fragments-Must-Be-Used.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Defined fragments must be used within a document. For example the following is an invalid document: <pre id="example-9e1e3" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L960-L970"><a href="#example-9e1e3">Counter Example № 143</a><code>fragment nameFragment on Dog { # unused name } { dog { name } } </code></pre> </section> </section> </section> <section id="sec-Fragment-Spreads" secid="5.5.2"> <h3 data-source="spec/Section%205%20--%20Validation.md#L973"><a href="#sec-Fragment-Spreads">5.5.2</a>Fragment Spreads</h3> Field selection is also determined by spreading fragments into one another. The selection set of the target fragment is combined into the selection set at the level at which the target fragment is referenced. <section id="sec-Fragment-spread-target-defined" secid="5.5.2.1"> <h4 data-source="spec/Section%205%20--%20Validation.md#L981"><a href="#sec-Fragment-spread-target-defined">5.5.2.1</a>Fragment spread target defined</h4> <section id="sec-Fragment-spread-target-defined.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L983"><a href="#sec-Fragment-spread-target-defined.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L985">For every <var data-name="namedSpread">namedSpread</var> in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L986">Let <var data-name="fragment">fragment</var> be the target of <var data-name="namedSpread">namedSpread</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L987"><var data-name="fragment">fragment</var> must be defined in the document</li> </ul> </section> <section id="sec-Fragment-spread-target-defined.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L989"><a href="#sec-Fragment-spread-target-defined.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Named fragment spreads must refer to fragments defined within the document. It is a validation error if the target of a spread is not defined. <pre id="example-28421" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L995-L1001"><a href="#example-28421">Counter Example № 144</a><code>{ dog { ...undefinedFragment } } </code></pre> </section> </section> <section id="sec-Fragment-spreads-must-not-form-cycles" secid="5.5.2.2"> <h4 data-source="spec/Section%205%20--%20Validation.md#L1004"><a href="#sec-Fragment-spreads-must-not-form-cycles">5.5.2.2</a>Fragment spreads must not form cycles</h4> <section id="sec-Fragment-spreads-must-not-form-cycles.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1006"><a href="#sec-Fragment-spreads-must-not-form-cycles.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1008">For each <var data-name="fragmentDefinition">fragmentDefinition</var> in the document</li> <li data-source="spec/Section%205%20--%20Validation.md#L1009">Let <var data-name="visited">visited</var> be the empty set.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1010"><a href="#DetectFragmentCycles()" data-name="DetectFragmentCycles">DetectFragmentCycles</a>(<var data-name="fragmentDefinition">fragmentDefinition</var>, <var data-name="visited">visited</var>)</li> </ul> <div class="spec-algo" id="DetectFragmentCycles()" data-source="spec/Section%205%20--%20Validation.md#L1012-L1019"> <a href="#DetectFragmentCycles()" data-name="DetectFragmentCycles">DetectFragmentCycles</a>(<var data-name="fragmentDefinition">fragmentDefinition</var>, <var data-name="visited">visited</var>)<ol> <li data-source="spec/Section%205%20--%20Validation.md#L1014">Let <var data-name="spreads">spreads</var> be all fragment spread descendants of <var data-name="fragmentDefinition">fragmentDefinition</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1015-L1019">For each <var data-name="spread">spread</var> in <var data-name="spreads">spreads</var><ol> <li data-source="spec/Section%205%20--%20Validation.md#L1016"><var data-name="visited">visited</var> must not contain <var data-name="spread">spread</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1017">Let <var data-name="nextVisited">nextVisited</var> be the set including <var data-name="spread">spread</var> and members of <var data-name="visited">visited</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1018">Let <var data-name="nextFragmentDefinition">nextFragmentDefinition</var> be the target of <var data-name="spread">spread</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1019"><a href="#DetectFragmentCycles()" data-name="DetectFragmentCycles">DetectFragmentCycles</a>(<var data-name="nextFragmentDefinition">nextFragmentDefinition</var>, <var data-name="nextVisited">nextVisited</var>)</li> </ol> </li> </ol> </div> </section> <section id="sec-Fragment-spreads-must-not-form-cycles.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1021"><a href="#sec-Fragment-spreads-must-not-form-cycles.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> The graph of fragment spreads must not form any cycles including spreading itself. Otherwise an operation could infinitely spread or infinitely execute on cycles in the underlying data. This invalidates fragments that would result in an infinite spread: <pre id="example-9ceb4" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1029-L1045"><a href="#example-9ceb4">Counter Example № 145</a><code>{ dog { ...nameFragment } } fragment nameFragment on Dog { name ...barkVolumeFragment } fragment barkVolumeFragment on Dog { barkVolume ...nameFragment } </code></pre> If the above fragments were inlined, this would result in the infinitely large: <pre id="example-08734" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1049-L1062"><a href="#example-08734">Example № 146</a><code>{ dog { name barkVolume name barkVolume name barkVolume name # forever... } } </code></pre> This also invalidates fragments that would result in an infinite recursion when executed against cyclic data: <pre id="example-cd11c" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1067-L1087"><a href="#example-cd11c">Counter Example № 147</a><code>{ dog { ...dogFragment } } fragment dogFragment on Dog { name owner { ...ownerFragment } } fragment ownerFragment on Human { name pets { ...dogFragment } } </code></pre> </section> </section> <section id="sec-Fragment-spread-is-possible" secid="5.5.2.3"> <h4 data-source="spec/Section%205%20--%20Validation.md#L1090"><a href="#sec-Fragment-spread-is-possible">5.5.2.3</a>Fragment spread is possible</h4> <section id="sec-Fragment-spread-is-possible.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1092"><a href="#sec-Fragment-spread-is-possible.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1094">For each <var data-name="spread">spread</var> (named or inline) defined in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1095">Let <var data-name="fragment">fragment</var> be the target of <var data-name="spread">spread</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1096">Let <var data-name="fragmentType">fragmentType</var> be the type condition of <var data-name="fragment">fragment</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1097">Let <var data-name="parentType">parentType</var> be the type of the selection set containing <var data-name="spread">spread</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1098-L1099">Let <var data-name="applicableTypes">applicableTypes</var> be the intersection of <a href="#GetPossibleTypes()" data-name="GetPossibleTypes">GetPossibleTypes</a>(<var data-name="fragmentType">fragmentType</var>) and <a href="#GetPossibleTypes()" data-name="GetPossibleTypes">GetPossibleTypes</a>(<var data-name="parentType">parentType</var>)</li> <li data-source="spec/Section%205%20--%20Validation.md#L1100"><var data-name="applicableTypes">applicableTypes</var> must not be empty.</li> </ul> <div class="spec-algo" id="GetPossibleTypes()" data-source="spec/Section%205%20--%20Validation.md#L1102-L1106"> <a href="#GetPossibleTypes()" data-name="GetPossibleTypes">GetPossibleTypes</a>(<var data-name="type">type</var>)<ol> <li data-source="spec/Section%205%20--%20Validation.md#L1104">If <var data-name="type">type</var> is an object type, return a set containing <var data-name="type">type</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1105">If <var data-name="type">type</var> is an interface type, return the set of types implementing <var data-name="type">type</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1106">If <var data-name="type">type</var> is a union type, return the set of possible types of <var data-name="type">type</var></li> </ol> </div> </section> <section id="sec-Fragment-spread-is-possible.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1108"><a href="#sec-Fragment-spread-is-possible.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Fragments are declared on a type and will only apply when the runtime object type matches the type condition. They also are spread within the context of a parent type. A fragment spread is only valid if its type condition could ever apply within the parent type. </section> <section id="sec-Object-Spreads-In-Object-Scope" secid="5.5.2.3.1"> <h5 data-source="spec/Section%205%20--%20Validation.md#L1117"><a href="#sec-Object-Spreads-In-Object-Scope">5.5.2.3.1</a>Object Spreads In Object Scope</h5> In the scope of an object type, the only valid object type fragment spread is one that applies to the same type that is in scope. For example <pre id="example-0fc38" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1125-L1131"><a href="#example-0fc38">Example № 148</a><code>fragment dogFragment on Dog { ... on Dog { barkVolume } } </code></pre> and the following is invalid <pre id="example-4d411" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1135-L1141"><a href="#example-4d411">Counter Example № 149</a><code>fragment catInDogFragmentInvalid on Dog { ... on Cat { meowVolume } } </code></pre> </section> <section id="sec-Abstract-Spreads-in-Object-Scope" secid="5.5.2.3.2"> <h5 data-source="spec/Section%205%20--%20Validation.md#L1144"><a href="#sec-Abstract-Spreads-in-Object-Scope">5.5.2.3.2</a>Abstract Spreads in Object Scope</h5> In scope of an object type, unions or interface spreads can be used if the object type implements the interface or is a member of the union. For example <pre id="example-2c8d0" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1151-L1159"><a href="#example-2c8d0">Example № 150</a><code>fragment petNameFragment on Pet { name } fragment interfaceWithinObjectFragment on Dog { ...petNameFragment } </code></pre> is valid because Dog implements Pet. Likewise <pre id="example-41843" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1165-L1175"><a href="#example-41843">Example № 151</a><code>fragment catOrDogNameFragment on CatOrDog { ... on Cat { meowVolume } } fragment unionWithObjectFragment on Dog { ...catOrDogNameFragment } </code></pre> is valid because Dog is a member of the CatOrDog union. It is worth noting that if one inspected the contents of the CatOrDogNameFragment you could note that no valid results would ever be returned. However we do not specify this as invalid because we only consider the fragment declaration, not its body. </section> <section id="sec-Object-Spreads-In-Abstract-Scope" secid="5.5.2.3.3"> <h5 data-source="spec/Section%205%20--%20Validation.md#L1184"><a href="#sec-Object-Spreads-In-Abstract-Scope">5.5.2.3.3</a>Object Spreads In Abstract Scope</h5> Union or interface spreads can be used within the context of an object type fragment, but only if the object type is one of the possible types of that interface or union. For example, the following fragments are valid: <pre id="example-85110" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1192-L1205"><a href="#example-85110">Example № 152</a><code>fragment petFragment on Pet { name ... on Dog { barkVolume } } fragment catOrDogFragment on CatOrDog { ... on Cat { meowVolume } } </code></pre> <var data-name="petFragment">petFragment</var> is valid because Dog implements the interface Pet. <var data-name="catOrDogFragment">catOrDogFragment</var> is valid because Cat is a member of the CatOrDog union. By contrast the following fragments are invalid: <pre id="example-a8dcc" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1213-L1225"><a href="#example-a8dcc">Counter Example № 153</a><code>fragment sentientFragment on Sentient { ... on Dog { barkVolume } } fragment humanOrAlienFragment on HumanOrAlien { ... on Cat { meowVolume } } </code></pre> Dog does not implement the interface Sentient and therefore <var data-name="sentientFragment">sentientFragment</var> can never return meaningful results. Therefore the fragment is invalid. Likewise Cat is not a member of the union HumanOrAlien, and it can also never return meaningful results, making it invalid. </section> <section id="sec-Abstract-Spreads-in-Abstract-Scope" secid="5.5.2.3.4"> <h5 data-source="spec/Section%205%20--%20Validation.md#L1233"><a href="#sec-Abstract-Spreads-in-Abstract-Scope">5.5.2.3.4</a>Abstract Spreads in Abstract Scope</h5> Union or interfaces fragments can be used within each other. As long as there exists at least one object type that exists in the intersection of the possible types of the scope and the spread, the spread is considered valid. So for example <pre id="example-dc875" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1241-L1251"><a href="#example-dc875">Example № 154</a><code>fragment unionWithInterface on Pet { ...dogOrHumanFragment } fragment dogOrHumanFragment on DogOrHuman { ... on Dog { barkVolume } } </code></pre> is considered valid because Dog implements interface Pet and is a member of DogOrHuman. However <pre id="example-c9c63" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1258-L1266"><a href="#example-c9c63">Counter Example № 155</a><code>fragment nonIntersectingInterfaces on Pet { ...sentientFragment } fragment sentientFragment on Sentient { name } </code></pre> is not valid because there exists no type that implements both Pet and Sentient. <section id="sec-Abstract-Spreads-in-Abstract-Scope.Interface-Spreads-in-implemented-Interface-Scope" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1272"><a href="#sec-Abstract-Spreads-in-Abstract-Scope.Interface-Spreads-in-implemented-Interface-Scope" title="link to this subsection">Interface Spreads in implemented Interface Scope</a></h6> Additionally, an interface type fragment can always be spread into an interface scope which it implements. In the example below, the <code>...resourceFragment</code> fragments spreads is valid, since <code>Resource</code> implements <code>Node</code>. <pre id="example-bc12a" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1280-L1297"><a href="#example-bc12a">Example № 156</a><code>interface Node { id: ID! } interface Resource implements Node { id: ID! url: String } fragment interfaceWithInterface on Node { ...resourceFragment } fragment resourceFragment on Resource { url } </code></pre> </section> </section> </section> </section> </section> <section id="sec-Values" secid="5.6"> <h2 data-source="spec/Section%205%20--%20Validation.md#L1300"><a href="#sec-Values">5.6</a>Values</h2> <section id="sec-Values-of-Correct-Type" secid="5.6.1"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1303"><a href="#sec-Values-of-Correct-Type">5.6.1</a>Values of Correct Type</h3> <section id="sec-Values-of-Correct-Type.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1305"><a href="#sec-Values-of-Correct-Type.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1307-L1309">For each input Value <var data-name="value">value</var> in the document.<ul> <li data-source="spec/Section%205%20--%20Validation.md#L1308">Let <var data-name="type">type</var> be the type expected in the position <var data-name="value">value</var> is found.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1309"><var data-name="value">value</var> must be coercible to <var data-name="type">type</var>.</li> </ul> </li> </ul> </section> <section id="sec-Values-of-Correct-Type.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1311"><a href="#sec-Values-of-Correct-Type.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Literal values must be compatible with the type expected in the position they are found as per the coercion rules defined in the Type System chapter. The type expected in a position includes the type defined by the argument a value is provided for, the type defined by an input object field a value is provided for, and the type of a variable definition a default value is provided for. The following examples are valid use of value literals: <pre id="example-7ee0e" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1322-L1335"><a href="#example-7ee0e">Example № 157</a><code>fragment goodBooleanArg on Arguments { booleanArgField(booleanArg: true) } fragment coercedIntIntoFloatArg on Arguments { # Note: The input coercion rules for Float allow Int literals. floatArgField(floatArg: 123) } query goodComplexDefaultValue($search: ComplexInput = { name: "Fido" }) { findDog(complex: $search) } </code></pre> Non-coercible values (such as a String into an Int) are invalid. The following examples are invalid: <pre id="example-3a7c1" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1340-L1348"><a href="#example-3a7c1">Counter Example № 158</a><code>fragment stringIntoInt on Arguments { intArgField(intArg: "123") } query badComplexValue { findDog(complex: { name: 123 }) } </code></pre> </section> </section> <section id="sec-Input-Object-Field-Names" secid="5.6.2"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1351"><a href="#sec-Input-Object-Field-Names">5.6.2</a>Input Object Field Names</h3> <section id="sec-Input-Object-Field-Names.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1353"><a href="#sec-Input-Object-Field-Names.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1355">For each Input Object Field <var data-name="inputField">inputField</var> in the document</li> <li data-source="spec/Section%205%20--%20Validation.md#L1356">Let <var data-name="inputFieldName">inputFieldName</var> be the Name of <var data-name="inputField">inputField</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1357-L1358">Let <var data-name="inputFieldDefinition">inputFieldDefinition</var> be the input field definition provided by the parent input object type named <var data-name="inputFieldName">inputFieldName</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1359"><var data-name="inputFieldDefinition">inputFieldDefinition</var> must exist.</li> </ul> </section> <section id="sec-Input-Object-Field-Names.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1361"><a href="#sec-Input-Object-Field-Names.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Every input field provided in an input object value must be defined in the set of possible fields of that input object’s expected type. For example the following example input object is valid: <pre id="example-a940b" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1368-L1372"><a href="#example-a940b">Example № 159</a><code>{ findDog(complex: { name: "Fido" }) } </code></pre> While the following example input-object uses a field “favoriteCookieFlavor” which is not defined on the expected type: <pre id="example-1a5f6" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1377-L1381"><a href="#example-1a5f6">Counter Example № 160</a><code>{ findDog(complex: { favoriteCookieFlavor: "Bacon" }) } </code></pre> </section> </section> <section id="sec-Input-Object-Field-Uniqueness" secid="5.6.3"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1384"><a href="#sec-Input-Object-Field-Uniqueness">5.6.3</a>Input Object Field Uniqueness</h3> <section id="sec-Input-Object-Field-Uniqueness.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1386"><a href="#sec-Input-Object-Field-Uniqueness.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1388">For each input object value <var data-name="inputObject">inputObject</var> in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1389-L1392">For every <var data-name="inputField">inputField</var> in <var data-name="inputObject">inputObject</var><ul> <li data-source="spec/Section%205%20--%20Validation.md#L1390">Let <var data-name="name">name</var> be the Name of <var data-name="inputField">inputField</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1391">Let <var data-name="fields">fields</var> be all Input Object Fields named <var data-name="name">name</var> in <var data-name="inputObject">inputObject</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1392"><var data-name="fields">fields</var> must be the set containing only <var data-name="inputField">inputField</var>.</li> </ul> </li> </ul> </section> <section id="sec-Input-Object-Field-Uniqueness.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1394"><a href="#sec-Input-Object-Field-Uniqueness.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Input objects must not contain more than one field of the same name, otherwise an ambiguity would exist which includes an ignored portion of syntax. For example the following document will not pass validation. <pre id="example-5d541" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1401-L1405"><a href="#example-5d541">Counter Example № 161</a><code>{ field(arg: { field: true, field: false }) } </code></pre> </section> </section> <section id="sec-Input-Object-Required-Fields" secid="5.6.4"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1408"><a href="#sec-Input-Object-Required-Fields">5.6.4</a>Input Object Required Fields</h3> <section id="sec-Input-Object-Required-Fields.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1410"><a href="#sec-Input-Object-Required-Fields.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1412-L1414">For each Input Object in the document.<ul> <li data-source="spec/Section%205%20--%20Validation.md#L1413">Let <var data-name="fields">fields</var> be the fields provided by that Input Object.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1414">Let <var data-name="fieldDefinitions">fieldDefinitions</var> be the set of input field definitions of that Input Object.</li> </ul> </li> <li data-source="spec/Section%205%20--%20Validation.md#L1415-L1423">For each <var data-name="fieldDefinition">fieldDefinition</var> in <var data-name="fieldDefinitions">fieldDefinitions</var>:<ul> <li data-source="spec/Section%205%20--%20Validation.md#L1416">Let <var data-name="type">type</var> be the expected type of <var data-name="fieldDefinition">fieldDefinition</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1417">Let <var data-name="defaultValue">defaultValue</var> be the default value of <var data-name="fieldDefinition">fieldDefinition</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1418-L1423">If <var data-name="type">type</var> is Non-Null and <var data-name="defaultValue">defaultValue</var> does not exist:<ul> <li data-source="spec/Section%205%20--%20Validation.md#L1419">Let <var data-name="fieldName">fieldName</var> be the name of <var data-name="fieldDefinition">fieldDefinition</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1420">Let <var data-name="field">field</var> be the input field in <var data-name="fields">fields</var> named <var data-name="fieldName">fieldName</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1421"><var data-name="field">field</var> must exist.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1422">Let <var data-name="value">value</var> be the value of <var data-name="field">field</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1423"><var data-name="value">value</var> must not be the null literal.</li> </ul> </li> </ul> </li> </ul> </section> <section id="sec-Input-Object-Required-Fields.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1425"><a href="#sec-Input-Object-Required-Fields.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Input object fields may be required. Much like a field may have required arguments, an input object may have required fields. An input field is required if it has a non-null type and does not have a default value. Otherwise, the input object field is optional. </section> </section> </section> <section id="sec-Validation.Directives" secid="5.7"> <h2 data-source="spec/Section%205%20--%20Validation.md#L1433"><a href="#sec-Validation.Directives">5.7</a>Directives</h2> <section id="sec-Directives-Are-Defined" secid="5.7.1"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1436"><a href="#sec-Directives-Are-Defined">5.7.1</a>Directives Are Defined</h3> <section id="sec-Directives-Are-Defined.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1438"><a href="#sec-Directives-Are-Defined.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1440">For every <var data-name="directive">directive</var> in a document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1441">Let <var data-name="directiveName">directiveName</var> be the name of <var data-name="directive">directive</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1442">Let <var data-name="directiveDefinition">directiveDefinition</var> be the directive named <var data-name="directiveName">directiveName</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1443"><var data-name="directiveDefinition">directiveDefinition</var> must exist.</li> </ul> </section> <section id="sec-Directives-Are-Defined.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1445"><a href="#sec-Directives-Are-Defined.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> GraphQL services define what directives they support. For each usage of a directive, the directive must be available on that service. </section> </section> <section id="sec-Directives-Are-In-Valid-Locations" secid="5.7.2"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1451"><a href="#sec-Directives-Are-In-Valid-Locations">5.7.2</a>Directives Are In Valid Locations</h3> <section id="sec-Directives-Are-In-Valid-Locations.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1453"><a href="#sec-Directives-Are-In-Valid-Locations.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1455">For every <var data-name="directive">directive</var> in a document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1456">Let <var data-name="directiveName">directiveName</var> be the name of <var data-name="directive">directive</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1457">Let <var data-name="directiveDefinition">directiveDefinition</var> be the directive named <var data-name="directiveName">directiveName</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1458">Let <var data-name="locations">locations</var> be the valid locations for <var data-name="directiveDefinition">directiveDefinition</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1459">Let <var data-name="adjacent">adjacent</var> be the AST node the directive affects.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1460"><var data-name="adjacent">adjacent</var> must be represented by an item within <var data-name="locations">locations</var>.</li> </ul> </section> <section id="sec-Directives-Are-In-Valid-Locations.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1462"><a href="#sec-Directives-Are-In-Valid-Locations.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> GraphQL services define what directives they support and where they support them. For each usage of a directive, the directive must be used in a location that the service has declared support for. For example the following document will not pass validation because <code>@skip</code> does not provide <code>QUERY</code> as a valid location. <pre id="example-55f3f" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1471-L1475"><a href="#example-55f3f">Counter Example № 162</a><code>query @skip(if: $foo) { field } </code></pre> </section> </section> <section id="sec-Directives-Are-Unique-Per-Location" secid="5.7.3"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1478"><a href="#sec-Directives-Are-Unique-Per-Location">5.7.3</a>Directives Are Unique Per Location</h3> <section id="sec-Directives-Are-Unique-Per-Location.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1480"><a href="#sec-Directives-Are-Unique-Per-Location.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1482-L1489">For every <var data-name="location">location</var> in the document for which Directives can apply:<ul> <li data-source="spec/Section%205%20--%20Validation.md#L1483-L1484">Let <var data-name="directives">directives</var> be the set of Directives which apply to <var data-name="location">location</var> and are not repeatable.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1485-L1489">For each <var data-name="directive">directive</var> in <var data-name="directives">directives</var>:<ul> <li data-source="spec/Section%205%20--%20Validation.md#L1486">Let <var data-name="directiveName">directiveName</var> be the name of <var data-name="directive">directive</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1487-L1488">Let <var data-name="namedDirectives">namedDirectives</var> be the set of all Directives named <var data-name="directiveName">directiveName</var> in <var data-name="directives">directives</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1489"><var data-name="namedDirectives">namedDirectives</var> must be a set of one.</li> </ul> </li> </ul> </li> </ul> </section> <section id="sec-Directives-Are-Unique-Per-Location.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1491"><a href="#sec-Directives-Are-Unique-Per-Location.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Directives are used to describe some metadata or behavioral change on the definition they apply to. When more than one directive of the same name is used, the expected metadata or behavior becomes ambiguous, therefore only one of each directive is allowed per location. For example, the following document will not pass validation because <code>@skip</code> has been used twice for the same field: <pre id="example-b2e6c" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1501-L1505"><a href="#example-b2e6c">Counter Example № 163</a><code>query ($foo: Boolean = true, $bar: Boolean = false) { field @skip(if: $foo) @skip(if: $bar) } </code></pre> However the following example is valid because <code>@skip</code> has been used only once per location, despite being used twice in the operation and on the same named field: <pre id="example-c5ee9" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1511-L1520"><a href="#example-c5ee9">Example № 164</a><code>query ($foo: Boolean = true, $bar: Boolean = false) { field @skip(if: $foo) { subfieldA } field @skip(if: $bar) { subfieldB } } </code></pre> </section> </section> </section> <section id="sec-Validation.Variables" secid="5.8"> <h2 data-source="spec/Section%205%20--%20Validation.md#L1523"><a href="#sec-Validation.Variables">5.8</a>Variables</h2> <section id="sec-Variable-Uniqueness" secid="5.8.1"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1525"><a href="#sec-Variable-Uniqueness">5.8.1</a>Variable Uniqueness</h3> <section id="sec-Variable-Uniqueness.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1527"><a href="#sec-Variable-Uniqueness.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1529-L1534">For every <var data-name="operation">operation</var> in the document<ul> <li data-source="spec/Section%205%20--%20Validation.md#L1530-L1534">For every <var data-name="variable">variable</var> defined on <var data-name="operation">operation</var><ul> <li data-source="spec/Section%205%20--%20Validation.md#L1531">Let <var data-name="variableName">variableName</var> be the name of <var data-name="variable">variable</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1532-L1533">Let <var data-name="variables">variables</var> be the set of all variables named <var data-name="variableName">variableName</var> on <var data-name="operation">operation</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1534"><var data-name="variables">variables</var> must be a set of one</li> </ul> </li> </ul> </li> </ul> </section> <section id="sec-Variable-Uniqueness.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1536"><a href="#sec-Variable-Uniqueness.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> If any operation defines more than one variable with the same name, it is ambiguous and invalid. It is invalid even if the type of the duplicate variable is the same. <pre id="example-abc9c" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1542-L1548"><a href="#example-abc9c">Counter Example № 165</a><code>query houseTrainedQuery($atOtherHomes: Boolean, $atOtherHomes: Boolean) { dog { isHouseTrained(atOtherHomes: $atOtherHomes) } } </code></pre> It is valid for multiple operations to define a variable with the same name. If two operations reference the same fragment, it might actually be necessary: <pre id="example-54c93" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1554-L1568"><a href="#example-54c93">Example № 166</a><code>query A($atOtherHomes: Boolean) { ...HouseTrainedFragment } query B($atOtherHomes: Boolean) { ...HouseTrainedFragment } fragment HouseTrainedFragment on Query { dog { isHouseTrained(atOtherHomes: $atOtherHomes) } } </code></pre> </section> </section> <section id="sec-Variables-Are-Input-Types" secid="5.8.2"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1571"><a href="#sec-Variables-Are-Input-Types">5.8.2</a>Variables Are Input Types</h3> <section id="sec-Variables-Are-Input-Types.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1573"><a href="#sec-Variables-Are-Input-Types.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1575">For every <var data-name="operation">operation</var> in a <var data-name="document">document</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1576-L1578">For every <var data-name="variable">variable</var> on each <var data-name="operation">operation</var><ul> <li data-source="spec/Section%205%20--%20Validation.md#L1577">Let <var data-name="variableType">variableType</var> be the type of <var data-name="variable">variable</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1578"><a href="#IsInputType()" data-name="IsInputType">IsInputType</a>(<var data-name="variableType">variableType</var>) must be true</li> </ul> </li> </ul> </section> <section id="sec-Variables-Are-Input-Types.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1580"><a href="#sec-Variables-Are-Input-Types.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Variables can only be input types. Objects, unions, and interfaces cannot be used as inputs. For these examples, consider the following type system additions: <pre id="example-ce150" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1587-L1597"><a href="#example-ce150">Example № 167</a><code>input ComplexInput { name: String owner: String } extend type Query { findDog(complex: ComplexInput): Dog booleanList(booleanListArg: [Boolean!]): Boolean } </code></pre> The following operations are valid: <pre id="example-a4255" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1601-L1617"><a href="#example-a4255">Example № 168</a><code>query takesBoolean($atOtherHomes: Boolean) { dog { isHouseTrained(atOtherHomes: $atOtherHomes) } } query takesComplexInput($complexInput: ComplexInput) { findDog(complex: $complexInput) { name } } query TakesListOfBooleanBang($booleans: [Boolean!]) { booleanList(booleanListArg: $booleans) } </code></pre> The following operations are invalid: <pre id="example-aeba9" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1621-L1637"><a href="#example-aeba9">Counter Example № 169</a><code>query takesCat($cat: Cat) { # ... } query takesDogBang($dog: Dog!) { # ... } query takesListOfPet($pets: [Pet]) { # ... } query takesCatOrDog($catOrDog: CatOrDog) { # ... } </code></pre> </section> </section> <section id="sec-All-Variable-Uses-Defined" secid="5.8.3"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1640"><a href="#sec-All-Variable-Uses-Defined">5.8.3</a>All Variable Uses Defined</h3> <section id="sec-All-Variable-Uses-Defined.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1642"><a href="#sec-All-Variable-Uses-Defined.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1644-L1649">For each <var data-name="operation">operation</var> in a document<ul> <li data-source="spec/Section%205%20--%20Validation.md#L1645">For each <var data-name="variableUsage">variableUsage</var> in scope, variable must be in <var data-name="operation">operation</var>‘s variable list.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1646">Let <var data-name="fragments">fragments</var> be every fragment referenced by that <var data-name="operation">operation</var> transitively</li> <li data-source="spec/Section%205%20--%20Validation.md#L1647-L1649">For each <var data-name="fragment">fragment</var> in <var data-name="fragments">fragments</var><ul> <li data-source="spec/Section%205%20--%20Validation.md#L1648-L1649">For each <var data-name="variableUsage">variableUsage</var> in scope of <var data-name="fragment">fragment</var>, variable must be in <var data-name="operation">operation</var>‘s variable list.</li> </ul> </li> </ul> </li> </ul> </section> <section id="sec-All-Variable-Uses-Defined.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1651"><a href="#sec-All-Variable-Uses-Defined.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Variables are scoped on a per-operation basis. That means that any variable used within the context of an operation must be defined at the top level of that operation For example: <pre id="example-38119" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1659-L1665"><a href="#example-38119">Example № 170</a><code>query variableIsDefined($atOtherHomes: Boolean) { dog { isHouseTrained(atOtherHomes: $atOtherHomes) } } </code></pre> is valid. $<var data-name="atOtherHomes">atOtherHomes</var> is defined by the operation. By contrast the following document is invalid: <pre id="example-5ba94" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1671-L1677"><a href="#example-5ba94">Counter Example № 171</a><code>query variableIsNotDefined { dog { isHouseTrained(atOtherHomes: $atOtherHomes) } } </code></pre> $<var data-name="atOtherHomes">atOtherHomes</var> is not defined by the operation. Fragments complicate this rule. Any fragment transitively included by an operation has access to the variables defined by that operation. Fragments can appear within multiple operations and therefore variable usages must correspond to variable definitions in all of those operations. For example the following is valid: <pre id="example-559c2" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1688-L1698"><a href="#example-559c2">Example № 172</a><code>query variableIsDefinedUsedInSingleFragment($atOtherHomes: Boolean) { dog { ...isHouseTrainedFragment } } fragment isHouseTrainedFragment on Dog { isHouseTrained(atOtherHomes: $atOtherHomes) } </code></pre> since <var data-name="isHouseTrainedFragment">isHouseTrainedFragment</var> is used within the context of the operation <var data-name="variableIsDefinedUsedInSingleFragment">variableIsDefinedUsedInSingleFragment</var> and the variable is defined by that operation. On the other hand, if a fragment is included within an operation that does not define a referenced variable, the document is invalid. <pre id="example-93d3e" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1707-L1717"><a href="#example-93d3e">Counter Example № 173</a><code>query variableIsNotDefinedUsedInSingleFragment { dog { ...isHouseTrainedFragment } } fragment isHouseTrainedFragment on Dog { isHouseTrained(atOtherHomes: $atOtherHomes) } </code></pre> This applies transitively as well, so the following also fails: <pre id="example-ee7be" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1721-L1735"><a href="#example-ee7be">Counter Example № 174</a><code>query variableIsNotDefinedUsedInNestedFragment { dog { ...outerHouseTrainedFragment } } fragment outerHouseTrainedFragment on Dog { ...isHouseTrainedFragment } fragment isHouseTrainedFragment on Dog { isHouseTrained(atOtherHomes: $atOtherHomes) } </code></pre> Variables must be defined in all operations in which a fragment is used. <pre id="example-d601e" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1740-L1756"><a href="#example-d601e">Example № 175</a><code>query houseTrainedQueryOne($atOtherHomes: Boolean) { dog { ...isHouseTrainedFragment } } query houseTrainedQueryTwo($atOtherHomes: Boolean) { dog { ...isHouseTrainedFragment } } fragment isHouseTrainedFragment on Dog { isHouseTrained(atOtherHomes: $atOtherHomes) } </code></pre> However the following does not validate: <pre id="example-2b284" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1760-L1776"><a href="#example-2b284">Counter Example № 176</a><code>query houseTrainedQueryOne($atOtherHomes: Boolean) { dog { ...isHouseTrainedFragment } } query houseTrainedQueryTwoNotDefined { dog { ...isHouseTrainedFragment } } fragment isHouseTrainedFragment on Dog { isHouseTrained(atOtherHomes: $atOtherHomes) } </code></pre> This is because <var data-name="houseTrainedQueryTwoNotDefined">houseTrainedQueryTwoNotDefined</var> does not define a variable $<var data-name="atOtherHomes">atOtherHomes</var> but that variable is used by <var data-name="isHouseTrainedFragment">isHouseTrainedFragment</var> which is included in that operation. </section> </section> <section id="sec-All-Variables-Used" secid="5.8.4"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1783"><a href="#sec-All-Variables-Used">5.8.4</a>All Variables Used</h3> <section id="sec-All-Variables-Used.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1785"><a href="#sec-All-Variables-Used.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1787">For every <var data-name="operation">operation</var> in the document.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1788">Let <var data-name="variables">variables</var> be the variables defined by that <var data-name="operation">operation</var></li> <li data-source="spec/Section%205%20--%20Validation.md#L1789-L1791">Each <var data-name="variable">variable</var> in <var data-name="variables">variables</var> must be used at least once in either the operation scope itself or any fragment transitively referenced by that operation.</li> </ul> </section> <section id="sec-All-Variables-Used.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1793"><a href="#sec-All-Variables-Used.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> All variables defined by an operation must be used in that operation or a fragment transitively included by that operation. Unused variables cause a validation error. For example the following is invalid: <pre id="example-464b6" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1801-L1807"><a href="#example-464b6">Counter Example № 177</a><code>query variableUnused($atOtherHomes: Boolean) { dog { isHouseTrained } } </code></pre> because $<var data-name="atOtherHomes">atOtherHomes</var> is not referenced. These rules apply to transitive fragment spreads as well: <pre id="example-6d4bb" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1813-L1823"><a href="#example-6d4bb">Example № 178</a><code>query variableUsedInFragment($atOtherHomes: Boolean) { dog { ...isHouseTrainedFragment } } fragment isHouseTrainedFragment on Dog { isHouseTrained(atOtherHomes: $atOtherHomes) } </code></pre> The above is valid since $<var data-name="atOtherHomes">atOtherHomes</var> is used in <var data-name="isHouseTrainedFragment">isHouseTrainedFragment</var> which is included by <var data-name="variableUsedInFragment">variableUsedInFragment</var>. If that fragment did not have a reference to $<var data-name="atOtherHomes">atOtherHomes</var> it would be not valid: <pre id="example-a30e2" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1830-L1840"><a href="#example-a30e2">Counter Example № 179</a><code>query variableNotUsedWithinFragment($atOtherHomes: Boolean) { dog { ...isHouseTrainedWithoutVariableFragment } } fragment isHouseTrainedWithoutVariableFragment on Dog { isHouseTrained } </code></pre> All operations in a document must use all of their variables. As a result, the following document does not validate. <pre id="example-e647f" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1846-L1862"><a href="#example-e647f">Counter Example № 180</a><code>query queryWithUsedVar($atOtherHomes: Boolean) { dog { ...isHouseTrainedFragment } } query queryWithExtraVar($atOtherHomes: Boolean, $extra: Int) { dog { ...isHouseTrainedFragment } } fragment isHouseTrainedFragment on Dog { isHouseTrained(atOtherHomes: $atOtherHomes) } </code></pre> This document is not valid because <var data-name="queryWithExtraVar">queryWithExtraVar</var> defines an extraneous variable. </section> </section> <section id="sec-All-Variable-Usages-are-Allowed" secid="5.8.5"> <h3 data-source="spec/Section%205%20--%20Validation.md#L1868"><a href="#sec-All-Variable-Usages-are-Allowed">5.8.5</a>All Variable Usages are Allowed</h3> <section id="sec-All-Variable-Usages-are-Allowed.Formal-Specification" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1870"><a href="#sec-All-Variable-Usages-are-Allowed.Formal-Specification" title="link to this subsection">Formal Specification</a></h6> <ul> <li data-source="spec/Section%205%20--%20Validation.md#L1872">For each <var data-name="operation">operation</var> in <var data-name="document">document</var>:</li> <li data-source="spec/Section%205%20--%20Validation.md#L1873">Let <var data-name="variableUsages">variableUsages</var> be all usages transitively included in the <var data-name="operation">operation</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1874-L1878">For each <var data-name="variableUsage">variableUsage</var> in <var data-name="variableUsages">variableUsages</var>:<ul> <li data-source="spec/Section%205%20--%20Validation.md#L1875">Let <var data-name="variableName">variableName</var> be the name of <var data-name="variableUsage">variableUsage</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1876-L1877">Let <var data-name="variableDefinition">variableDefinition</var> be the <a href="#VariableDefinition" data-name="VariableDefinition">VariableDefinition</a> named <var data-name="variableName">variableName</var> defined within <var data-name="operation">operation</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1878"><a href="#IsVariableUsageAllowed()" data-name="IsVariableUsageAllowed">IsVariableUsageAllowed</a>(<var data-name="variableDefinition">variableDefinition</var>, <var data-name="variableUsage">variableUsage</var>) must be true.</li> </ul> </li> </ul> <div class="spec-algo" id="IsVariableUsageAllowed()" data-source="spec/Section%205%20--%20Validation.md#L1880-L1894"> <a href="#IsVariableUsageAllowed()" data-name="IsVariableUsageAllowed">IsVariableUsageAllowed</a>(<var data-name="variableDefinition">variableDefinition</var>, <var data-name="variableUsage">variableUsage</var>)<ol> <li data-source="spec/Section%205%20--%20Validation.md#L1882">Let <var data-name="variableType">variableType</var> be the expected type of <var data-name="variableDefinition">variableDefinition</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1883-L1884">Let <var data-name="locationType">locationType</var> be the expected type of the <a href="#Argument" data-name="Argument">Argument</a>, <a href="#ObjectField" data-name="ObjectField">ObjectField</a>, or <a href="#ListValue" data-name="ListValue">ListValue</a> entry where <var data-name="variableUsage">variableUsage</var> is located.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1885-L1893">If <var data-name="locationType">locationType</var> is a non-null type AND <var data-name="variableType">variableType</var> is NOT a non-null type:<ol> <li data-source="spec/Section%205%20--%20Validation.md#L1886-L1887">Let <var data-name="hasNonNullVariableDefaultValue">hasNonNullVariableDefaultValue</var> be true if a default value exists for <var data-name="variableDefinition">variableDefinition</var> and is not the value null.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1888-L1889">Let <var data-name="hasLocationDefaultValue">hasLocationDefaultValue</var> be true if a default value exists for the <a href="#Argument" data-name="Argument">Argument</a> or <a href="#ObjectField" data-name="ObjectField">ObjectField</a> where <var data-name="variableUsage">variableUsage</var> is located.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1890-L1891">If <var data-name="hasNonNullVariableDefaultValue">hasNonNullVariableDefaultValue</var> is NOT true AND <var data-name="hasLocationDefaultValue">hasLocationDefaultValue</var> is NOT true, return false.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1892">Let <var data-name="nullableLocationType">nullableLocationType</var> be the unwrapped nullable type of <var data-name="locationType">locationType</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1893">Return <a href="#AreTypesCompatible()" data-name="AreTypesCompatible">AreTypesCompatible</a>(<var data-name="variableType">variableType</var>, <var data-name="nullableLocationType">nullableLocationType</var>).</li> </ol> </li> <li data-source="spec/Section%205%20--%20Validation.md#L1894">Return <a href="#AreTypesCompatible()" data-name="AreTypesCompatible">AreTypesCompatible</a>(<var data-name="variableType">variableType</var>, <var data-name="locationType">locationType</var>).</li> </ol> </div> <div class="spec-algo" id="AreTypesCompatible()" data-source="spec/Section%205%20--%20Validation.md#L1896-L1912"> <a href="#AreTypesCompatible()" data-name="AreTypesCompatible">AreTypesCompatible</a>(<var data-name="variableType">variableType</var>, <var data-name="locationType">locationType</var>)<ol> <li data-source="spec/Section%205%20--%20Validation.md#L1898-L1902">If <var data-name="locationType">locationType</var> is a non-null type:<ol> <li data-source="spec/Section%205%20--%20Validation.md#L1899">If <var data-name="variableType">variableType</var> is NOT a non-null type, return false.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1900">Let <var data-name="nullableLocationType">nullableLocationType</var> be the unwrapped nullable type of <var data-name="locationType">locationType</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1901">Let <var data-name="nullableVariableType">nullableVariableType</var> be the unwrapped nullable type of <var data-name="variableType">variableType</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1902">Return <a href="#AreTypesCompatible()" data-name="AreTypesCompatible">AreTypesCompatible</a>(<var data-name="nullableVariableType">nullableVariableType</var>, <var data-name="nullableLocationType">nullableLocationType</var>).</li> </ol> </li> <li data-source="spec/Section%205%20--%20Validation.md#L1903-L1905">Otherwise, if <var data-name="variableType">variableType</var> is a non-null type:<ol> <li data-source="spec/Section%205%20--%20Validation.md#L1904">Let <var data-name="nullableVariableType">nullableVariableType</var> be the nullable type of <var data-name="variableType">variableType</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1905">Return <a href="#AreTypesCompatible()" data-name="AreTypesCompatible">AreTypesCompatible</a>(<var data-name="nullableVariableType">nullableVariableType</var>, <var data-name="locationType">locationType</var>).</li> </ol> </li> <li data-source="spec/Section%205%20--%20Validation.md#L1906-L1910">Otherwise, if <var data-name="locationType">locationType</var> is a list type:<ol> <li data-source="spec/Section%205%20--%20Validation.md#L1907">If <var data-name="variableType">variableType</var> is NOT a list type, return false.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1908">Let <var data-name="itemLocationType">itemLocationType</var> be the unwrapped item type of <var data-name="locationType">locationType</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1909">Let <var data-name="itemVariableType">itemVariableType</var> be the unwrapped item type of <var data-name="variableType">variableType</var>.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1910">Return <a href="#AreTypesCompatible()" data-name="AreTypesCompatible">AreTypesCompatible</a>(<var data-name="itemVariableType">itemVariableType</var>, <var data-name="itemLocationType">itemLocationType</var>).</li> </ol> </li> <li data-source="spec/Section%205%20--%20Validation.md#L1911">Otherwise, if <var data-name="variableType">variableType</var> is a list type, return false.</li> <li data-source="spec/Section%205%20--%20Validation.md#L1912">Return true if <var data-name="variableType">variableType</var> and <var data-name="locationType">locationType</var> are identical, otherwise false.</li> </ol> </div> </section> <section id="sec-All-Variable-Usages-are-Allowed.Explanatory-Text" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1914"><a href="#sec-All-Variable-Usages-are-Allowed.Explanatory-Text" title="link to this subsection">Explanatory Text</a></h6> Variable usages must be compatible with the arguments they are passed to. Validation failures occur when variables are used in the context of types that are complete mismatches, or if a nullable type in a variable is passed to a non-null argument type. Types must match: <pre id="example-2028e" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1924-L1930"><a href="#example-2028e">Counter Example № 181</a><code>query intCannotGoIntoBoolean($intArg: Int) { arguments { booleanArgField(booleanArg: $intArg) } } </code></pre> $<var data-name="intArg">intArg</var> typed as Int cannot be used as an argument to <var data-name="booleanArg">booleanArg</var>, typed as Boolean. List cardinality must also be the same. For example, lists cannot be passed into singular values. <pre id="example-8d369" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1937-L1943"><a href="#example-8d369">Counter Example № 182</a><code>query booleanListCannotGoIntoBoolean($booleanListArg: [Boolean]) { arguments { booleanArgField(booleanArg: $booleanListArg) } } </code></pre> Nullability must also be respected. In general a nullable variable cannot be passed to a non-null argument. <pre id="example-ed727" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1948-L1954"><a href="#example-ed727">Counter Example № 183</a><code>query booleanArgQuery($booleanArg: Boolean) { arguments { nonNullBooleanArgField(nonNullBooleanArg: $booleanArg) } } </code></pre> For list types, the same rules around nullability apply to both outer types and inner types. A nullable list cannot be passed to a non-null list, and a list of nullable values cannot be passed to a list of non-null values. The following is valid: <pre id="example-c5959" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1961-L1967"><a href="#example-c5959">Example № 184</a><code>query nonNullListToList($nonNullBooleanList: [Boolean]!) { arguments { booleanListArgField(booleanListArg: $nonNullBooleanList) } } </code></pre> However, a nullable list cannot be passed to a non-null list: <pre id="example-64255" class="spec-counter-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1971-L1977"><a href="#example-64255">Counter Example № 185</a><code>query listToNonNullList($booleanList: [Boolean]) { arguments { nonNullBooleanListField(nonNullBooleanListArg: $booleanList) } } </code></pre> This would fail validation because a <code>[T]</code> cannot be passed to a <code>[T]!</code>. Similarly a <code>[T]</code> cannot be passed to a <code>[T!]</code>. </section> <section id="sec-All-Variable-Usages-are-Allowed.Allowing-optional-variables-when-default-values-exist" class="subsec"> <h6 data-source="spec/Section%205%20--%20Validation.md#L1982"><a href="#sec-All-Variable-Usages-are-Allowed.Allowing-optional-variables-when-default-values-exist" title="link to this subsection">Allowing optional variables when default values exist</a></h6> A notable exception to typical variable type compatibility is allowing a variable definition with a nullable type to be provided to a non-null location as long as either that variable or that location provides a default value. In the example below, an optional variable <code>$booleanArg</code> is allowed to be used in the non-null argument <code>optionalBooleanArg</code> because the field argument is optional since it provides a default value in the schema. <pre id="example-0877c" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L1992-L1998"><a href="#example-0877c">Example № 186</a><code>query booleanArgQueryWithDefault($booleanArg: Boolean) { arguments { optionalNonNullBooleanArgField(optionalBooleanArg: $booleanArg) } } </code></pre> In the example below, an optional variable <code>$booleanArg</code> is allowed to be used in the non-null argument (<code>nonNullBooleanArg</code>) because the variable provides a default value in the operation. This behavior is explicitly supported for compatibility with earlier editions of this specification. GraphQL authoring tools may wish to report this as a warning with the suggestion to replace <code>Boolean</code> with <code>Boolean!</code> to avoid ambiguity. <pre id="example-d24d9" class="spec-example" data-language="graphql" data-source="spec/Section%205%20--%20Validation.md#L2007-L2013"><a href="#example-d24d9">Example № 187</a><code>query booleanArgQueryWithDefault($booleanArg: Boolean = true) { arguments { nonNullBooleanArgField(nonNullBooleanArg: $booleanArg) } } </code></pre> <div id="note-f0f28" class="spec-note" data-source="spec/Section%205%20--%20Validation.md#L2015-L2017"> <a href="#note-f0f28">Note</a> The value null could still be provided to such a variable at runtime. A non-null argument must raise a field error if provided a null value. </div> </section> </section> </section> </section> <section id="sec-Execution" secid="6"> <h1 data-source="spec/Section%206%20--%20Execution.md#L1"><a href="#sec-Execution">6</a>Execution</h1> GraphQL generates a response from a request via execution. A request for execution consists of a few pieces of information: <ul> <li data-source="spec/Section%206%20--%20Execution.md#L7">The schema to use, typically solely provided by the GraphQL service.</li> <li data-source="spec/Section%206%20--%20Execution.md#L8">A <a href="#Document" data-name="Document">Document</a> which must contain GraphQL <a href="#OperationDefinition" data-name="OperationDefinition">OperationDefinition</a> and may contain <a href="#FragmentDefinition" data-name="FragmentDefinition">FragmentDefinition</a>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L9">Optionally: The name of the Operation in the Document to execute.</li> <li data-source="spec/Section%206%20--%20Execution.md#L10">Optionally: Values for any Variables defined by the Operation.</li> <li data-source="spec/Section%206%20--%20Execution.md#L11-L14">An initial value corresponding to the root type being executed. Conceptually, an initial value represents the “universe” of data available via a GraphQL Service. It is common for a GraphQL Service to always use the same initial value for every request.</li> </ul> Given this information, the result of <a href="#ExecuteRequest()" data-name="ExecuteRequest">ExecuteRequest</a>() produces the response, to be formatted according to the Response section below. <section id="sec-Executing-Requests" secid="6.1"> <h2 data-source="spec/Section%206%20--%20Execution.md#L20"><a href="#sec-Executing-Requests">6.1</a>Executing Requests</h2> To execute a request, the executor must have a parsed <a href="#Document" data-name="Document">Document</a> and a selected operation name to run if the document defines multiple operations, otherwise the document is expected to only contain a single operation. The result of the request is determined by the result of executing this operation according to the “Executing Operations” section below. <div class="spec-algo" id="ExecuteRequest()" data-source="spec/Section%206%20--%20Execution.md#L28-L37"> <a href="#ExecuteRequest()" data-name="ExecuteRequest">ExecuteRequest</a>(<var data-name="schema">schema</var>, <var data-name="document">document</var>, <var data-name="operationName">operationName</var>, <var data-name="variableValues">variableValues</var>, <var data-name="initialValue">initialValue</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L30">Let <var data-name="operation">operation</var> be the result of <a href="#GetOperation()" data-name="GetOperation">GetOperation</a>(<var data-name="document">document</var>, <var data-name="operationName">operationName</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L31">Let <var data-name="coercedVariableValues">coercedVariableValues</var> be the result of <a href="#CoerceVariableValues()" data-name="CoerceVariableValues">CoerceVariableValues</a>(<var data-name="schema">schema</var>, <var data-name="operation">operation</var>, <var data-name="variableValues">variableValues</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L32-L33">If <var data-name="operation">operation</var> is a query operation:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L33">Return <a href="#ExecuteQuery()" data-name="ExecuteQuery">ExecuteQuery</a>(<var data-name="operation">operation</var>, <var data-name="schema">schema</var>, <var data-name="coercedVariableValues">coercedVariableValues</var>, <var data-name="initialValue">initialValue</var>).</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L34-L35">Otherwise if <var data-name="operation">operation</var> is a mutation operation:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L35">Return <a href="#ExecuteMutation()" data-name="ExecuteMutation">ExecuteMutation</a>(<var data-name="operation">operation</var>, <var data-name="schema">schema</var>, <var data-name="coercedVariableValues">coercedVariableValues</var>, <var data-name="initialValue">initialValue</var>).</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L36-L37">Otherwise if <var data-name="operation">operation</var> is a subscription operation:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L37">Return <a href="#Subscribe()" data-name="Subscribe">Subscribe</a>(<var data-name="operation">operation</var>, <var data-name="schema">schema</var>, <var data-name="coercedVariableValues">coercedVariableValues</var>, <var data-name="initialValue">initialValue</var>).</li> </ol> </li> </ol> </div> <div class="spec-algo" id="GetOperation()" data-source="spec/Section%206%20--%20Execution.md#L39-L48"> <a href="#GetOperation()" data-name="GetOperation">GetOperation</a>(<var data-name="document">document</var>, <var data-name="operationName">operationName</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L41-L44">If <var data-name="operationName">operationName</var> is null:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L42-L43">If <var data-name="document">document</var> contains exactly one operation.<ol> <li data-source="spec/Section%206%20--%20Execution.md#L43">Return the Operation contained in the <var data-name="document">document</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L44">Otherwise raise a request error requiring <var data-name="operationName">operationName</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L45-L48">Otherwise:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L46">Let <var data-name="operation">operation</var> be the Operation named <var data-name="operationName">operationName</var> in <var data-name="document">document</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L47">If <var data-name="operation">operation</var> was not found, raise a request error.</li> <li data-source="spec/Section%206%20--%20Execution.md#L48">Return <var data-name="operation">operation</var>.</li> </ol> </li> </ol> </div> <section id="sec-Validating-Requests" secid="6.1.1"> <h3 data-source="spec/Section%206%20--%20Execution.md#L51"><a href="#sec-Validating-Requests">6.1.1</a>Validating Requests</h3> As explained in the Validation section, only requests which pass all validation rules should be executed. If validation errors are known, they should be reported in the list of “errors” in the response and the request must fail without execution. Typically validation is performed in the context of a request immediately before execution, however a GraphQL service may execute a request without immediately validating it if that exact same request is known to have been validated before. A GraphQL service should only execute requests which at some point were known to be free of any validation errors, and have since not changed. For example: the request may be validated during development, provided it does not later change, or a service may validate a request once and memoize the result to avoid validating the same request again in the future. </section> <section id="sec-Coercing-Variable-Values" secid="6.1.2"> <h3 data-source="spec/Section%206%20--%20Execution.md#L70"><a href="#sec-Coercing-Variable-Values">6.1.2</a>Coercing Variable Values</h3> If the operation has defined any variables, then the values for those variables need to be coerced using the input coercion rules of variable’s declared type. If a request error is encountered during input coercion of variable values, then the operation fails without execution. <div class="spec-algo" id="CoerceVariableValues()" data-source="spec/Section%206%20--%20Execution.md#L78-L107"> <a href="#CoerceVariableValues()" data-name="CoerceVariableValues">CoerceVariableValues</a>(<var data-name="schema">schema</var>, <var data-name="operation">operation</var>, <var data-name="variableValues">variableValues</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L80">Let <var data-name="coercedValues">coercedValues</var> be an empty unordered Map.</li> <li data-source="spec/Section%206%20--%20Execution.md#L81">Let <var data-name="variableDefinitions">variableDefinitions</var> be the variables defined by <var data-name="operation">operation</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L82-L106">For each <var data-name="variableDefinition">variableDefinition</var> in <var data-name="variableDefinitions">variableDefinitions</var>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L83">Let <var data-name="variableName">variableName</var> be the name of <var data-name="variableDefinition">variableDefinition</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L84">Let <var data-name="variableType">variableType</var> be the expected type of <var data-name="variableDefinition">variableDefinition</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L85">Assert: <a href="#IsInputType()" data-name="IsInputType">IsInputType</a>(<var data-name="variableType">variableType</var>) must be true.</li> <li data-source="spec/Section%206%20--%20Execution.md#L86">Let <var data-name="defaultValue">defaultValue</var> be the default value for <var data-name="variableDefinition">variableDefinition</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L87-L88">Let <var data-name="hasValue">hasValue</var> be true if <var data-name="variableValues">variableValues</var> provides a value for the name <var data-name="variableName">variableName</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L89-L90">Let <var data-name="value">value</var> be the value provided in <var data-name="variableValues">variableValues</var> for the name <var data-name="variableName">variableName</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L91-L93">If <var data-name="hasValue">hasValue</var> is not true and <var data-name="defaultValue">defaultValue</var> exists (including null):<ol> <li data-source="spec/Section%206%20--%20Execution.md#L92-L93">Add an entry to <var data-name="coercedValues">coercedValues</var> named <var data-name="variableName">variableName</var> with the value <var data-name="defaultValue">defaultValue</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L94-L95">Otherwise if <var data-name="variableType">variableType</var> is a Non-Nullable type, and either <var data-name="hasValue">hasValue</var> is not true or <var data-name="value">value</var> is null, raise a request error.</li> <li data-source="spec/Section%206%20--%20Execution.md#L96-L106">Otherwise if <var data-name="hasValue">hasValue</var> is true:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L97-L99">If <var data-name="value">value</var> is null:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L98-L99">Add an entry to <var data-name="coercedValues">coercedValues</var> named <var data-name="variableName">variableName</var> with the value null.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L100-L106">Otherwise:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L101-L102">If <var data-name="value">value</var> cannot be coerced according to the input coercion rules of <var data-name="variableType">variableType</var>, raise a request error.</li> <li data-source="spec/Section%206%20--%20Execution.md#L103-L104">Let <var data-name="coercedValue">coercedValue</var> be the result of coercing <var data-name="value">value</var> according to the input coercion rules of <var data-name="variableType">variableType</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L105-L106">Add an entry to <var data-name="coercedValues">coercedValues</var> named <var data-name="variableName">variableName</var> with the value <var data-name="coercedValue">coercedValue</var>.</li> </ol> </li> </ol> </li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L107">Return <var data-name="coercedValues">coercedValues</var>.</li> </ol> </div> <div id="note-38e04" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L109"> <a href="#note-38e04">Note</a> This algorithm is very similar to <a href="#CoerceArgumentValues()" data-name="CoerceArgumentValues">CoerceArgumentValues</a>().</div> </section> </section> <section id="sec-Executing-Operations" secid="6.2"> <h2 data-source="spec/Section%206%20--%20Execution.md#L112"><a href="#sec-Executing-Operations">6.2</a>Executing Operations</h2> The type system, as described in the “Type System” section of the spec, must provide a query root operation type. If mutations or subscriptions are supported, it must also provide a mutation or subscription root operation type, respectively. <section id="sec-Query" secid="6.2.1"> <h3 data-source="spec/Section%206%20--%20Execution.md#L118"><a href="#sec-Query">6.2.1</a>Query</h3> If the operation is a query, the result of the operation is the result of executing the operation’s top level selection set with the query root operation type. An initial value may be provided when executing a query operation. <div class="spec-algo" id="ExecuteQuery()" data-source="spec/Section%206%20--%20Execution.md#L126-L136"> <a href="#ExecuteQuery()" data-name="ExecuteQuery">ExecuteQuery</a>(<var data-name="query">query</var>, <var data-name="schema">schema</var>, <var data-name="variableValues">variableValues</var>, <var data-name="initialValue">initialValue</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L128">Let <var data-name="queryType">queryType</var> be the root Query type in <var data-name="schema">schema</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L129">Assert: <var data-name="queryType">queryType</var> is an Object type.</li> <li data-source="spec/Section%206%20--%20Execution.md#L130">Let <var data-name="selectionSet">selectionSet</var> be the top level Selection Set in <var data-name="query">query</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L131-L133">Let <var data-name="data">data</var> be the result of running <a href="#ExecuteSelectionSet()" data-name="ExecuteSelectionSet">ExecuteSelectionSet</a>(<var data-name="selectionSet">selectionSet</var>, <var data-name="queryType">queryType</var>, <var data-name="initialValue">initialValue</var>, <var data-name="variableValues">variableValues</var>) normally (allowing parallelization).</li> <li data-source="spec/Section%206%20--%20Execution.md#L134-L135">Let <var data-name="errors">errors</var> be any field errors produced while executing the selection set.</li> <li data-source="spec/Section%206%20--%20Execution.md#L136">Return an unordered map containing <var data-name="data">data</var> and <var data-name="errors">errors</var>.</li> </ol> </div> </section> <section id="sec-Mutation" secid="6.2.2"> <h3 data-source="spec/Section%206%20--%20Execution.md#L138"><a href="#sec-Mutation">6.2.2</a>Mutation</h3> If the operation is a mutation, the result of the operation is the result of executing the operation’s top level selection set on the mutation root object type. This selection set should be executed serially. It is expected that the top level fields in a mutation operation perform side-effects on the underlying data system. Serial execution of the provided mutations ensures against race conditions during these side-effects. <div class="spec-algo" id="ExecuteMutation()" data-source="spec/Section%206%20--%20Execution.md#L148-L158"> <a href="#ExecuteMutation()" data-name="ExecuteMutation">ExecuteMutation</a>(<var data-name="mutation">mutation</var>, <var data-name="schema">schema</var>, <var data-name="variableValues">variableValues</var>, <var data-name="initialValue">initialValue</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L150">Let <var data-name="mutationType">mutationType</var> be the root Mutation type in <var data-name="schema">schema</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L151">Assert: <var data-name="mutationType">mutationType</var> is an Object type.</li> <li data-source="spec/Section%206%20--%20Execution.md#L152">Let <var data-name="selectionSet">selectionSet</var> be the top level Selection Set in <var data-name="mutation">mutation</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L153-L155">Let <var data-name="data">data</var> be the result of running <a href="#ExecuteSelectionSet()" data-name="ExecuteSelectionSet">ExecuteSelectionSet</a>(<var data-name="selectionSet">selectionSet</var>, <var data-name="mutationType">mutationType</var>, <var data-name="initialValue">initialValue</var>, <var data-name="variableValues">variableValues</var>) serially.</li> <li data-source="spec/Section%206%20--%20Execution.md#L156-L157">Let <var data-name="errors">errors</var> be any field errors produced while executing the selection set.</li> <li data-source="spec/Section%206%20--%20Execution.md#L158">Return an unordered map containing <var data-name="data">data</var> and <var data-name="errors">errors</var>.</li> </ol> </div> </section> <section id="sec-Subscription" secid="6.2.3"> <h3 data-source="spec/Section%206%20--%20Execution.md#L160"><a href="#sec-Subscription">6.2.3</a>Subscription</h3> If the operation is a subscription, the result is an event stream called the “Response Stream” where each event in the event stream is the result of executing the operation for each new event on an underlying “Source Stream”. Executing a subscription operation creates a persistent function on the service that maps an underlying Source Stream to a returned Response Stream. <div class="spec-algo" id="Subscribe()" data-source="spec/Section%206%20--%20Execution.md#L169-L173"> <a href="#Subscribe()" data-name="Subscribe">Subscribe</a>(<var data-name="subscription">subscription</var>, <var data-name="schema">schema</var>, <var data-name="variableValues">variableValues</var>, <var data-name="initialValue">initialValue</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L171">Let <var data-name="sourceStream">sourceStream</var> be the result of running <a href="#CreateSourceEventStream()" data-name="CreateSourceEventStream">CreateSourceEventStream</a>(<var data-name="subscription">subscription</var>, <var data-name="schema">schema</var>, <var data-name="variableValues">variableValues</var>, <var data-name="initialValue">initialValue</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L172">Let <var data-name="responseStream">responseStream</var> be the result of running <a href="#MapSourceToResponseEvent()" data-name="MapSourceToResponseEvent">MapSourceToResponseEvent</a>(<var data-name="sourceStream">sourceStream</var>, <var data-name="subscription">subscription</var>, <var data-name="schema">schema</var>, <var data-name="variableValues">variableValues</var>)</li> <li data-source="spec/Section%206%20--%20Execution.md#L173">Return <var data-name="responseStream">responseStream</var>.</li> </ol> </div> <div id="note-79d56" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L175-L178"> <a href="#note-79d56">Note</a> In large scale subscription systems, the <a href="#Subscribe()" data-name="Subscribe">Subscribe</a>() and <a href="#ExecuteSubscriptionEvent()" data-name="ExecuteSubscriptionEvent">ExecuteSubscriptionEvent</a>() algorithms may be run on separate services to maintain predictable scaling properties. See the section below on Supporting Subscriptions at Scale.</div> As an example, consider a chat application. To subscribe to new messages posted to the chat room, the client sends a request like so: <pre id="example-2a5f0" class="spec-example" data-language="graphql" data-source="spec/Section%206%20--%20Execution.md#L183-L190"><a href="#example-2a5f0">Example № 188</a><code>subscription NewMessages { newMessage(roomId: 123) { sender text } } </code></pre> While the client is subscribed, whenever new messages are posted to chat room with ID “123”, the selection for “sender” and “text” will be evaluated and published to the client, for example: <pre id="example-a4629" class="spec-example" data-language="json" data-source="spec/Section%206%20--%20Execution.md#L196-L205"><a href="#example-a4629">Example № 189</a><code>{ "data": { "newMessage": { "sender": "Hagrid", "text": "You're a wizard!" } } } </code></pre> The “new message posted to chat room” could use a “Pub-Sub” system where the chat room ID is the “topic” and each “publish” contains the sender and text. <section id="sec-Subscription.Event-Streams" class="subsec"> <h6 data-source="spec/Section%206%20--%20Execution.md#L210"><a href="#sec-Subscription.Event-Streams" title="link to this subsection">Event Streams</a></h6> An event stream represents a sequence of discrete events over time which can be observed. As an example, a “Pub-Sub” system may produce an event stream when “subscribing to a topic”, with an event occurring on that event stream for each “publish” to that topic. Event streams may produce an infinite sequence of events or may complete at any point. Event streams may complete in response to an error or simply because no more events will occur. An observer may at any point decide to stop observing an event stream by cancelling it, after which it must receive no more events from that event stream. </section> <section id="sec-Subscription.Supporting-Subscriptions-at-Scale" class="subsec"> <h6 data-source="spec/Section%206%20--%20Execution.md#L221"><a href="#sec-Subscription.Supporting-Subscriptions-at-Scale" title="link to this subsection">Supporting Subscriptions at Scale</a></h6> Supporting subscriptions is a significant change for any GraphQL service. Query and mutation operations are stateless, allowing scaling via cloning of GraphQL service instances. Subscriptions, by contrast, are stateful and require maintaining the GraphQL document, variables, and other context over the lifetime of the subscription. Consider the behavior of your system when state is lost due to the failure of a single machine in a service. Durability and availability may be improved by having separate dedicated services for managing subscription state and client connectivity. </section> <section id="sec-Subscription.Delivery-Agnostic" class="subsec"> <h6 data-source="spec/Section%206%20--%20Execution.md#L234"><a href="#sec-Subscription.Delivery-Agnostic" title="link to this subsection">Delivery Agnostic</a></h6> GraphQL subscriptions do not require any specific serialization format or transport mechanism. Subscriptions specifies algorithms for the creation of a stream, the content of each payload on that stream, and the closing of that stream. There are intentionally no specifications for message acknowledgement, buffering, resend requests, or any other quality of service (QoS) details. Message serialization, transport mechanisms, and quality of service details should be chosen by the implementing service. </section> <section id="sec-Source-Stream" secid="6.2.3.1"> <h4 data-source="spec/Section%206%20--%20Execution.md#L244"><a href="#sec-Source-Stream">6.2.3.1</a>Source Stream</h4> A Source Stream represents the sequence of events, each of which will trigger a GraphQL execution corresponding to that event. Like field value resolution, the logic to create a Source Stream is application-specific. <div class="spec-algo" id="CreateSourceEventStream()" data-source="spec/Section%206%20--%20Execution.md#L250-L264"> <a href="#CreateSourceEventStream()" data-name="CreateSourceEventStream">CreateSourceEventStream</a>(<var data-name="subscription">subscription</var>, <var data-name="schema">schema</var>, <var data-name="variableValues">variableValues</var>, <var data-name="initialValue">initialValue</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L252">Let <var data-name="subscriptionType">subscriptionType</var> be the root Subscription type in <var data-name="schema">schema</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L253">Assert: <var data-name="subscriptionType">subscriptionType</var> is an Object type.</li> <li data-source="spec/Section%206%20--%20Execution.md#L254">Let <var data-name="selectionSet">selectionSet</var> be the top level Selection Set in <var data-name="subscription">subscription</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L255-L256">Let <var data-name="groupedFieldSet">groupedFieldSet</var> be the result of <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>(<var data-name="subscriptionType">subscriptionType</var>, <var data-name="selectionSet">selectionSet</var>, <var data-name="variableValues">variableValues</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L257">If <var data-name="groupedFieldSet">groupedFieldSet</var> does not have exactly one entry, raise a request error.</li> <li data-source="spec/Section%206%20--%20Execution.md#L258">Let <var data-name="fields">fields</var> be the value of the first entry in <var data-name="groupedFieldSet">groupedFieldSet</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L259-L260">Let <var data-name="fieldName">fieldName</var> be the name of the first entry in <var data-name="fields">fields</var>. Note: This value is unaffected if an alias is used.</li> <li data-source="spec/Section%206%20--%20Execution.md#L261">Let <var data-name="field">field</var> be the first entry in <var data-name="fields">fields</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L262">Let <var data-name="argumentValues">argumentValues</var> be the result of <a href="#CoerceArgumentValues()" data-name="CoerceArgumentValues">CoerceArgumentValues</a>(<var data-name="subscriptionType">subscriptionType</var>, <var data-name="field">field</var>, <var data-name="variableValues">variableValues</var>)</li> <li data-source="spec/Section%206%20--%20Execution.md#L263">Let <var data-name="fieldStream">fieldStream</var> be the result of running <a href="#ResolveFieldEventStream()" data-name="ResolveFieldEventStream">ResolveFieldEventStream</a>(<var data-name="subscriptionType">subscriptionType</var>, <var data-name="initialValue">initialValue</var>, <var data-name="fieldName">fieldName</var>, <var data-name="argumentValues">argumentValues</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L264">Return <var data-name="fieldStream">fieldStream</var>.</li> </ol> </div> <div class="spec-algo" id="ResolveFieldEventStream()" data-source="spec/Section%206%20--%20Execution.md#L266-L269"> <a href="#ResolveFieldEventStream()" data-name="ResolveFieldEventStream">ResolveFieldEventStream</a>(<var data-name="subscriptionType">subscriptionType</var>, <var data-name="rootValue">rootValue</var>, <var data-name="fieldName">fieldName</var>, <var data-name="argumentValues">argumentValues</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L267-L268">Let <var data-name="resolver">resolver</var> be the internal function provided by <var data-name="subscriptionType">subscriptionType</var> for determining the resolved event stream of a subscription field named <var data-name="fieldName">fieldName</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L269">Return the result of calling <var data-name="resolver">resolver</var>, providing <var data-name="rootValue">rootValue</var> and <var data-name="argumentValues">argumentValues</var>.</li> </ol> </div> <div id="note-5869a" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L271-L273"> <a href="#note-5869a">Note</a> This <a href="#ResolveFieldEventStream()" data-name="ResolveFieldEventStream">ResolveFieldEventStream</a>() algorithm is intentionally similar to <a href="#ResolveFieldValue()" data-name="ResolveFieldValue">ResolveFieldValue</a>() to enable consistency when defining resolvers on any operation type.</div> </section> <section id="sec-Response-Stream" secid="6.2.3.2"> <h4 data-source="spec/Section%206%20--%20Execution.md#L275"><a href="#sec-Response-Stream">6.2.3.2</a>Response Stream</h4> Each event in the underlying Source Stream triggers execution of the subscription selection set using that event as a root value. <div class="spec-algo" id="MapSourceToResponseEvent()" data-source="spec/Section%206%20--%20Execution.md#L280-L287"> <a href="#MapSourceToResponseEvent()" data-name="MapSourceToResponseEvent">MapSourceToResponseEvent</a>(<var data-name="sourceStream">sourceStream</var>, <var data-name="subscription">subscription</var>, <var data-name="schema">schema</var>, <var data-name="variableValues">variableValues</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L282">Return a new event stream <var data-name="responseStream">responseStream</var> which yields events as follows:</li> <li data-source="spec/Section%206%20--%20Execution.md#L283-L286">For each <var data-name="event">event</var> on <var data-name="sourceStream">sourceStream</var>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L284-L285">Let <var data-name="response">response</var> be the result of running <a href="#ExecuteSubscriptionEvent()" data-name="ExecuteSubscriptionEvent">ExecuteSubscriptionEvent</a>(<var data-name="subscription">subscription</var>, <var data-name="schema">schema</var>, <var data-name="variableValues">variableValues</var>, <var data-name="event">event</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L286">Yield an event containing <var data-name="response">response</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L287">When <var data-name="responseStream">responseStream</var> completes: complete this event stream.</li> </ol> </div> <div class="spec-algo" id="ExecuteSubscriptionEvent()" data-source="spec/Section%206%20--%20Execution.md#L289-L299"> <a href="#ExecuteSubscriptionEvent()" data-name="ExecuteSubscriptionEvent">ExecuteSubscriptionEvent</a>(<var data-name="subscription">subscription</var>, <var data-name="schema">schema</var>, <var data-name="variableValues">variableValues</var>, <var data-name="initialValue">initialValue</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L291">Let <var data-name="subscriptionType">subscriptionType</var> be the root Subscription type in <var data-name="schema">schema</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L292">Assert: <var data-name="subscriptionType">subscriptionType</var> is an Object type.</li> <li data-source="spec/Section%206%20--%20Execution.md#L293">Let <var data-name="selectionSet">selectionSet</var> be the top level Selection Set in <var data-name="subscription">subscription</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L294-L296">Let <var data-name="data">data</var> be the result of running <a href="#ExecuteSelectionSet()" data-name="ExecuteSelectionSet">ExecuteSelectionSet</a>(<var data-name="selectionSet">selectionSet</var>, <var data-name="subscriptionType">subscriptionType</var>, <var data-name="initialValue">initialValue</var>, <var data-name="variableValues">variableValues</var>) normally (allowing parallelization).</li> <li data-source="spec/Section%206%20--%20Execution.md#L297-L298">Let <var data-name="errors">errors</var> be any field errors produced while executing the selection set.</li> <li data-source="spec/Section%206%20--%20Execution.md#L299">Return an unordered map containing <var data-name="data">data</var> and <var data-name="errors">errors</var>.</li> </ol> </div> <div id="note-5fb9c" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L301-L302"> <a href="#note-5fb9c">Note</a> The <a href="#ExecuteSubscriptionEvent()" data-name="ExecuteSubscriptionEvent">ExecuteSubscriptionEvent</a>() algorithm is intentionally similar to <a href="#ExecuteQuery()" data-name="ExecuteQuery">ExecuteQuery</a>() since this is how each event result is produced.</div> </section> <section id="sec-Unsubscribe" secid="6.2.3.3"> <h4 data-source="spec/Section%206%20--%20Execution.md#L304"><a href="#sec-Unsubscribe">6.2.3.3</a>Unsubscribe</h4> Unsubscribe cancels the Response Stream when a client no longer wishes to receive payloads for a subscription. This may in turn also cancel the Source Stream. This is also a good opportunity to clean up any other resources used by the subscription. <div class="spec-algo" id="Unsubscribe()" data-source="spec/Section%206%20--%20Execution.md#L311-L313"> <a href="#Unsubscribe()" data-name="Unsubscribe">Unsubscribe</a>(<var data-name="responseStream">responseStream</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L313">Cancel <var data-name="responseStream">responseStream</var></li> </ol> </div> </section> </section> </section> <section id="sec-Executing-Selection-Sets" secid="6.3"> <h2 data-source="spec/Section%206%20--%20Execution.md#L315"><a href="#sec-Executing-Selection-Sets">6.3</a>Executing Selection Sets</h2> To execute a selection set, the object value being evaluated and the object type need to be known, as well as whether it must be executed serially, or may be executed in parallel. First, the selection set is turned into a grouped field set; then, each represented field in the grouped field set produces an entry into a response map. <div class="spec-algo" id="ExecuteSelectionSet()" data-source="spec/Section%206%20--%20Execution.md#L325-L337"> <a href="#ExecuteSelectionSet()" data-name="ExecuteSelectionSet">ExecuteSelectionSet</a>(<var data-name="selectionSet">selectionSet</var>, <var data-name="objectType">objectType</var>, <var data-name="objectValue">objectValue</var>, <var data-name="variableValues">variableValues</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L327-L328">Let <var data-name="groupedFieldSet">groupedFieldSet</var> be the result of <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>(<var data-name="objectType">objectType</var>, <var data-name="selectionSet">selectionSet</var>, <var data-name="variableValues">variableValues</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L329">Initialize <var data-name="resultMap">resultMap</var> to an empty ordered map.</li> <li data-source="spec/Section%206%20--%20Execution.md#L330-L336">For each <var data-name="groupedFieldSet">groupedFieldSet</var> as <var data-name="responseKey">responseKey</var> and <var data-name="fields">fields</var>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L331-L332">Let <var data-name="fieldName">fieldName</var> be the name of the first entry in <var data-name="fields">fields</var>. Note: This value is unaffected if an alias is used.</li> <li data-source="spec/Section%206%20--%20Execution.md#L333">Let <var data-name="fieldType">fieldType</var> be the return type defined for the field <var data-name="fieldName">fieldName</var> of <var data-name="objectType">objectType</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L334-L336">If <var data-name="fieldType">fieldType</var> is defined:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L335">Let <var data-name="responseValue">responseValue</var> be <a href="#ExecuteField()" data-name="ExecuteField">ExecuteField</a>(<var data-name="objectType">objectType</var>, <var data-name="objectValue">objectValue</var>, <var data-name="fieldType">fieldType</var>, <var data-name="fields">fields</var>, <var data-name="variableValues">variableValues</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L336">Set <var data-name="responseValue">responseValue</var> as the value for <var data-name="responseKey">responseKey</var> in <var data-name="resultMap">resultMap</var>.</li> </ol> </li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L337">Return <var data-name="resultMap">resultMap</var>.</li> </ol> </div> <div id="note-b8f81" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L339-L340"> <a href="#note-b8f81">Note</a> <var data-name="resultMap">resultMap</var> is ordered by which fields appear first in the operation. This is explained in greater detail in the Field Collection section below.</div> <section id="sec-Executing-Selection-Sets.Errors-and-Non-Null-Fields" class="subsec"> <h6 data-source="spec/Section%206%20--%20Execution.md#L342"><a href="#sec-Executing-Selection-Sets.Errors-and-Non-Null-Fields" title="link to this subsection">Errors and Non-Null Fields</a></h6> If during <a href="#ExecuteSelectionSet()" data-name="ExecuteSelectionSet">ExecuteSelectionSet</a>() a field with a non-null <var data-name="fieldType">fieldType</var> raises a field error then that error must propagate to this entire selection set, either resolving to null if allowed or further propagated to a parent field. If this occurs, any sibling fields which have not yet executed or have not yet yielded a value may be cancelled to avoid unnecessary work. <div id="note-4dd38" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L351-L352"> <a href="#note-4dd38">Note</a> See <a href="#sec-Handling-Field-Errors">Handling Field Errors</a> for more about this behavior.</div> </section> <section id="sec-Normal-and-Serial-Execution" secid="6.3.1"> <h3 data-source="spec/Section%206%20--%20Execution.md#L354"><a href="#sec-Normal-and-Serial-Execution">6.3.1</a>Normal and Serial Execution</h3> Normally the executor can execute the entries in a grouped field set in whatever order it chooses (normally in parallel). Because the resolution of fields other than top-level mutation fields must always be side effect-free and idempotent, the execution order must not affect the result, and hence the service has the freedom to execute the field entries in whatever order it deems optimal. For example, given the following grouped field set to be executed normally: <pre id="example-65e7d" class="spec-example" data-language="graphql" data-source="spec/Section%206%20--%20Execution.md#L364-L373"><a href="#example-65e7d">Example № 190</a><code>{ birthday { month } address { street } } </code></pre> A valid GraphQL executor can resolve the four fields in whatever order it chose (however of course <code>birthday</code> must be resolved before <code>month</code>, and <code>address</code> before <code>street</code>). When executing a mutation, the selections in the top most selection set will be executed in serial order, starting with the first appearing field textually. When executing a grouped field set serially, the executor must consider each entry from the grouped field set in the order provided in the grouped field set. It must determine the corresponding entry in the result map for each item to completion before it continues on to the next item in the grouped field set: For example, given the following selection set to be executed serially: <pre id="example-33b6a" class="spec-example" data-language="graphql" data-source="spec/Section%206%20--%20Execution.md#L389-L398"><a href="#example-33b6a">Example № 191</a><code>{ changeBirthday(birthday: $newBirthday) { month } changeAddress(address: $newAddress) { street } } </code></pre> The executor must, in serial: <ul> <li data-source="spec/Section%206%20--%20Execution.md#L402-L403">Run <a href="#ExecuteField()" data-name="ExecuteField">ExecuteField</a>() for <code>changeBirthday</code>, which during <a href="#CompleteValue()" data-name="CompleteValue">CompleteValue</a>() will execute the <code>{ month }</code> sub-selection set normally.</li> <li data-source="spec/Section%206%20--%20Execution.md#L404-L405">Run <a href="#ExecuteField()" data-name="ExecuteField">ExecuteField</a>() for <code>changeAddress</code>, which during <a href="#CompleteValue()" data-name="CompleteValue">CompleteValue</a>() will execute the <code>{ street }</code> sub-selection set normally.</li> </ul> As an illustrative example, let’s assume we have a mutation field <code>changeTheNumber</code> that returns an object containing one field, <code>theNumber</code>. If we execute the following selection set serially: <pre id="example-c91a3" class="spec-example" data-language="graphql" data-source="spec/Section%206%20--%20Execution.md#L411-L423"><a href="#example-c91a3">Example № 192</a><code>{ first: changeTheNumber(newNumber: 1) { theNumber } second: changeTheNumber(newNumber: 3) { theNumber } third: changeTheNumber(newNumber: 2) { theNumber } } </code></pre> The executor will execute the following serially: <ul> <li data-source="spec/Section%206%20--%20Execution.md#L427">Resolve the <code>changeTheNumber(newNumber: 1)</code> field</li> <li data-source="spec/Section%206%20--%20Execution.md#L428">Execute the <code>{ theNumber }</code> sub-selection set of <code>first</code> normally</li> <li data-source="spec/Section%206%20--%20Execution.md#L429">Resolve the <code>changeTheNumber(newNumber: 3)</code> field</li> <li data-source="spec/Section%206%20--%20Execution.md#L430">Execute the <code>{ theNumber }</code> sub-selection set of <code>second</code> normally</li> <li data-source="spec/Section%206%20--%20Execution.md#L431">Resolve the <code>changeTheNumber(newNumber: 2)</code> field</li> <li data-source="spec/Section%206%20--%20Execution.md#L432">Execute the <code>{ theNumber }</code> sub-selection set of <code>third</code> normally</li> </ul> A correct executor must generate the following result for that selection set: <pre id="example-1d82c" class="spec-example" data-language="json" data-source="spec/Section%206%20--%20Execution.md#L436-L448"><a href="#example-1d82c">Example № 193</a><code>{ "first": { "theNumber": 1 }, "second": { "theNumber": 3 }, "third": { "theNumber": 2 } } </code></pre> </section> <section id="sec-Field-Collection" secid="6.3.2"> <h3 data-source="spec/Section%206%20--%20Execution.md#L451"><a href="#sec-Field-Collection">6.3.2</a>Field Collection</h3> Before execution, the selection set is converted to a grouped field set by calling <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>(). Each entry in the grouped field set is a list of fields that share a response key (the alias if defined, otherwise the field name). This ensures all fields with the same response key (including those in referenced fragments) are executed at the same time. As an example, collecting the fields of this selection set would collect two instances of the field <code>a</code> and one of field <code>b</code>: <pre id="example-fdbb7" class="spec-example" data-language="graphql" data-source="spec/Section%206%20--%20Execution.md#L462-L476"><a href="#example-fdbb7">Example № 194</a><code>{ a { subfield1 } ...ExampleFragment } fragment ExampleFragment on Query { a { subfield2 } b } </code></pre> The depth-first-search order of the field groups produced by <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>() is maintained through execution, ensuring that fields appear in the executed response in a stable and predictable order. <div class="spec-algo" id="CollectFields()" data-source="spec/Section%206%20--%20Execution.md#L482-L529"> <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>(<var data-name="objectType">objectType</var>, <var data-name="selectionSet">selectionSet</var>, <var data-name="variableValues">variableValues</var>, <var data-name="visitedFragments">visitedFragments</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L484">If <var data-name="visitedFragments">visitedFragments</var> is not provided, initialize it to the empty set.</li> <li data-source="spec/Section%206%20--%20Execution.md#L485">Initialize <var data-name="groupedFields">groupedFields</var> to an empty ordered map of lists.</li> <li data-source="spec/Section%206%20--%20Execution.md#L486-L528">For each <var data-name="selection">selection</var> in <var data-name="selectionSet">selectionSet</var>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L487-L489">If <var data-name="selection">selection</var> provides the directive <code>@skip</code>, let <var data-name="skipDirective">skipDirective</var> be that directive.<ol> <li data-source="spec/Section%206%20--%20Execution.md#L488-L489">If <var data-name="skipDirective">skipDirective</var>‘s <var data-name="if">if</var> argument is true or is a variable in <var data-name="variableValues">variableValues</var> with the value true, continue with the next <var data-name="selection">selection</var> in <var data-name="selectionSet">selectionSet</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L490-L492">If <var data-name="selection">selection</var> provides the directive <code>@include</code>, let <var data-name="includeDirective">includeDirective</var> be that directive.<ol> <li data-source="spec/Section%206%20--%20Execution.md#L491-L492">If <var data-name="includeDirective">includeDirective</var>‘s <var data-name="if">if</var> argument is not true and is not a variable in <var data-name="variableValues">variableValues</var> with the value true, continue with the next <var data-name="selection">selection</var> in <var data-name="selectionSet">selectionSet</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L493-L497">If <var data-name="selection">selection</var> is a <a href="#Field" data-name="Field">Field</a>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L494">Let <var data-name="responseKey">responseKey</var> be the response key of <var data-name="selection">selection</var> (the alias if defined, otherwise the field name).</li> <li data-source="spec/Section%206%20--%20Execution.md#L495-L496">Let <var data-name="groupForResponseKey">groupForResponseKey</var> be the list in <var data-name="groupedFields">groupedFields</var> for <var data-name="responseKey">responseKey</var>; if no such list exists, create it as an empty list.</li> <li data-source="spec/Section%206%20--%20Execution.md#L497">Append <var data-name="selection">selection</var> to the <var data-name="groupForResponseKey">groupForResponseKey</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L498-L517">If <var data-name="selection">selection</var> is a <a href="#FragmentSpread" data-name="FragmentSpread">FragmentSpread</a>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L499">Let <var data-name="fragmentSpreadName">fragmentSpreadName</var> be the name of <var data-name="selection">selection</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L500-L501">If <var data-name="fragmentSpreadName">fragmentSpreadName</var> is in <var data-name="visitedFragments">visitedFragments</var>, continue with the next <var data-name="selection">selection</var> in <var data-name="selectionSet">selectionSet</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L502">Add <var data-name="fragmentSpreadName">fragmentSpreadName</var> to <var data-name="visitedFragments">visitedFragments</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L503-L504">Let <var data-name="fragment">fragment</var> be the Fragment in the current Document whose name is <var data-name="fragmentSpreadName">fragmentSpreadName</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L505-L506">If no such <var data-name="fragment">fragment</var> exists, continue with the next <var data-name="selection">selection</var> in <var data-name="selectionSet">selectionSet</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L507">Let <var data-name="fragmentType">fragmentType</var> be the type condition on <var data-name="fragment">fragment</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L508-L509">If <a href="#DoesFragmentTypeApply()" data-name="DoesFragmentTypeApply">DoesFragmentTypeApply</a>(<var data-name="objectType">objectType</var>, <var data-name="fragmentType">fragmentType</var>) is false, continue with the next <var data-name="selection">selection</var> in <var data-name="selectionSet">selectionSet</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L510">Let <var data-name="fragmentSelectionSet">fragmentSelectionSet</var> be the top-level selection set of <var data-name="fragment">fragment</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L511-L512">Let <var data-name="fragmentGroupedFieldSet">fragmentGroupedFieldSet</var> be the result of calling <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>(<var data-name="objectType">objectType</var>, <var data-name="fragmentSelectionSet">fragmentSelectionSet</var>, <var data-name="variableValues">variableValues</var>, <var data-name="visitedFragments">visitedFragments</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L513-L517">For each <var data-name="fragmentGroup">fragmentGroup</var> in <var data-name="fragmentGroupedFieldSet">fragmentGroupedFieldSet</var>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L514">Let <var data-name="responseKey">responseKey</var> be the response key shared by all fields in <var data-name="fragmentGroup">fragmentGroup</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L515-L516">Let <var data-name="groupForResponseKey">groupForResponseKey</var> be the list in <var data-name="groupedFields">groupedFields</var> for <var data-name="responseKey">responseKey</var>; if no such list exists, create it as an empty list.</li> <li data-source="spec/Section%206%20--%20Execution.md#L517">Append all items in <var data-name="fragmentGroup">fragmentGroup</var> to <var data-name="groupForResponseKey">groupForResponseKey</var>.</li> </ol> </li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L518-L528">If <var data-name="selection">selection</var> is an <a href="#InlineFragment" data-name="InlineFragment">InlineFragment</a>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L519">Let <var data-name="fragmentType">fragmentType</var> be the type condition on <var data-name="selection">selection</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L520-L521">If <var data-name="fragmentType">fragmentType</var> is not null and <a href="#DoesFragmentTypeApply()" data-name="DoesFragmentTypeApply">DoesFragmentTypeApply</a>(<var data-name="objectType">objectType</var>, <var data-name="fragmentType">fragmentType</var>) is false, continue with the next <var data-name="selection">selection</var> in <var data-name="selectionSet">selectionSet</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L522">Let <var data-name="fragmentSelectionSet">fragmentSelectionSet</var> be the top-level selection set of <var data-name="selection">selection</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L523">Let <var data-name="fragmentGroupedFieldSet">fragmentGroupedFieldSet</var> be the result of calling <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>(<var data-name="objectType">objectType</var>, <var data-name="fragmentSelectionSet">fragmentSelectionSet</var>, <var data-name="variableValues">variableValues</var>, <var data-name="visitedFragments">visitedFragments</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L524-L528">For each <var data-name="fragmentGroup">fragmentGroup</var> in <var data-name="fragmentGroupedFieldSet">fragmentGroupedFieldSet</var>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L525">Let <var data-name="responseKey">responseKey</var> be the response key shared by all fields in <var data-name="fragmentGroup">fragmentGroup</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L526-L527">Let <var data-name="groupForResponseKey">groupForResponseKey</var> be the list in <var data-name="groupedFields">groupedFields</var> for <var data-name="responseKey">responseKey</var>; if no such list exists, create it as an empty list.</li> <li data-source="spec/Section%206%20--%20Execution.md#L528">Append all items in <var data-name="fragmentGroup">fragmentGroup</var> to <var data-name="groupForResponseKey">groupForResponseKey</var>.</li> </ol> </li> </ol> </li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L529">Return <var data-name="groupedFields">groupedFields</var>.</li> </ol> </div> <div class="spec-algo" id="DoesFragmentTypeApply()" data-source="spec/Section%206%20--%20Execution.md#L531-L538"> <a href="#DoesFragmentTypeApply()" data-name="DoesFragmentTypeApply">DoesFragmentTypeApply</a>(<var data-name="objectType">objectType</var>, <var data-name="fragmentType">fragmentType</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L533-L534">If <var data-name="fragmentType">fragmentType</var> is an Object Type:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L534">if <var data-name="objectType">objectType</var> and <var data-name="fragmentType">fragmentType</var> are the same type, return true, otherwise return false.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L535-L536">If <var data-name="fragmentType">fragmentType</var> is an Interface Type:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L536">if <var data-name="objectType">objectType</var> is an implementation of <var data-name="fragmentType">fragmentType</var>, return true otherwise return false.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L537-L538">If <var data-name="fragmentType">fragmentType</var> is a Union:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L538">if <var data-name="objectType">objectType</var> is a possible type of <var data-name="fragmentType">fragmentType</var>, return true otherwise return false.</li> </ol> </li> </ol> </div> <div id="note-f1a76" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L540-L541"> <a href="#note-f1a76">Note</a> The steps in <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>() evaluating the <code>@skip</code> and <code>@include</code> directives may be applied in either order since they apply commutatively.</div> </section> </section> <section id="sec-Executing-Fields" secid="6.4"> <h2 data-source="spec/Section%206%20--%20Execution.md#L544"><a href="#sec-Executing-Fields">6.4</a>Executing Fields</h2> Each field requested in the grouped field set that is defined on the selected objectType will result in an entry in the response map. Field execution first coerces any provided argument values, then resolves a value for the field, and finally completes that value either by recursively executing another selection set or coercing a scalar value. <div class="spec-algo" id="ExecuteField()" data-source="spec/Section%206%20--%20Execution.md#L552-L557"> <a href="#ExecuteField()" data-name="ExecuteField">ExecuteField</a>(<var data-name="objectType">objectType</var>, <var data-name="objectValue">objectValue</var>, <var data-name="fieldType">fieldType</var>, <var data-name="fields">fields</var>, <var data-name="variableValues">variableValues</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L553">Let <var data-name="field">field</var> be the first entry in <var data-name="fields">fields</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L554">Let <var data-name="fieldName">fieldName</var> be the field name of <var data-name="field">field</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L555">Let <var data-name="argumentValues">argumentValues</var> be the result of <a href="#CoerceArgumentValues()" data-name="CoerceArgumentValues">CoerceArgumentValues</a>(<var data-name="objectType">objectType</var>, <var data-name="field">field</var>, <var data-name="variableValues">variableValues</var>)</li> <li data-source="spec/Section%206%20--%20Execution.md#L556">Let <var data-name="resolvedValue">resolvedValue</var> be <a href="#ResolveFieldValue()" data-name="ResolveFieldValue">ResolveFieldValue</a>(<var data-name="objectType">objectType</var>, <var data-name="objectValue">objectValue</var>, <var data-name="fieldName">fieldName</var>, <var data-name="argumentValues">argumentValues</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L557">Return the result of <a href="#CompleteValue()" data-name="CompleteValue">CompleteValue</a>(<var data-name="fieldType">fieldType</var>, <var data-name="fields">fields</var>, <var data-name="resolvedValue">resolvedValue</var>, <var data-name="variableValues">variableValues</var>).</li> </ol> </div> <section id="sec-Coercing-Field-Arguments" secid="6.4.1"> <h3 data-source="spec/Section%206%20--%20Execution.md#L560"><a href="#sec-Coercing-Field-Arguments">6.4.1</a>Coercing Field Arguments</h3> Fields may include arguments which are provided to the underlying runtime in order to correctly produce a value. These arguments are defined by the field in the type system to have a specific input type. At each argument position in an operation may be a literal <a href="#Value" data-name="Value">Value</a>, or a <a href="#Variable" data-name="Variable">Variable</a> to be provided at runtime. <div class="spec-algo" id="CoerceArgumentValues()" data-source="spec/Section%206%20--%20Execution.md#L569-L609"> <a href="#CoerceArgumentValues()" data-name="CoerceArgumentValues">CoerceArgumentValues</a>(<var data-name="objectType">objectType</var>, <var data-name="field">field</var>, <var data-name="variableValues">variableValues</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L570">Let <var data-name="coercedValues">coercedValues</var> be an empty unordered Map.</li> <li data-source="spec/Section%206%20--%20Execution.md#L571">Let <var data-name="argumentValues">argumentValues</var> be the argument values provided in <var data-name="field">field</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L572">Let <var data-name="fieldName">fieldName</var> be the name of <var data-name="field">field</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L573-L574">Let <var data-name="argumentDefinitions">argumentDefinitions</var> be the arguments defined by <var data-name="objectType">objectType</var> for the field named <var data-name="fieldName">fieldName</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L575-L608">For each <var data-name="argumentDefinition">argumentDefinition</var> in <var data-name="argumentDefinitions">argumentDefinitions</var>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L576">Let <var data-name="argumentName">argumentName</var> be the name of <var data-name="argumentDefinition">argumentDefinition</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L577">Let <var data-name="argumentType">argumentType</var> be the expected type of <var data-name="argumentDefinition">argumentDefinition</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L578">Let <var data-name="defaultValue">defaultValue</var> be the default value for <var data-name="argumentDefinition">argumentDefinition</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L579-L580">Let <var data-name="hasValue">hasValue</var> be true if <var data-name="argumentValues">argumentValues</var> provides a value for the name <var data-name="argumentName">argumentName</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L581-L582">Let <var data-name="argumentValue">argumentValue</var> be the value provided in <var data-name="argumentValues">argumentValues</var> for the name <var data-name="argumentName">argumentName</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L583-L588">If <var data-name="argumentValue">argumentValue</var> is a <a href="#Variable" data-name="Variable">Variable</a>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L584">Let <var data-name="variableName">variableName</var> be the name of <var data-name="argumentValue">argumentValue</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L585-L586">Let <var data-name="hasValue">hasValue</var> be true if <var data-name="variableValues">variableValues</var> provides a value for the name <var data-name="variableName">variableName</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L587-L588">Let <var data-name="value">value</var> be the value provided in <var data-name="variableValues">variableValues</var> for the name <var data-name="variableName">variableName</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L589">Otherwise, let <var data-name="value">value</var> be <var data-name="argumentValue">argumentValue</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L590-L592">If <var data-name="hasValue">hasValue</var> is not true and <var data-name="defaultValue">defaultValue</var> exists (including null):<ol> <li data-source="spec/Section%206%20--%20Execution.md#L591-L592">Add an entry to <var data-name="coercedValues">coercedValues</var> named <var data-name="argumentName">argumentName</var> with the value <var data-name="defaultValue">defaultValue</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L593-L594">Otherwise if <var data-name="argumentType">argumentType</var> is a Non-Nullable type, and either <var data-name="hasValue">hasValue</var> is not true or <var data-name="value">value</var> is null, raise a field error.</li> <li data-source="spec/Section%206%20--%20Execution.md#L595-L608">Otherwise if <var data-name="hasValue">hasValue</var> is true:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L596-L598">If <var data-name="value">value</var> is null:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L597-L598">Add an entry to <var data-name="coercedValues">coercedValues</var> named <var data-name="argumentName">argumentName</var> with the value null.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L599-L601">Otherwise, if <var data-name="argumentValue">argumentValue</var> is a <a href="#Variable" data-name="Variable">Variable</a>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L600-L601">Add an entry to <var data-name="coercedValues">coercedValues</var> named <var data-name="argumentName">argumentName</var> with the value <var data-name="value">value</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L602-L608">Otherwise:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L603-L604">If <var data-name="value">value</var> cannot be coerced according to the input coercion rules of <var data-name="argumentType">argumentType</var>, raise a field error.</li> <li data-source="spec/Section%206%20--%20Execution.md#L605-L606">Let <var data-name="coercedValue">coercedValue</var> be the result of coercing <var data-name="value">value</var> according to the input coercion rules of <var data-name="argumentType">argumentType</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L607-L608">Add an entry to <var data-name="coercedValues">coercedValues</var> named <var data-name="argumentName">argumentName</var> with the value <var data-name="coercedValue">coercedValue</var>.</li> </ol> </li> </ol> </li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L609">Return <var data-name="coercedValues">coercedValues</var>.</li> </ol> </div> <div id="note-65769" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L611-L613"> <a href="#note-65769">Note</a> Variable values are not coerced because they are expected to be coerced before executing the operation in <a href="#CoerceVariableValues()" data-name="CoerceVariableValues">CoerceVariableValues</a>(), and valid operations must only allow usage of variables of appropriate types.</div> </section> <section id="sec-Value-Resolution" secid="6.4.2"> <h3 data-source="spec/Section%206%20--%20Execution.md#L616"><a href="#sec-Value-Resolution">6.4.2</a>Value Resolution</h3> While nearly all of GraphQL execution can be described generically, ultimately the internal system exposing the GraphQL interface must provide values. This is exposed via ResolveFieldValue, which produces a value for a given field on a type for a real value. As an example, this might accept the <var data-name="objectType">objectType</var> <code>Person</code>, the <var data-name="field">field</var> "soulMate", and the <var data-name="objectValue">objectValue</var> representing John Lennon. It would be expected to yield the value representing Yoko Ono. <div class="spec-algo" id="ResolveFieldValue()" data-source="spec/Section%206%20--%20Execution.md#L627-L630"> <a href="#ResolveFieldValue()" data-name="ResolveFieldValue">ResolveFieldValue</a>(<var data-name="objectType">objectType</var>, <var data-name="objectValue">objectValue</var>, <var data-name="fieldName">fieldName</var>, <var data-name="argumentValues">argumentValues</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L628-L629">Let <var data-name="resolver">resolver</var> be the internal function provided by <var data-name="objectType">objectType</var> for determining the resolved value of a field named <var data-name="fieldName">fieldName</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L630">Return the result of calling <var data-name="resolver">resolver</var>, providing <var data-name="objectValue">objectValue</var> and <var data-name="argumentValues">argumentValues</var>.</li> </ol> </div> <div id="note-7bf5f" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L632-L635"> <a href="#note-7bf5f">Note</a> It is common for <var data-name="resolver">resolver</var> to be asynchronous due to relying on reading an underlying database or networked service to produce a value. This necessitates the rest of a GraphQL executor to handle an asynchronous execution flow.</div> </section> <section id="sec-Value-Completion" secid="6.4.3"> <h3 data-source="spec/Section%206%20--%20Execution.md#L638"><a href="#sec-Value-Completion">6.4.3</a>Value Completion</h3> After resolving the value for a field, it is completed by ensuring it adheres to the expected return type. If the return type is another Object type, then the field execution process continues recursively. <div class="spec-algo" id="CompleteValue()" data-source="spec/Section%206%20--%20Execution.md#L644-L667"> <a href="#CompleteValue()" data-name="CompleteValue">CompleteValue</a>(<var data-name="fieldType">fieldType</var>, <var data-name="fields">fields</var>, <var data-name="result">result</var>, <var data-name="variableValues">variableValues</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L645-L650">If the <var data-name="fieldType">fieldType</var> is a Non-Null type:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L646">Let <var data-name="innerType">innerType</var> be the inner type of <var data-name="fieldType">fieldType</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L647-L648">Let <var data-name="completedResult">completedResult</var> be the result of calling <a href="#CompleteValue()" data-name="CompleteValue">CompleteValue</a>(<var data-name="innerType">innerType</var>, <var data-name="fields">fields</var>, <var data-name="result">result</var>, <var data-name="variableValues">variableValues</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L649">If <var data-name="completedResult">completedResult</var> is null, raise a field error.</li> <li data-source="spec/Section%206%20--%20Execution.md#L650">Return <var data-name="completedResult">completedResult</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L651-L652">If <var data-name="result">result</var> is null (or another internal value similar to null such as undefined), return null.</li> <li data-source="spec/Section%206%20--%20Execution.md#L653-L658">If <var data-name="fieldType">fieldType</var> is a List type:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L654">If <var data-name="result">result</var> is not a collection of values, raise a field error.</li> <li data-source="spec/Section%206%20--%20Execution.md#L655">Let <var data-name="innerType">innerType</var> be the inner type of <var data-name="fieldType">fieldType</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L656-L658">Return a list where each list item is the result of calling <a href="#CompleteValue()" data-name="CompleteValue">CompleteValue</a>(<var data-name="innerType">innerType</var>, <var data-name="fields">fields</var>, <var data-name="resultItem">resultItem</var>, <var data-name="variableValues">variableValues</var>), where <var data-name="resultItem">resultItem</var> is each item in <var data-name="result">result</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L659-L660">If <var data-name="fieldType">fieldType</var> is a Scalar or Enum type:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L660">Return the result of <a href="#CoerceResult()" data-name="CoerceResult">CoerceResult</a>(<var data-name="fieldType">fieldType</var>, <var data-name="result">result</var>).</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L661-L667">If <var data-name="fieldType">fieldType</var> is an Object, Interface, or Union type:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L662-L663">If <var data-name="fieldType">fieldType</var> is an Object type.<ol> <li data-source="spec/Section%206%20--%20Execution.md#L663">Let <var data-name="objectType">objectType</var> be <var data-name="fieldType">fieldType</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L664-L665">Otherwise if <var data-name="fieldType">fieldType</var> is an Interface or Union type.<ol> <li data-source="spec/Section%206%20--%20Execution.md#L665">Let <var data-name="objectType">objectType</var> be <a href="#ResolveAbstractType()" data-name="ResolveAbstractType">ResolveAbstractType</a>(<var data-name="fieldType">fieldType</var>, <var data-name="result">result</var>).</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L666">Let <var data-name="subSelectionSet">subSelectionSet</var> be the result of calling <a href="#MergeSelectionSets()" data-name="MergeSelectionSets">MergeSelectionSets</a>(<var data-name="fields">fields</var>).</li> <li data-source="spec/Section%206%20--%20Execution.md#L667">Return the result of evaluating <a href="#ExecuteSelectionSet()" data-name="ExecuteSelectionSet">ExecuteSelectionSet</a>(<var data-name="subSelectionSet">subSelectionSet</var>, <var data-name="objectType">objectType</var>, <var data-name="result">result</var>, <var data-name="variableValues">variableValues</var>) normally (allowing for parallelization).</li> </ol> </li> </ol> </div> <section id="sec-Value-Completion.Coercing-Results" class="subsec"> <h6 data-source="spec/Section%206%20--%20Execution.md#L669"><a href="#sec-Value-Completion.Coercing-Results" title="link to this subsection">Coercing Results</a></h6> The primary purpose of value completion is to ensure that the values returned by field resolvers are valid according to the GraphQL type system and a service’s schema. This “dynamic type checking” allows GraphQL to provide consistent guarantees about returned types atop any service’s internal runtime. See the Scalars <a href="#sec-Scalars.Result-Coercion-and-Serialization">Result Coercion and Serialization</a> sub-section for more detailed information about how GraphQL’s built-in scalars coerce result values. <div class="spec-algo" id="CoerceResult()" data-source="spec/Section%206%20--%20Execution.md#L680-L685"> <a href="#CoerceResult()" data-name="CoerceResult">CoerceResult</a>(<var data-name="leafType">leafType</var>, <var data-name="value">value</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L681">Assert <var data-name="value">value</var> is not null.</li> <li data-source="spec/Section%206%20--%20Execution.md#L682-L685">Return the result of calling the internal method provided by the type system for determining the “result coercion” of <var data-name="leafType">leafType</var> given the value <var data-name="value">value</var>. This internal method must return a valid value for the type and not null. Otherwise throw a field error.</li> </ol> </div> <div id="note-5bde4" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L687-L689"> <a href="#note-5bde4">Note</a> If a field resolver returns null then it is handled within <a href="#CompleteValue()" data-name="CompleteValue">CompleteValue</a>() before <a href="#CoerceResult()" data-name="CoerceResult">CoerceResult</a>() is called. Therefore both the input and output of <a href="#CoerceResult()" data-name="CoerceResult">CoerceResult</a>() must not be null.</div> </section> <section id="sec-Value-Completion.Resolving-Abstract-Types" class="subsec"> <h6 data-source="spec/Section%206%20--%20Execution.md#L691"><a href="#sec-Value-Completion.Resolving-Abstract-Types" title="link to this subsection">Resolving Abstract Types</a></h6> When completing a field with an abstract return type, that is an Interface or Union return type, first the abstract type must be resolved to a relevant Object type. This determination is made by the internal system using whatever means appropriate. <div id="note-5ee58" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L698-L700"> <a href="#note-5ee58">Note</a> A common method of determining the Object type for an <var data-name="objectValue">objectValue</var> in object-oriented environments, such as Java or C#, is to use the class name of the <var data-name="objectValue">objectValue</var>.</div> <div class="spec-algo" id="ResolveAbstractType()" data-source="spec/Section%206%20--%20Execution.md#L702-L705"> <a href="#ResolveAbstractType()" data-name="ResolveAbstractType">ResolveAbstractType</a>(<var data-name="abstractType">abstractType</var>, <var data-name="objectValue">objectValue</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L703-L705">Return the result of calling the internal method provided by the type system for determining the Object type of <var data-name="abstractType">abstractType</var> given the value <var data-name="objectValue">objectValue</var>.</li> </ol> </div> </section> <section id="sec-Value-Completion.Merging-Selection-Sets" class="subsec"> <h6 data-source="spec/Section%206%20--%20Execution.md#L707"><a href="#sec-Value-Completion.Merging-Selection-Sets" title="link to this subsection">Merging Selection Sets</a></h6> When more than one field of the same name is executed in parallel, their selection sets are merged together when completing the value in order to continue execution of the sub-selection sets. An example operation illustrating parallel fields with the same name with sub-selections. <pre id="example-77852" class="spec-example" data-language="graphql" data-source="spec/Section%206%20--%20Execution.md#L716-L725"><a href="#example-77852">Example № 195</a><code>{ me { firstName } me { lastName } } </code></pre> After resolving the value for <code>me</code>, the selection sets are merged together so <code>firstName</code> and <code>lastName</code> can be resolved for one value. <div class="spec-algo" id="MergeSelectionSets()" data-source="spec/Section%206%20--%20Execution.md#L730-L736"> <a href="#MergeSelectionSets()" data-name="MergeSelectionSets">MergeSelectionSets</a>(<var data-name="fields">fields</var>)<ol> <li data-source="spec/Section%206%20--%20Execution.md#L731">Let <var data-name="selectionSet">selectionSet</var> be an empty list.</li> <li data-source="spec/Section%206%20--%20Execution.md#L732-L735">For each <var data-name="field">field</var> in <var data-name="fields">fields</var>:<ol> <li data-source="spec/Section%206%20--%20Execution.md#L733">Let <var data-name="fieldSelectionSet">fieldSelectionSet</var> be the selection set of <var data-name="field">field</var>.</li> <li data-source="spec/Section%206%20--%20Execution.md#L734">If <var data-name="fieldSelectionSet">fieldSelectionSet</var> is null or empty, continue to the next field.</li> <li data-source="spec/Section%206%20--%20Execution.md#L735">Append all selections in <var data-name="fieldSelectionSet">fieldSelectionSet</var> to <var data-name="selectionSet">selectionSet</var>.</li> </ol> </li> <li data-source="spec/Section%206%20--%20Execution.md#L736">Return <var data-name="selectionSet">selectionSet</var>.</li> </ol> </div> </section> </section> <section id="sec-Handling-Field-Errors" secid="6.4.4"> <h3 data-source="spec/Section%206%20--%20Execution.md#L739"><a href="#sec-Handling-Field-Errors">6.4.4</a>Handling Field Errors</h3> <a href="#sec-Errors.Field-errors">“Field errors”</a> are raised from a particular field during value resolution or coercion. While these errors should be reported in the response, they are “handled” by producing a partial response. <div id="note-c78be" class="spec-note" data-source="spec/Section%206%20--%20Execution.md#L745-L747"> <a href="#note-c78be">Note</a> This is distinct from <a href="#sec-Errors.Request-errors">“request errors”</a> which are raised before execution begins. If a request error is encountered, execution does not begin and no data is returned in the response.</div> If a field error is raised while resolving a field, it is handled as though the field returned null, and the error must be added to the "errors" list in the response. If the result of resolving a field is null (either because the function to resolve the field returned null or because a field error was raised), and that field is of a <code>Non-Null</code> type, then a field error is raised. The error must be added to the "errors" list in the response. If the field returns null because of a field error which has already been added to the "errors" list in the response, the "errors" list must not be further affected. That is, only one error should be added to the errors list per field. Since <code>Non-Null</code> type fields cannot be null, field errors are propagated to be handled by the parent field. If the parent field may be null then it resolves to null, otherwise if it is a <code>Non-Null</code> type, the field error is further propagated to its parent field. If a <code>List</code> type wraps a <code>Non-Null</code> type, and one of the elements of that list resolves to null, then the entire list must resolve to null. If the <code>List</code> type is also wrapped in a <code>Non-Null</code>, the field error continues to propagate upwards. If all fields from the root of the request to the source of the field error return <code>Non-Null</code> types, then the "data" entry in the response should be null. </section> </section> </section> <section id="sec-Response" secid="7"> <h1 data-source="spec/Section%207%20--%20Response.md#L1"><a href="#sec-Response">7</a>Response</h1> When a GraphQL service receives a request, it must return a well-formed response. The service’s response describes the result of executing the requested operation if successful, and describes any errors raised during the request. A response may contain both a partial response as well as any field errors in the case that a field error was raised on a field and was replaced with null. <section id="sec-Response-Format" secid="7.1"> <h2 data-source="spec/Section%207%20--%20Response.md#L10"><a href="#sec-Response-Format">7.1</a>Response Format</h2> A response to a GraphQL request must be a map. If the request raised any errors, the response map must contain an entry with key <code>errors</code>. The value of this entry is described in the “Errors” section. If the request completed without raising any errors, this entry must not be present. If the request included execution, the response map must contain an entry with key <code>data</code>. The value of this entry is described in the “Data” section. If the request failed before execution, due to a syntax error, missing information, or validation error, this entry must not be present. The response map may also contain an entry with key <code>extensions</code>. This entry, if set, must have a map as its value. This entry is reserved for implementors to extend the protocol however they see fit, and hence there are no additional restrictions on its contents. To ensure future changes to the protocol do not break existing services and clients, the top level response map must not contain any entries other than the three described above. <div id="note-6f005" class="spec-note" data-source="spec/Section%207%20--%20Response.md#L33-L35"> <a href="#note-6f005">Note</a> When <code>errors</code> is present in the response, it may be helpful for it to appear first when serialized to make it more clear when errors are present in a response during debugging.</div> <section id="sec-Data" secid="7.1.1"> <h3 data-source="spec/Section%207%20--%20Response.md#L37"><a href="#sec-Data">7.1.1</a>Data</h3> The <code>data</code> entry in the response will be the result of the execution of the requested operation. If the operation was a query, this output will be an object of the query root operation type; if the operation was a mutation, this output will be an object of the mutation root operation type. If an error was raised before execution begins, the <code>data</code> entry should not be present in the result. If an error was raised during the execution that prevented a valid response, the <code>data</code> entry in the response should be <code>null</code>. </section> <section id="sec-Errors" secid="7.1.2"> <h3 data-source="spec/Section%207%20--%20Response.md#L51"><a href="#sec-Errors">7.1.2</a>Errors</h3> The <code>errors</code> entry in the response is a non-empty list of errors, where each error is a map. If no errors were raised during the request, the <code>errors</code> entry should not be present in the result. If the <code>data</code> entry in the response is not present, the <code>errors</code> entry in the response must not be empty. It must contain at least one error. The errors it contains should indicate why no data was able to be returned. If the <code>data</code> entry in the response is present (including if it is the value null), the <code>errors</code> entry in the response may contain any field errors that were raised during execution. If field errors were raised during execution, it should contain those errors. <section id="sec-Errors.Request-errors" class="subsec"> <h6 data-source="spec/Section%207%20--%20Response.md#L68"><a href="#sec-Errors.Request-errors" title="link to this subsection">Request errors</a></h6> Request errors are raised before execution begins. This may occur due to a parse grammar or validation error in the requested document, an inability to determine which operation to execute, or invalid input values for variables. Request errors are typically the fault of the requesting client. If a request error is raised, execution does not begin and the <code>data</code> entry in the response must not be present. The <code>errors</code> entry must include the error. </section> <section id="sec-Errors.Field-errors" class="subsec"> <h6 data-source="spec/Section%207%20--%20Response.md#L79"><a href="#sec-Errors.Field-errors" title="link to this subsection">Field errors</a></h6> Field errors are raised during execution from a particular field. This may occur due to an internal error during value resolution or failure to coerce the resulting value. Field errors are typically the fault of GraphQL service. If a field error is raised, execution attempts to continue and a partial result is produced (see <a href="#sec-Handling-Field-Errors">Handling Field Errors</a>). The <code>data</code> entry in the response must be present. The <code>errors</code> entry should include all raised field errors. </section> <section id="sec-Errors.Error-result-format" class="subsec"> <h6 data-source="spec/Section%207%20--%20Response.md#L92"><a href="#sec-Errors.Error-result-format" title="link to this subsection">Error result format</a></h6> Every error must contain an entry with the key <code>message</code> with a string description of the error intended for the developer as a guide to understand and correct the error. If an error can be associated to a particular point in the requested GraphQL document, it should contain an entry with the key <code>locations</code> with a list of locations, where each location is a map with the keys <code>line</code> and <code>column</code>, both positive numbers starting from <code>1</code> which describe the beginning of an associated syntax element. If an error can be associated to a particular field in the GraphQL result, it must contain an entry with the key <code>path</code> that details the path of the response field which experienced the error. This allows clients to identify whether a <code>null</code> result is intentional or caused by a runtime error. This field should be a list of path segments starting at the root of the response and ending with the field associated with the error. Path segments that represent fields should be strings, and path segments that represent list indices should be 0-indexed integers. If the error happens in an aliased field, the path to the error should use the aliased name, since it represents a path in the response, not in the request. For example, if fetching one of the friends’ names fails in the following operation: <pre id="example-bc485" class="spec-example" data-language="graphql" data-source="spec/Section%207%20--%20Response.md#L119-L129"><a href="#example-bc485">Example № 196</a><code>{ hero(episode: $episode) { name heroFriends: friends { id name } } } </code></pre> The response might look like: <pre id="example-072c4" class="spec-example" data-language="json" data-source="spec/Section%207%20--%20Response.md#L133-L162"><a href="#example-072c4">Example № 197</a><code>{ "errors": [ { "message": "Name for character with ID 1002 could not be fetched.", "locations": [{ "line": 6, "column": 7 }], "path": ["hero", "heroFriends", 1, "name"] } ], "data": { "hero": { "name": "R2-D2", "heroFriends": [ { "id": "1000", "name": "Luke Skywalker" }, { "id": "1002", "name": null }, { "id": "1003", "name": "Leia Organa" } ] } } } </code></pre> If the field which experienced an error was declared as <code>Non-Null</code>, the <code>null</code> result will bubble up to the next nullable field. In that case, the <code>path</code> for the error should include the full path to the result field where the error was raised, even if that field is not present in the response. For example, if the <code>name</code> field from above had declared a <code>Non-Null</code> return type in the schema, the result would look different but the error reported would be the same: <pre id="example-c18ef" class="spec-example" data-language="json" data-source="spec/Section%207%20--%20Response.md#L173-L199"><a href="#example-c18ef">Example № 198</a><code>{ "errors": [ { "message": "Name for character with ID 1002 could not be fetched.", "locations": [{ "line": 6, "column": 7 }], "path": ["hero", "heroFriends", 1, "name"] } ], "data": { "hero": { "name": "R2-D2", "heroFriends": [ { "id": "1000", "name": "Luke Skywalker" }, null, { "id": "1003", "name": "Leia Organa" } ] } } } </code></pre> GraphQL services may provide an additional entry to errors with key <code>extensions</code>. This entry, if set, must have a map as its value. This entry is reserved for implementors to add additional information to errors however they see fit, and there are no additional restrictions on its contents. <pre id="example-8b658" class="spec-example" data-language="json" data-source="spec/Section%207%20--%20Response.md#L206-L220"><a href="#example-8b658">Example № 199</a><code>{ "errors": [ { "message": "Name for character with ID 1002 could not be fetched.", "locations": [{ "line": 6, "column": 7 }], "path": ["hero", "heroFriends", 1, "name"], "extensions": { "code": "CAN_NOT_FETCH_BY_ID", "timestamp": "Fri Feb 9 14:33:09 UTC 2018" } } ] } </code></pre> GraphQL services should not provide any additional entries to the error format since they could conflict with additional entries that may be added in future versions of this specification. <div id="note-5c13b" class="spec-note" data-source="spec/Section%207%20--%20Response.md#L226-L228"> <a href="#note-5c13b">Note</a> Previous versions of this spec did not describe the <code>extensions</code> entry for error formatting. While non-specified entries are not violations, they are still discouraged.</div> <pre id="example-78af4" class="spec-counter-example" data-language="json" data-source="spec/Section%207%20--%20Response.md#L230-L242"><a href="#example-78af4">Counter Example № 200</a><code>{ "errors": [ { "message": "Name for character with ID 1002 could not be fetched.", "locations": [{ "line": 6, "column": 7 }], "path": ["hero", "heroFriends", 1, "name"], "code": "CAN_NOT_FETCH_BY_ID", "timestamp": "Fri Feb 9 14:33:09 UTC 2018" } ] } </code></pre> </section> </section> </section> <section id="sec-Serialization-Format" secid="7.2"> <h2 data-source="spec/Section%207%20--%20Response.md#L245"><a href="#sec-Serialization-Format">7.2</a>Serialization Format</h2> GraphQL does not require a specific serialization format. However, clients should use a serialization format that supports the major primitives in the GraphQL response. In particular, the serialization format must at least support representations of the following four primitives: <ul> <li data-source="spec/Section%207%20--%20Response.md#L252">Map</li> <li data-source="spec/Section%207%20--%20Response.md#L253">List</li> <li data-source="spec/Section%207%20--%20Response.md#L254">String</li> <li data-source="spec/Section%207%20--%20Response.md#L255">Null</li> </ul> A serialization format should also support the following primitives, each representing one of the common GraphQL scalar types, however a string or simpler primitive may be used as a substitute if any are not directly supported: <ul> <li data-source="spec/Section%207%20--%20Response.md#L261">Boolean</li> <li data-source="spec/Section%207%20--%20Response.md#L262">Int</li> <li data-source="spec/Section%207%20--%20Response.md#L263">Float</li> <li data-source="spec/Section%207%20--%20Response.md#L264">Enum Value</li> </ul> This is not meant to be an exhaustive list of what a serialization format may encode. For example custom scalars representing a Date, Time, URI, or number with a different precision may be represented in whichever relevant format a given serialization format may support. <section id="sec-JSON-Serialization" secid="7.2.1"> <h3 data-source="spec/Section%207%20--%20Response.md#L272"><a href="#sec-JSON-Serialization">7.2.1</a>JSON Serialization</h3> JSON is the most common serialization format for GraphQL. Though as mentioned above, GraphQL does not require a specific serialization format. When using JSON as a serialization of GraphQL responses, the following JSON values should be used to encode the related GraphQL values: <table> <thead> <tr data-source="spec/Section%207%20--%20Response.md#L280"> <th>GraphQL Value</th> <th>JSON Value</th> </tr> </thead> <tbody> <tr data-source="spec/Section%207%20--%20Response.md#L282"> <td>Map</td> <td>Object</td> </tr> <tr data-source="spec/Section%207%20--%20Response.md#L283"> <td>List</td> <td>Array</td> </tr> <tr data-source="spec/Section%207%20--%20Response.md#L284"> <td>Null</td> <td>null</td> </tr> <tr data-source="spec/Section%207%20--%20Response.md#L285"> <td>String</td> <td>String</td> </tr> <tr data-source="spec/Section%207%20--%20Response.md#L286"> <td>Boolean</td> <td>true or false</td> </tr> <tr data-source="spec/Section%207%20--%20Response.md#L287"> <td>Int</td> <td>Number</td> </tr> <tr data-source="spec/Section%207%20--%20Response.md#L288"> <td>Float</td> <td>Number</td> </tr> <tr data-source="spec/Section%207%20--%20Response.md#L289"> <td>Enum Value</td> <td>String</td> </tr> </tbody> </table> <div id="note-786e2" class="spec-note" data-source="spec/Section%207%20--%20Response.md#L291-L292"> <a href="#note-786e2">Note</a> For consistency and ease of notation, examples of responses are given in JSON format throughout this document.</div> </section> <section id="sec-Serialized-Map-Ordering" secid="7.2.2"> <h3 data-source="spec/Section%207%20--%20Response.md#L295"><a href="#sec-Serialized-Map-Ordering">7.2.2</a>Serialized Map Ordering</h3> Since the result of evaluating a selection set is ordered, the serialized Map of results should preserve this order by writing the map entries in the same order as those fields were requested as defined by selection set execution. Producing a serialized response where fields are represented in the same order in which they appear in the request improves human readability during debugging and enables more efficient parsing of responses if the order of properties can be anticipated. Serialization formats which represent an ordered map should preserve the order of requested fields as defined by <a href="#CollectFields()" data-name="CollectFields">CollectFields</a>() in the Execution section. Serialization formats which only represent unordered maps but where order is still implicit in the serialization’s textual order (such as JSON) should preserve the order of requested fields textually. For example, if the request was <code>{ name, age }</code>, a GraphQL service responding in JSON should respond with <code>{ "name": "Mark", "age": 30 }</code> and should not respond with <code>{ "age": 30, "name": "Mark" }</code>. While JSON Objects are specified as an <a href="https://tools.ietf.org/html/rfc7159#section-4">unordered collection of key-value pairs</a> the pairs are represented in an ordered manner. In other words, while the JSON strings <code>{ "name": "Mark", "age": 30 }</code> and <code>{ "age": 30, "name": "Mark" }</code> encode the same value, they also have observably different property orderings. <div id="note-4bb20" class="spec-note" data-source="spec/Section%207%20--%20Response.md#L321-L323"> <a href="#note-4bb20">Note</a> This does not violate the JSON spec, as clients may still interpret objects in the response as unordered Maps and arrive at a valid value. </div> </section> </section> </section> <section id="sec-Appendix-Notation-Conventions" secid="A"> <h1 data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L1"><a href="#sec-Appendix-Notation-Conventions">A</a>Appendix: Notation Conventions</h1> This specification document contains a number of notation conventions used to describe technical concepts such as language grammar and semantics as well as runtime algorithms. This appendix seeks to explain these notations in greater detail to avoid ambiguity. <section id="sec-Context-Free-Grammar" secid="A.1"> <h2 data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L11"><a href="#sec-Context-Free-Grammar">A.1</a>Context-Free Grammar</h2> A context-free grammar consists of a number of productions. Each production has an abstract symbol called a “non-terminal” as its left-hand side, and zero or more possible sequences of non-terminal symbols and or terminal characters as its right-hand side. Starting from a single goal non-terminal symbol, a context-free grammar describes a language: the set of possible sequences of characters that can be described by repeatedly replacing any non-terminal in the goal sequence with one of the sequences it is defined by, until all non-terminal symbols have been replaced by terminal characters. Terminals are represented in this document in a monospace font in two forms: a specific Unicode character or sequence of Unicode characters (ie. = or terminal), and prose typically describing a specific Unicode code-point "Space (U+0020)". Sequences of Unicode characters only appear in syntactic grammars and represent a <a href="#Name" data-name="Name">Name</a> token of that specific sequence. Non-terminal production rules are represented in this document using the following notation for a non-terminal with a single definition: <div class="spec-production" id="NonTerminalWithSingleDefinition" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L33"> <a href="#NonTerminalWithSingleDefinition" data-name="NonTerminalWithSingleDefinition">NonTerminalWithSingleDefinition</a><div class="spec-rhs">NonTerminalterminal</div> </div> While using the following notation for a production with a list of definitions: <div class="spec-production" id="NonTerminalWithManyDefinitions" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L37-L39"> <a href="#NonTerminalWithManyDefinitions" data-name="NonTerminalWithManyDefinitions">NonTerminalWithManyDefinitions</a><div class="spec-rhs">OtherNonTerminalterminal</div> <div class="spec-rhs">terminal</div> </div> A definition may refer to itself, which describes repetitive sequences, for example: <div class="spec-production" id="ListOfLetterA" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L44-L46"> <a href="#ListOfLetterA" data-name="ListOfLetterA">ListOfLetterA</a><div class="spec-rhs"><a href="#ListOfLetterA" data-name="ListOfLetterA">ListOfLetterA</a>a</div> <div class="spec-rhs">a</div> </div> </section> <section id="sec-Lexical-and-Syntactical-Grammar" secid="A.2"> <h2 data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L49"><a href="#sec-Lexical-and-Syntactical-Grammar">A.2</a>Lexical and Syntactical Grammar</h2> The GraphQL language is defined in a syntactic grammar where terminal symbols are tokens. Tokens are defined in a lexical grammar which matches patterns of source characters. The result of parsing a source text sequence of Unicode characters first produces a sequence of lexical tokens according to the lexical grammar which then produces abstract syntax tree (AST) according to the syntactical grammar. A lexical grammar production describes non-terminal “tokens” by patterns of terminal Unicode characters. No “whitespace” or other ignored characters may appear between any terminal Unicode characters in the lexical grammar production. A lexical grammar production is distinguished by a two colon <code>::</code> definition. <div class="spec-production d2" id="Word" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L64"> <a href="#Word" data-name="Word">Word</a><div class="spec-rhs"><a href="#Letter" data-name="Letter">Letter</a>list</div> </div> A Syntactical grammar production describes non-terminal “rules” by patterns of terminal Tokens. <a href="#WhiteSpace" data-name="WhiteSpace">WhiteSpace</a> and other <a href="#Ignored" data-name="Ignored">Ignored</a> sequences may appear before or after any terminal <a href="#Token" data-name="Token">Token</a>. A syntactical grammar production is distinguished by a one colon <code>:</code> definition. <div class="spec-production" id="Sentence" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L71"> <a href="#Sentence" data-name="Sentence">Sentence</a><div class="spec-rhs"><a href="#Word" data-name="Word">Word</a>list.</div> </div> </section> <section id="sec-Grammar-Notation" secid="A.3"> <h2 data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L74"><a href="#sec-Grammar-Notation">A.3</a>Grammar Notation</h2> This specification uses some additional notation to describe common patterns, such as optional or repeated patterns, or parameterized alterations of the definition of a non-terminal. This section explains these short-hand notations and their expanded definitions in the context-free grammar. <section id="sec-Grammar-Notation.Constraints" class="subsec"> <h6 data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L82"><a href="#sec-Grammar-Notation.Constraints" title="link to this subsection">Constraints</a></h6> A grammar production may specify that certain expansions are not permitted by using the phrase “but not” and then indicating the expansions to be excluded. For example, the following production means that the non-terminal <a href="#SafeWord" data-name="SafeWord">SafeWord</a> may be replaced by any sequence of characters that could replace <a href="#Word" data-name="Word">Word</a> provided that the same sequence of characters could not replace SevenCarlinWords. <div class="spec-production" id="SafeWord" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L91"> <a href="#SafeWord" data-name="SafeWord">SafeWord</a><div class="spec-rhs"><a href="#Word" data-name="Word">Word</a>SevenCarlinWords</div> </div> A grammar may also list a number of restrictions after “but not” separated by “or”. For example: <div class="spec-production" id="NonBooleanName" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L98"> <a href="#NonBooleanName" data-name="NonBooleanName">NonBooleanName</a><div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>truefalse</div> </div> </section> <section id="sec-Grammar-Notation.Lookahead-Restrictions" class="subsec"> <h6 data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L101"><a href="#sec-Grammar-Notation.Lookahead-Restrictions" title="link to this subsection">Lookahead Restrictions</a></h6> A grammar production may specify that certain characters or tokens are not permitted to follow it by using the pattern NotAllowed. Lookahead restrictions are often used to remove ambiguity from the grammar. The following example makes it clear that <a href="#Letter" data-name="Letter">Letter</a>list must be greedy, since <a href="#Word" data-name="Word">Word</a> cannot be followed by yet another <a href="#Letter" data-name="Letter">Letter</a>. <div class="spec-production d2" id="Word" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L110"> <a href="#Word" data-name="Word">Word</a><div class="spec-rhs"><a href="#Letter" data-name="Letter">Letter</a>list<a href="#Letter" data-name="Letter">Letter</a></div> </div> </section> <section id="sec-Grammar-Notation.Optionality-and-Lists" class="subsec"> <h6 data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L113"><a href="#sec-Grammar-Notation.Optionality-and-Lists" title="link to this subsection">Optionality and Lists</a></h6> A subscript suffix “Symbolopt” is shorthand for two possible sequences, one including that symbol and one excluding it. As an example: <div class="spec-production" id="Sentence" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L120"> <a href="#Sentence" data-name="Sentence">Sentence</a><div class="spec-rhs">NounVerbAdverbopt</div> </div> is shorthand for <div class="spec-production" id="Sentence" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L124-L126"> <a href="#Sentence" data-name="Sentence">Sentence</a><div class="spec-rhs">NounVerbAdverb</div> <div class="spec-rhs">NounVerb</div> </div> A subscript suffix “Symbollist” is shorthand for a list of one or more of that symbol, represented as an additional recursive production. As an example: <div class="spec-production" id="Book" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L133"> <a href="#Book" data-name="Book">Book</a><div class="spec-rhs">CoverPagelistCover</div> </div> is shorthand for <div class="spec-production" id="Book" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L137"> <a href="#Book" data-name="Book">Book</a><div class="spec-rhs">Cover<a href="#Page_list" data-name="Page_list">Page_list</a>Cover</div> </div> <div class="spec-production" id="Page_list" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L139-L141"> <a href="#Page_list" data-name="Page_list">Page_list</a><div class="spec-rhs"><a href="#Page_list" data-name="Page_list">Page_list</a>Page</div> <div class="spec-rhs">Page</div> </div> </section> <section id="sec-Grammar-Notation.Parameterized-Grammar-Productions" class="subsec"> <h6 data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L144"><a href="#sec-Grammar-Notation.Parameterized-Grammar-Productions" title="link to this subsection">Parameterized Grammar Productions</a></h6> A symbol definition subscript suffix parameter in braces “SymbolParam” is shorthand for two symbol definitions, one appended with that parameter name, the other without. The same subscript suffix on a symbol is shorthand for that variant of the definition. If the parameter starts with “?”, that form of the symbol is used if in a symbol definition with the same parameter. Some possible sequences can be included or excluded conditionally when respectively prefixed with “[+Param]” and “[~Param]”. As an example: <div class="spec-production" id="Example" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L156-L161"> <a href="#Example" data-name="Example">Example</a>Param<div class="spec-rhs">A</div> <div class="spec-rhs">BParam</div> <div class="spec-rhs">CParam</div> <div class="spec-rhs">ParamD</div> <div class="spec-rhs">ParamE</div> </div> is shorthand for <div class="spec-production" id="Example" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L165-L169"> <a href="#Example" data-name="Example">Example</a><div class="spec-rhs">A</div> <div class="spec-rhs">B_param</div> <div class="spec-rhs">C</div> <div class="spec-rhs">E</div> </div> <div class="spec-production" id="Example_param" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L171-L175"> <a href="#Example_param" data-name="Example_param">Example_param</a><div class="spec-rhs">A</div> <div class="spec-rhs">B_param</div> <div class="spec-rhs">C_param</div> <div class="spec-rhs">D</div> </div> </section> </section> <section id="sec-Grammar-Semantics" secid="A.4"> <h2 data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L178"><a href="#sec-Grammar-Semantics">A.4</a>Grammar Semantics</h2> This specification describes the semantic value of many grammar productions in the form of a list of algorithmic steps. For example, this describes how a parser should interpret a string literal: <div class="spec-semantic d2" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L185-L187"> <a href="#StringValue" data-name="StringValue">StringValue</a><div class="spec-rhs">""</div> <ol> <li data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L187">Return an empty Unicode character sequence.</li> </ol> </div> <div class="spec-semantic d2" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L189-L192"> <a href="#StringValue" data-name="StringValue">StringValue</a><div class="spec-rhs">"<a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a>list"</div> <ol> <li data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L191-L192">Return the Unicode character sequence of all <a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a> Unicode character values.</li> </ol> </div> </section> <section id="sec-Algorithms" secid="A.5"> <h2 data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L195"><a href="#sec-Algorithms">A.5</a>Algorithms</h2> This specification describes some algorithms used by the static and runtime semantics, they’re defined in the form of a function-like syntax with the algorithm’s name and the arguments it accepts along with a list of algorithmic steps to take in the order listed. Each step may establish references to other values, check various conditions, call other algorithms, and eventually return a value representing the outcome of the algorithm for the provided arguments. For example, the following example describes an algorithm named Fibonacci which accepts a single argument <var data-name="number">number</var>. The algorithm’s steps produce the next number in the Fibonacci sequence: <div class="spec-algo" id="Fibonacci()" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L208-L215"> <a href="#Fibonacci()" data-name="Fibonacci">Fibonacci</a>(<var data-name="number">number</var>)<ol> <li data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L209-L210">If <var data-name="number">number</var> is 0:<ol> <li data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L210">Return 1.</li> </ol> </li> <li data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L211-L212">If <var data-name="number">number</var> is 1:<ol> <li data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L212">Return 2.</li> </ol> </li> <li data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L213">Let <var data-name="previousNumber">previousNumber</var> be <var data-name="number">number</var> - 1.</li> <li data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L214">Let <var data-name="previousPreviousNumber">previousPreviousNumber</var> be <var data-name="number">number</var> - 2.</li> <li data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L215">Return <a href="#Fibonacci()" data-name="Fibonacci">Fibonacci</a>(<var data-name="previousNumber">previousNumber</var>) + <a href="#Fibonacci()" data-name="Fibonacci">Fibonacci</a>(<var data-name="previousPreviousNumber">previousPreviousNumber</var>).</li> </ol> </div> <div id="note-edb29" class="spec-note" data-source="spec/Appendix%20A%20--%20Notation%20Conventions.md#L217-L219"> <a href="#note-edb29">Note</a> Algorithms described in this document are written to be easy to understand. Implementers are encouraged to include equivalent but optimized implementations. </div> </section> </section> <section id="sec-Appendix-Grammar-Summary" secid="B"> <h1 data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L1"><a href="#sec-Appendix-Grammar-Summary">B</a>Appendix: Grammar Summary</h1> <section id="sec-Appendix-Grammar-Summary.Source-Text" secid="B.1"> <h2 data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L3"><a href="#sec-Appendix-Grammar-Summary.Source-Text">B.1</a>Source Text</h2> <div class="spec-production d2" id="SourceCharacter" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L5-L9"> <a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a><div class="spec-rhs">U+0009</div> <div class="spec-rhs">U+000A</div> <div class="spec-rhs">U+000D</div> <div class="spec-rhs">U+0020–U+FFFF</div> </div> </section> <section id="sec-Appendix-Grammar-Summary.Ignored-Tokens" secid="B.2"> <h2 data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L12"><a href="#sec-Appendix-Grammar-Summary.Ignored-Tokens">B.2</a>Ignored Tokens</h2> <div class="spec-production d2" id="Ignored" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L14-L19"> <a href="#Ignored" data-name="Ignored">Ignored</a><div class="spec-rhs"><a href="#UnicodeBOM" data-name="UnicodeBOM">UnicodeBOM</a></div> <div class="spec-rhs"><a href="#WhiteSpace" data-name="WhiteSpace">WhiteSpace</a></div> <div class="spec-rhs"><a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a></div> <div class="spec-rhs"><a href="#Comment" data-name="Comment">Comment</a></div> <div class="spec-rhs"><a href="#Comma" data-name="Comma">Comma</a></div> </div> <div class="spec-production d2" id="UnicodeBOM" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L21"> <a href="#UnicodeBOM" data-name="UnicodeBOM">UnicodeBOM</a><div class="spec-rhs">Byte Order Mark (U+FEFF)</div> </div> <div class="spec-production d2" id="WhiteSpace" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L23-L25"> <a href="#WhiteSpace" data-name="WhiteSpace">WhiteSpace</a><div class="spec-rhs">Horizontal Tab (U+0009)</div> <div class="spec-rhs">Space (U+0020)</div> </div> <div class="spec-production d2" id="LineTerminator" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L27-L30"> <a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a><div class="spec-rhs">New Line (U+000A)</div> <div class="spec-rhs">Carriage Return (U+000D)New Line (U+000A)</div> <div class="spec-rhs">Carriage Return (U+000D)New Line (U+000A)</div> </div> <div class="spec-production d2" id="Comment" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L32"> <a href="#Comment" data-name="Comment">Comment</a><div class="spec-rhs">#<a href="#CommentChar" data-name="CommentChar">CommentChar</a>listopt<a href="#CommentChar" data-name="CommentChar">CommentChar</a></div> </div> <div class="spec-production d2" id="CommentChar" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L34"> <a href="#CommentChar" data-name="CommentChar">CommentChar</a><div class="spec-rhs"><a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a><a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a></div> </div> <div class="spec-production d2" id="Comma" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L36"> <a href="#Comma" data-name="Comma">Comma</a><div class="spec-rhs">,</div> </div> </section> <section id="sec-Appendix-Grammar-Summary.Lexical-Tokens" secid="B.3"> <h2 data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L39"><a href="#sec-Appendix-Grammar-Summary.Lexical-Tokens">B.3</a>Lexical Tokens</h2> <div class="spec-production d2" id="Token" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L41-L46"> <a href="#Token" data-name="Token">Token</a><div class="spec-rhs"><a href="#Punctuator" data-name="Punctuator">Punctuator</a></div> <div class="spec-rhs"><a href="#Name" data-name="Name">Name</a></div> <div class="spec-rhs"><a href="#IntValue" data-name="IntValue">IntValue</a></div> <div class="spec-rhs"><a href="#FloatValue" data-name="FloatValue">FloatValue</a></div> <div class="spec-rhs"><a href="#StringValue" data-name="StringValue">StringValue</a></div> </div> <div class="spec-production d2" id="Punctuator" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L48"> <a href="#Punctuator" data-name="Punctuator">Punctuator</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">!</td><td class="spec-rhs">$</td><td class="spec-rhs">&</td><td class="spec-rhs">(</td><td class="spec-rhs">)</td><td class="spec-rhs">...</td><td class="spec-rhs">:</td><td class="spec-rhs">=</td><td class="spec-rhs">@</td><td class="spec-rhs">[</td><td class="spec-rhs">]</td><td class="spec-rhs">{</td><td class="spec-rhs">|</td><td class="spec-rhs">}</td></tr> </table></div></div> </div> <div class="spec-production d2" id="Name" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L50-L51"> <a href="#Name" data-name="Name">Name</a><div class="spec-rhs"><a href="#NameStart" data-name="NameStart">NameStart</a><a href="#NameContinue" data-name="NameContinue">NameContinue</a>listopt<a href="#NameContinue" data-name="NameContinue">NameContinue</a></div> </div> <div class="spec-production d2" id="NameStart" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L53-L55"> <a href="#NameStart" data-name="NameStart">NameStart</a><div class="spec-rhs"><a href="#Letter" data-name="Letter">Letter</a></div> <div class="spec-rhs">_</div> </div> <div class="spec-production d2" id="NameContinue" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L57-L60"> <a href="#NameContinue" data-name="NameContinue">NameContinue</a><div class="spec-rhs"><a href="#Letter" data-name="Letter">Letter</a></div> <div class="spec-rhs"><a href="#Digit" data-name="Digit">Digit</a></div> <div class="spec-rhs">_</div> </div> <div class="spec-production d2" id="Letter" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L62-L66"> <a href="#Letter" data-name="Letter">Letter</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">A</td><td class="spec-rhs">B</td><td class="spec-rhs">C</td><td class="spec-rhs">D</td><td class="spec-rhs">E</td><td class="spec-rhs">F</td><td class="spec-rhs">G</td><td class="spec-rhs">H</td><td class="spec-rhs">I</td><td class="spec-rhs">J</td><td class="spec-rhs">K</td><td class="spec-rhs">L</td><td class="spec-rhs">M</td></tr> <tr> <td class="spec-rhs">N</td><td class="spec-rhs">O</td><td class="spec-rhs">P</td><td class="spec-rhs">Q</td><td class="spec-rhs">R</td><td class="spec-rhs">S</td><td class="spec-rhs">T</td><td class="spec-rhs">U</td><td class="spec-rhs">V</td><td class="spec-rhs">W</td><td class="spec-rhs">X</td><td class="spec-rhs">Y</td><td class="spec-rhs">Z</td></tr> <tr> <td class="spec-rhs">a</td><td class="spec-rhs">b</td><td class="spec-rhs">c</td><td class="spec-rhs">d</td><td class="spec-rhs">e</td><td class="spec-rhs">f</td><td class="spec-rhs">g</td><td class="spec-rhs">h</td><td class="spec-rhs">i</td><td class="spec-rhs">j</td><td class="spec-rhs">k</td><td class="spec-rhs">l</td><td class="spec-rhs">m</td></tr> <tr> <td class="spec-rhs">n</td><td class="spec-rhs">o</td><td class="spec-rhs">p</td><td class="spec-rhs">q</td><td class="spec-rhs">r</td><td class="spec-rhs">s</td><td class="spec-rhs">t</td><td class="spec-rhs">u</td><td class="spec-rhs">v</td><td class="spec-rhs">w</td><td class="spec-rhs">x</td><td class="spec-rhs">y</td><td class="spec-rhs">z</td></tr> </table></div></div> </div> <div class="spec-production d2" id="Digit" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L68-L69"> <a href="#Digit" data-name="Digit">Digit</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">0</td><td class="spec-rhs">1</td><td class="spec-rhs">2</td><td class="spec-rhs">3</td><td class="spec-rhs">4</td><td class="spec-rhs">5</td><td class="spec-rhs">6</td><td class="spec-rhs">7</td><td class="spec-rhs">8</td><td class="spec-rhs">9</td></tr> </table></div></div> </div> <div class="spec-production d2" id="IntValue" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L71"> <a href="#IntValue" data-name="IntValue">IntValue</a><div class="spec-rhs"><a href="#IntegerPart" data-name="IntegerPart">IntegerPart</a><a href="#Digit" data-name="Digit">Digit</a>.<a href="#NameStart" data-name="NameStart">NameStart</a></div> </div> <div class="spec-production d2" id="IntegerPart" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L73-L75"> <a href="#IntegerPart" data-name="IntegerPart">IntegerPart</a><div class="spec-rhs"><a href="#NegativeSign" data-name="NegativeSign">NegativeSign</a>opt0</div> <div class="spec-rhs"><a href="#NegativeSign" data-name="NegativeSign">NegativeSign</a>opt<a href="#NonZeroDigit" data-name="NonZeroDigit">NonZeroDigit</a><a href="#Digit" data-name="Digit">Digit</a>listopt</div> </div> <div class="spec-production d2" id="NegativeSign" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L77"> <a href="#NegativeSign" data-name="NegativeSign">NegativeSign</a><div class="spec-rhs">-</div> </div> <div class="spec-production d2" id="NonZeroDigit" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L79"> <a href="#NonZeroDigit" data-name="NonZeroDigit">NonZeroDigit</a><div class="spec-rhs"><a href="#Digit" data-name="Digit">Digit</a>0</div> </div> <div class="spec-production d2" id="FloatValue" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L81-L84"> <a href="#FloatValue" data-name="FloatValue">FloatValue</a><div class="spec-rhs"><a href="#IntegerPart" data-name="IntegerPart">IntegerPart</a><a href="#FractionalPart" data-name="FractionalPart">FractionalPart</a><a href="#ExponentPart" data-name="ExponentPart">ExponentPart</a><a href="#Digit" data-name="Digit">Digit</a>.<a href="#NameStart" data-name="NameStart">NameStart</a></div> <div class="spec-rhs"><a href="#IntegerPart" data-name="IntegerPart">IntegerPart</a><a href="#FractionalPart" data-name="FractionalPart">FractionalPart</a><a href="#Digit" data-name="Digit">Digit</a>.<a href="#NameStart" data-name="NameStart">NameStart</a></div> <div class="spec-rhs"><a href="#IntegerPart" data-name="IntegerPart">IntegerPart</a><a href="#ExponentPart" data-name="ExponentPart">ExponentPart</a><a href="#Digit" data-name="Digit">Digit</a>.<a href="#NameStart" data-name="NameStart">NameStart</a></div> </div> <div class="spec-production d2" id="FractionalPart" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L86"> <a href="#FractionalPart" data-name="FractionalPart">FractionalPart</a><div class="spec-rhs">.<a href="#Digit" data-name="Digit">Digit</a>list</div> </div> <div class="spec-production d2" id="ExponentPart" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L88"> <a href="#ExponentPart" data-name="ExponentPart">ExponentPart</a><div class="spec-rhs"><a href="#ExponentIndicator" data-name="ExponentIndicator">ExponentIndicator</a><a href="#Sign" data-name="Sign">Sign</a>opt<a href="#Digit" data-name="Digit">Digit</a>list</div> </div> <div class="spec-production d2" id="ExponentIndicator" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L90"> <a href="#ExponentIndicator" data-name="ExponentIndicator">ExponentIndicator</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">e</td><td class="spec-rhs">E</td></tr> </table></div></div> </div> <div class="spec-production d2" id="Sign" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L92"> <a href="#Sign" data-name="Sign">Sign</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">+</td><td class="spec-rhs">-</td></tr> </table></div></div> </div> <div class="spec-production d2" id="StringValue" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L94-L97"> <a href="#StringValue" data-name="StringValue">StringValue</a><div class="spec-rhs">"""</div> <div class="spec-rhs">"<a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a>list"</div> <div class="spec-rhs">"""<a href="#BlockStringCharacter" data-name="BlockStringCharacter">BlockStringCharacter</a>listopt"""</div> </div> <div class="spec-production d2" id="StringCharacter" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L99-L102"> <a href="#StringCharacter" data-name="StringCharacter">StringCharacter</a><div class="spec-rhs"><a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a>"\<a href="#LineTerminator" data-name="LineTerminator">LineTerminator</a></div> <div class="spec-rhs">\u<a href="#EscapedUnicode" data-name="EscapedUnicode">EscapedUnicode</a></div> <div class="spec-rhs">\<a href="#EscapedCharacter" data-name="EscapedCharacter">EscapedCharacter</a></div> </div> <div class="spec-production d2" id="EscapedUnicode" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L104"> <a href="#EscapedUnicode" data-name="EscapedUnicode">EscapedUnicode</a><div class="spec-rhs">/[0-9A-Fa-f]{4}/</div> </div> <div class="spec-production d2" id="EscapedCharacter" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L106"> <a href="#EscapedCharacter" data-name="EscapedCharacter">EscapedCharacter</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">"</td><td class="spec-rhs">\</td><td class="spec-rhs">/</td><td class="spec-rhs">b</td><td class="spec-rhs">f</td><td class="spec-rhs">n</td><td class="spec-rhs">r</td><td class="spec-rhs">t</td></tr> </table></div></div> </div> <div class="spec-production d2" id="BlockStringCharacter" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L108-L110"> <a href="#BlockStringCharacter" data-name="BlockStringCharacter">BlockStringCharacter</a><div class="spec-rhs"><a href="#SourceCharacter" data-name="SourceCharacter">SourceCharacter</a>"""\"""</div> <div class="spec-rhs">\"""</div> </div> <div id="note-5ad29" class="spec-note" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L112-L113"> <a href="#note-5ad29">Note</a> Block string values are interpreted to exclude blank initial and trailing lines and uniform indentation with <a href="#BlockStringValue()" data-name="BlockStringValue">BlockStringValue</a>().</div> </section> <section id="sec-Document-Syntax" secid="B.4"> <h2 data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L116"><a href="#sec-Document-Syntax">B.4</a>Document Syntax</h2> <div class="spec-production" id="Document" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L118"> <a href="#Document" data-name="Document">Document</a><div class="spec-rhs"><a href="#Definition" data-name="Definition">Definition</a>list</div> </div> <div class="spec-production" id="Definition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L120-L122"> <a href="#Definition" data-name="Definition">Definition</a><div class="spec-rhs"><a href="#ExecutableDefinition" data-name="ExecutableDefinition">ExecutableDefinition</a></div> <div class="spec-rhs"><a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a></div> </div> <div class="spec-production" id="ExecutableDocument" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L124"> <a href="#ExecutableDocument" data-name="ExecutableDocument">ExecutableDocument</a><div class="spec-rhs"><a href="#ExecutableDefinition" data-name="ExecutableDefinition">ExecutableDefinition</a>list</div> </div> <div class="spec-production" id="ExecutableDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L126-L128"> <a href="#ExecutableDefinition" data-name="ExecutableDefinition">ExecutableDefinition</a><div class="spec-rhs"><a href="#OperationDefinition" data-name="OperationDefinition">OperationDefinition</a></div> <div class="spec-rhs"><a href="#FragmentDefinition" data-name="FragmentDefinition">FragmentDefinition</a></div> </div> <div class="spec-production" id="OperationDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L130-L132"> <a href="#OperationDefinition" data-name="OperationDefinition">OperationDefinition</a><div class="spec-rhs"><a href="#OperationType" data-name="OperationType">OperationType</a><a href="#Name" data-name="Name">Name</a>opt<a href="#VariableDefinitions" data-name="VariableDefinitions">VariableDefinitions</a>opt<a href="#Directives" data-name="Directives">Directives</a>opt<a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a></div> <div class="spec-rhs"><a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a></div> </div> <div class="spec-production" id="OperationType" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L134"> <a href="#OperationType" data-name="OperationType">OperationType</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">query</td><td class="spec-rhs">mutation</td><td class="spec-rhs">subscription</td></tr> </table></div></div> </div> <div class="spec-production" id="SelectionSet" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L136"> <a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a><div class="spec-rhs">{<a href="#Selection" data-name="Selection">Selection</a>list}</div> </div> <div class="spec-production" id="Selection" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L138-L141"> <a href="#Selection" data-name="Selection">Selection</a><div class="spec-rhs"><a href="#Field" data-name="Field">Field</a></div> <div class="spec-rhs"><a href="#FragmentSpread" data-name="FragmentSpread">FragmentSpread</a></div> <div class="spec-rhs"><a href="#InlineFragment" data-name="InlineFragment">InlineFragment</a></div> </div> <div class="spec-production" id="Field" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L143"> <a href="#Field" data-name="Field">Field</a><div class="spec-rhs"><a href="#Alias" data-name="Alias">Alias</a>opt<a href="#Name" data-name="Name">Name</a><a href="#Arguments" data-name="Arguments">Arguments</a>opt<a href="#Directives" data-name="Directives">Directives</a>opt<a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a>opt</div> </div> <div class="spec-production" id="Alias" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L145"> <a href="#Alias" data-name="Alias">Alias</a><div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>:</div> </div> <div class="spec-production" id="Arguments" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L147"> <a href="#Arguments" data-name="Arguments">Arguments</a>Const<div class="spec-rhs">(<a href="#Argument" data-name="Argument">Argument</a>Constlist)</div> </div> <div class="spec-production" id="Argument" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L149"> <a href="#Argument" data-name="Argument">Argument</a>Const<div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>:<a href="#Value" data-name="Value">Value</a>Const</div> </div> <div class="spec-production" id="FragmentSpread" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L151"> <a href="#FragmentSpread" data-name="FragmentSpread">FragmentSpread</a><div class="spec-rhs">...<a href="#FragmentName" data-name="FragmentName">FragmentName</a><a href="#Directives" data-name="Directives">Directives</a>opt</div> </div> <div class="spec-production" id="InlineFragment" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L153"> <a href="#InlineFragment" data-name="InlineFragment">InlineFragment</a><div class="spec-rhs">...<a href="#TypeCondition" data-name="TypeCondition">TypeCondition</a>opt<a href="#Directives" data-name="Directives">Directives</a>opt<a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a></div> </div> <div class="spec-production" id="FragmentDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L155"> <a href="#FragmentDefinition" data-name="FragmentDefinition">FragmentDefinition</a><div class="spec-rhs">fragment<a href="#FragmentName" data-name="FragmentName">FragmentName</a><a href="#TypeCondition" data-name="TypeCondition">TypeCondition</a><a href="#Directives" data-name="Directives">Directives</a>opt<a href="#SelectionSet" data-name="SelectionSet">SelectionSet</a></div> </div> <div class="spec-production" id="FragmentName" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L157"> <a href="#FragmentName" data-name="FragmentName">FragmentName</a><div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>on</div> </div> <div class="spec-production" id="TypeCondition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L159"> <a href="#TypeCondition" data-name="TypeCondition">TypeCondition</a><div class="spec-rhs">on<a href="#NamedType" data-name="NamedType">NamedType</a></div> </div> <div class="spec-production" id="Value" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L161-L170"> <a href="#Value" data-name="Value">Value</a>Const<div class="spec-rhs">Const<a href="#Variable" data-name="Variable">Variable</a></div> <div class="spec-rhs"><a href="#IntValue" data-name="IntValue">IntValue</a></div> <div class="spec-rhs"><a href="#FloatValue" data-name="FloatValue">FloatValue</a></div> <div class="spec-rhs"><a href="#StringValue" data-name="StringValue">StringValue</a></div> <div class="spec-rhs"><a href="#BooleanValue" data-name="BooleanValue">BooleanValue</a></div> <div class="spec-rhs"><a href="#NullValue" data-name="NullValue">NullValue</a></div> <div class="spec-rhs"><a href="#EnumValue" data-name="EnumValue">EnumValue</a></div> <div class="spec-rhs"><a href="#ListValue" data-name="ListValue">ListValue</a>Const</div> <div class="spec-rhs"><a href="#ObjectValue" data-name="ObjectValue">ObjectValue</a>Const</div> </div> <div class="spec-production" id="BooleanValue" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L172"> <a href="#BooleanValue" data-name="BooleanValue">BooleanValue</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">true</td><td class="spec-rhs">false</td></tr> </table></div></div> </div> <div class="spec-production" id="NullValue" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L174"> <a href="#NullValue" data-name="NullValue">NullValue</a><div class="spec-rhs">null</div> </div> <div class="spec-production" id="EnumValue" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L176"> <a href="#EnumValue" data-name="EnumValue">EnumValue</a><div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>truefalsenull</div> </div> <div class="spec-production" id="ListValue" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L178-L180"> <a href="#ListValue" data-name="ListValue">ListValue</a>Const<div class="spec-rhs">[]</div> <div class="spec-rhs">[<a href="#Value" data-name="Value">Value</a>Constlist]</div> </div> <div class="spec-production" id="ObjectValue" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L182-L184"> <a href="#ObjectValue" data-name="ObjectValue">ObjectValue</a>Const<div class="spec-rhs">{}</div> <div class="spec-rhs">{<a href="#ObjectField" data-name="ObjectField">ObjectField</a>Constlist}</div> </div> <div class="spec-production" id="ObjectField" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L186"> <a href="#ObjectField" data-name="ObjectField">ObjectField</a>Const<div class="spec-rhs"><a href="#Name" data-name="Name">Name</a>:<a href="#Value" data-name="Value">Value</a>Const</div> </div> <div class="spec-production" id="VariableDefinitions" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L188"> <a href="#VariableDefinitions" data-name="VariableDefinitions">VariableDefinitions</a><div class="spec-rhs">(<a href="#VariableDefinition" data-name="VariableDefinition">VariableDefinition</a>list)</div> </div> <div class="spec-production" id="VariableDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L190"> <a href="#VariableDefinition" data-name="VariableDefinition">VariableDefinition</a><div class="spec-rhs"><a href="#Variable" data-name="Variable">Variable</a>:<a href="#Type" data-name="Type">Type</a><a href="#DefaultValue" data-name="DefaultValue">DefaultValue</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt</div> </div> <div class="spec-production" id="Variable" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L192"> <a href="#Variable" data-name="Variable">Variable</a><div class="spec-rhs">$<a href="#Name" data-name="Name">Name</a></div> </div> <div class="spec-production" id="DefaultValue" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L194"> <a href="#DefaultValue" data-name="DefaultValue">DefaultValue</a><div class="spec-rhs">=<a href="#Value" data-name="Value">Value</a>Const</div> </div> <div class="spec-production" id="Type" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L196-L199"> <a href="#Type" data-name="Type">Type</a><div class="spec-rhs"><a href="#NamedType" data-name="NamedType">NamedType</a></div> <div class="spec-rhs"><a href="#ListType" data-name="ListType">ListType</a></div> <div class="spec-rhs"><a href="#NonNullType" data-name="NonNullType">NonNullType</a></div> </div> <div class="spec-production" id="NamedType" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L201"> <a href="#NamedType" data-name="NamedType">NamedType</a><div class="spec-rhs"><a href="#Name" data-name="Name">Name</a></div> </div> <div class="spec-production" id="ListType" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L203"> <a href="#ListType" data-name="ListType">ListType</a><div class="spec-rhs">[<a href="#Type" data-name="Type">Type</a>]</div> </div> <div class="spec-production" id="NonNullType" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L205-L207"> <a href="#NonNullType" data-name="NonNullType">NonNullType</a><div class="spec-rhs"><a href="#NamedType" data-name="NamedType">NamedType</a>!</div> <div class="spec-rhs"><a href="#ListType" data-name="ListType">ListType</a>!</div> </div> <div class="spec-production" id="Directives" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L209"> <a href="#Directives" data-name="Directives">Directives</a>Const<div class="spec-rhs"><a href="#Directive" data-name="Directive">Directive</a>Constlist</div> </div> <div class="spec-production" id="Directive" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L211"> <a href="#Directive" data-name="Directive">Directive</a>Const<div class="spec-rhs">@<a href="#Name" data-name="Name">Name</a><a href="#Arguments" data-name="Arguments">Arguments</a>Constopt</div> </div> <div class="spec-production" id="TypeSystemDocument" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L213"> <a href="#TypeSystemDocument" data-name="TypeSystemDocument">TypeSystemDocument</a><div class="spec-rhs"><a href="#TypeSystemDefinition" data-name="TypeSystemDefinition">TypeSystemDefinition</a>list</div> </div> <div class="spec-production" id="TypeSystemDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L215-L218"> <a href="#TypeSystemDefinition" data-name="TypeSystemDefinition">TypeSystemDefinition</a><div class="spec-rhs"><a href="#SchemaDefinition" data-name="SchemaDefinition">SchemaDefinition</a></div> <div class="spec-rhs"><a href="#TypeDefinition" data-name="TypeDefinition">TypeDefinition</a></div> <div class="spec-rhs"><a href="#DirectiveDefinition" data-name="DirectiveDefinition">DirectiveDefinition</a></div> </div> <div class="spec-production" id="TypeSystemExtensionDocument" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L220"> <a href="#TypeSystemExtensionDocument" data-name="TypeSystemExtensionDocument">TypeSystemExtensionDocument</a><div class="spec-rhs"><a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a>list</div> </div> <div class="spec-production" id="TypeSystemDefinitionOrExtension" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L222-L224"> <a href="#TypeSystemDefinitionOrExtension" data-name="TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a><div class="spec-rhs"><a href="#TypeSystemDefinition" data-name="TypeSystemDefinition">TypeSystemDefinition</a></div> <div class="spec-rhs"><a href="#TypeSystemExtension" data-name="TypeSystemExtension">TypeSystemExtension</a></div> </div> <div class="spec-production" id="TypeSystemExtension" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L226-L228"> <a href="#TypeSystemExtension" data-name="TypeSystemExtension">TypeSystemExtension</a><div class="spec-rhs"><a href="#SchemaExtension" data-name="SchemaExtension">SchemaExtension</a></div> <div class="spec-rhs"><a href="#TypeExtension" data-name="TypeExtension">TypeExtension</a></div> </div> <div class="spec-production" id="SchemaDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L230"> <a href="#SchemaDefinition" data-name="SchemaDefinition">SchemaDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optschema<a href="#Directives" data-name="Directives">Directives</a>Constopt{<a href="#RootOperationTypeDefinition" data-name="RootOperationTypeDefinition">RootOperationTypeDefinition</a>list}</div> </div> <div class="spec-production" id="SchemaExtension" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L232-L234"> <a href="#SchemaExtension" data-name="SchemaExtension">SchemaExtension</a><div class="spec-rhs">extendschema<a href="#Directives" data-name="Directives">Directives</a>Constopt{<a href="#RootOperationTypeDefinition" data-name="RootOperationTypeDefinition">RootOperationTypeDefinition</a>list}</div> <div class="spec-rhs">extendschema<a href="#Directives" data-name="Directives">Directives</a>Const{</div> </div> <div class="spec-production" id="RootOperationTypeDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L236"> <a href="#RootOperationTypeDefinition" data-name="RootOperationTypeDefinition">RootOperationTypeDefinition</a><div class="spec-rhs"><a href="#OperationType" data-name="OperationType">OperationType</a>:<a href="#NamedType" data-name="NamedType">NamedType</a></div> </div> <div class="spec-production" id="Description" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L238"> <a href="#Description" data-name="Description">Description</a><div class="spec-rhs"><a href="#StringValue" data-name="StringValue">StringValue</a></div> </div> <div class="spec-production" id="TypeDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L240-L246"> <a href="#TypeDefinition" data-name="TypeDefinition">TypeDefinition</a><div class="spec-rhs"><a href="#ScalarTypeDefinition" data-name="ScalarTypeDefinition">ScalarTypeDefinition</a></div> <div class="spec-rhs"><a href="#ObjectTypeDefinition" data-name="ObjectTypeDefinition">ObjectTypeDefinition</a></div> <div class="spec-rhs"><a href="#InterfaceTypeDefinition" data-name="InterfaceTypeDefinition">InterfaceTypeDefinition</a></div> <div class="spec-rhs"><a href="#UnionTypeDefinition" data-name="UnionTypeDefinition">UnionTypeDefinition</a></div> <div class="spec-rhs"><a href="#EnumTypeDefinition" data-name="EnumTypeDefinition">EnumTypeDefinition</a></div> <div class="spec-rhs"><a href="#InputObjectTypeDefinition" data-name="InputObjectTypeDefinition">InputObjectTypeDefinition</a></div> </div> <div class="spec-production" id="TypeExtension" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L248-L254"> <a href="#TypeExtension" data-name="TypeExtension">TypeExtension</a><div class="spec-rhs"><a href="#ScalarTypeExtension" data-name="ScalarTypeExtension">ScalarTypeExtension</a></div> <div class="spec-rhs"><a href="#ObjectTypeExtension" data-name="ObjectTypeExtension">ObjectTypeExtension</a></div> <div class="spec-rhs"><a href="#InterfaceTypeExtension" data-name="InterfaceTypeExtension">InterfaceTypeExtension</a></div> <div class="spec-rhs"><a href="#UnionTypeExtension" data-name="UnionTypeExtension">UnionTypeExtension</a></div> <div class="spec-rhs"><a href="#EnumTypeExtension" data-name="EnumTypeExtension">EnumTypeExtension</a></div> <div class="spec-rhs"><a href="#InputObjectTypeExtension" data-name="InputObjectTypeExtension">InputObjectTypeExtension</a></div> </div> <div class="spec-production" id="ScalarTypeDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L256"> <a href="#ScalarTypeDefinition" data-name="ScalarTypeDefinition">ScalarTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optscalar<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt</div> </div> <div class="spec-production" id="ScalarTypeExtension" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L258-L259"> <a href="#ScalarTypeExtension" data-name="ScalarTypeExtension">ScalarTypeExtension</a><div class="spec-rhs">extendscalar<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Const</div> </div> <div class="spec-production" id="ObjectTypeDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L261-L263"> <a href="#ObjectTypeDefinition" data-name="ObjectTypeDefinition">ObjectTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>opttype<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#FieldsDefinition" data-name="FieldsDefinition">FieldsDefinition</a></div> <div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>opttype<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt{</div> </div> <div class="spec-production" id="ObjectTypeExtension" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L265-L268"> <a href="#ObjectTypeExtension" data-name="ObjectTypeExtension">ObjectTypeExtension</a><div class="spec-rhs">extendtype<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#FieldsDefinition" data-name="FieldsDefinition">FieldsDefinition</a></div> <div class="spec-rhs">extendtype<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Const{</div> <div class="spec-rhs">extendtype<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>{</div> </div> <div class="spec-production" id="ImplementsInterfaces" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L270-L272"> <a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a><div class="spec-rhs"><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>&<a href="#NamedType" data-name="NamedType">NamedType</a></div> <div class="spec-rhs">implements&opt<a href="#NamedType" data-name="NamedType">NamedType</a></div> </div> <div class="spec-production" id="FieldsDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L274"> <a href="#FieldsDefinition" data-name="FieldsDefinition">FieldsDefinition</a><div class="spec-rhs">{<a href="#FieldDefinition" data-name="FieldDefinition">FieldDefinition</a>list}</div> </div> <div class="spec-production" id="FieldDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L276"> <a href="#FieldDefinition" data-name="FieldDefinition">FieldDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>opt<a href="#Name" data-name="Name">Name</a><a href="#ArgumentsDefinition" data-name="ArgumentsDefinition">ArgumentsDefinition</a>opt:<a href="#Type" data-name="Type">Type</a><a href="#Directives" data-name="Directives">Directives</a>Constopt</div> </div> <div class="spec-production" id="ArgumentsDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L278"> <a href="#ArgumentsDefinition" data-name="ArgumentsDefinition">ArgumentsDefinition</a><div class="spec-rhs">(<a href="#InputValueDefinition" data-name="InputValueDefinition">InputValueDefinition</a>list)</div> </div> <div class="spec-production" id="InputValueDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L280"> <a href="#InputValueDefinition" data-name="InputValueDefinition">InputValueDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>opt<a href="#Name" data-name="Name">Name</a>:<a href="#Type" data-name="Type">Type</a><a href="#DefaultValue" data-name="DefaultValue">DefaultValue</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt</div> </div> <div class="spec-production" id="InterfaceTypeDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L282-L284"> <a href="#InterfaceTypeDefinition" data-name="InterfaceTypeDefinition">InterfaceTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optinterface<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#FieldsDefinition" data-name="FieldsDefinition">FieldsDefinition</a></div> <div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optinterface<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt{</div> </div> <div class="spec-production" id="InterfaceTypeExtension" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L286-L289"> <a href="#InterfaceTypeExtension" data-name="InterfaceTypeExtension">InterfaceTypeExtension</a><div class="spec-rhs">extendinterface<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#FieldsDefinition" data-name="FieldsDefinition">FieldsDefinition</a></div> <div class="spec-rhs">extendinterface<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>opt<a href="#Directives" data-name="Directives">Directives</a>Const{</div> <div class="spec-rhs">extendinterface<a href="#Name" data-name="Name">Name</a><a href="#ImplementsInterfaces" data-name="ImplementsInterfaces">ImplementsInterfaces</a>{</div> </div> <div class="spec-production" id="UnionTypeDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L291"> <a href="#UnionTypeDefinition" data-name="UnionTypeDefinition">UnionTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optunion<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#UnionMemberTypes" data-name="UnionMemberTypes">UnionMemberTypes</a>opt</div> </div> <div class="spec-production" id="UnionMemberTypes" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L293-L295"> <a href="#UnionMemberTypes" data-name="UnionMemberTypes">UnionMemberTypes</a><div class="spec-rhs"><a href="#UnionMemberTypes" data-name="UnionMemberTypes">UnionMemberTypes</a>|<a href="#NamedType" data-name="NamedType">NamedType</a></div> <div class="spec-rhs">=|opt<a href="#NamedType" data-name="NamedType">NamedType</a></div> </div> <div class="spec-production" id="UnionTypeExtension" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L297-L299"> <a href="#UnionTypeExtension" data-name="UnionTypeExtension">UnionTypeExtension</a><div class="spec-rhs">extendunion<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#UnionMemberTypes" data-name="UnionMemberTypes">UnionMemberTypes</a></div> <div class="spec-rhs">extendunion<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Const</div> </div> <div class="spec-production" id="EnumTypeDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L301-L303"> <a href="#EnumTypeDefinition" data-name="EnumTypeDefinition">EnumTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optenum<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#EnumValuesDefinition" data-name="EnumValuesDefinition">EnumValuesDefinition</a></div> <div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optenum<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt{</div> </div> <div class="spec-production" id="EnumValuesDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L305"> <a href="#EnumValuesDefinition" data-name="EnumValuesDefinition">EnumValuesDefinition</a><div class="spec-rhs">{<a href="#EnumValueDefinition" data-name="EnumValueDefinition">EnumValueDefinition</a>list}</div> </div> <div class="spec-production" id="EnumValueDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L307"> <a href="#EnumValueDefinition" data-name="EnumValueDefinition">EnumValueDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>opt<a href="#EnumValue" data-name="EnumValue">EnumValue</a><a href="#Directives" data-name="Directives">Directives</a>Constopt</div> </div> <div class="spec-production" id="EnumTypeExtension" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L309-L311"> <a href="#EnumTypeExtension" data-name="EnumTypeExtension">EnumTypeExtension</a><div class="spec-rhs">extendenum<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#EnumValuesDefinition" data-name="EnumValuesDefinition">EnumValuesDefinition</a></div> <div class="spec-rhs">extendenum<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Const{</div> </div> <div class="spec-production" id="InputObjectTypeDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L313-L315"> <a href="#InputObjectTypeDefinition" data-name="InputObjectTypeDefinition">InputObjectTypeDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optinput<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#InputFieldsDefinition" data-name="InputFieldsDefinition">InputFieldsDefinition</a></div> <div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optinput<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt{</div> </div> <div class="spec-production" id="InputFieldsDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L317"> <a href="#InputFieldsDefinition" data-name="InputFieldsDefinition">InputFieldsDefinition</a><div class="spec-rhs">{<a href="#InputValueDefinition" data-name="InputValueDefinition">InputValueDefinition</a>list}</div> </div> <div class="spec-production" id="InputObjectTypeExtension" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L319-L321"> <a href="#InputObjectTypeExtension" data-name="InputObjectTypeExtension">InputObjectTypeExtension</a><div class="spec-rhs">extendinput<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Constopt<a href="#InputFieldsDefinition" data-name="InputFieldsDefinition">InputFieldsDefinition</a></div> <div class="spec-rhs">extendinput<a href="#Name" data-name="Name">Name</a><a href="#Directives" data-name="Directives">Directives</a>Const{</div> </div> <div class="spec-production" id="DirectiveDefinition" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L323"> <a href="#DirectiveDefinition" data-name="DirectiveDefinition">DirectiveDefinition</a><div class="spec-rhs"><a href="#Description" data-name="Description">Description</a>optdirective@<a href="#Name" data-name="Name">Name</a><a href="#ArgumentsDefinition" data-name="ArgumentsDefinition">ArgumentsDefinition</a>optrepeatableopton<a href="#DirectiveLocations" data-name="DirectiveLocations">DirectiveLocations</a></div> </div> <div class="spec-production" id="DirectiveLocations" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L325-L327"> <a href="#DirectiveLocations" data-name="DirectiveLocations">DirectiveLocations</a><div class="spec-rhs"><a href="#DirectiveLocations" data-name="DirectiveLocations">DirectiveLocations</a>|<a href="#DirectiveLocation" data-name="DirectiveLocation">DirectiveLocation</a></div> <div class="spec-rhs">|opt<a href="#DirectiveLocation" data-name="DirectiveLocation">DirectiveLocation</a></div> </div> <div class="spec-production" id="DirectiveLocation" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L329-L331"> <a href="#DirectiveLocation" data-name="DirectiveLocation">DirectiveLocation</a><div class="spec-rhs"><a href="#ExecutableDirectiveLocation" data-name="ExecutableDirectiveLocation">ExecutableDirectiveLocation</a></div> <div class="spec-rhs"><a href="#TypeSystemDirectiveLocation" data-name="TypeSystemDirectiveLocation">TypeSystemDirectiveLocation</a></div> </div> <div class="spec-production" id="ExecutableDirectiveLocation" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L333-L341"> <a href="#ExecutableDirectiveLocation" data-name="ExecutableDirectiveLocation">ExecutableDirectiveLocation</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">QUERY</td></tr> <tr> <td class="spec-rhs">MUTATION</td></tr> <tr> <td class="spec-rhs">SUBSCRIPTION</td></tr> <tr> <td class="spec-rhs">FIELD</td></tr> <tr> <td class="spec-rhs">FRAGMENT_DEFINITION</td></tr> <tr> <td class="spec-rhs">FRAGMENT_SPREAD</td></tr> <tr> <td class="spec-rhs">INLINE_FRAGMENT</td></tr> <tr> <td class="spec-rhs">VARIABLE_DEFINITION</td></tr> </table></div></div> </div> <div class="spec-production" id="TypeSystemDirectiveLocation" data-source="spec/Appendix%20B%20--%20Grammar%20Summary.md#L343-L354"> <a href="#TypeSystemDirectiveLocation" data-name="TypeSystemDirectiveLocation">TypeSystemDirectiveLocation</a><div class="spec-oneof"><div class="spec-oneof-grid"><table> <tr> <td class="spec-rhs">SCHEMA</td></tr> <tr> <td class="spec-rhs">SCALAR</td></tr> <tr> <td class="spec-rhs">OBJECT</td></tr> <tr> <td class="spec-rhs">FIELD_DEFINITION</td></tr> <tr> <td class="spec-rhs">ARGUMENT_DEFINITION</td></tr> <tr> <td class="spec-rhs">INTERFACE</td></tr> <tr> <td class="spec-rhs">UNION</td></tr> <tr> <td class="spec-rhs">ENUM</td></tr> <tr> <td class="spec-rhs">ENUM_VALUE</td></tr> <tr> <td class="spec-rhs">INPUT_OBJECT</td></tr> <tr> <td class="spec-rhs">INPUT_FIELD_DEFINITION</td></tr> </table></div></div> </div> </section> </section> <section id="index" secid="index" class="spec-index"> <h1> <a href="#index">§</a>Index</h1> <ol> <li><a href="#Alias">Alias</a></li> <li><a href="#AreTypesCompatible()">AreTypesCompatible</a></li> <li><a href="#Argument">Argument</a></li> <li><a href="#Arguments">Arguments</a></li> <li><a href="#ArgumentsDefinition">ArgumentsDefinition</a></li> <li><a href="#BlockStringCharacter">BlockStringCharacter</a></li> <li><a href="#BlockStringValue()">BlockStringValue</a></li> <li><a href="#BooleanValue">BooleanValue</a></li> <li><a href="#built-in-directive">built-in directive</a></li> <li><a href="#CoerceArgumentValues()">CoerceArgumentValues</a></li> <li><a href="#CoerceResult()">CoerceResult</a></li> <li><a href="#CoerceVariableValues()">CoerceVariableValues</a></li> <li><a href="#CollectFields()">CollectFields</a></li> <li><a href="#Comma">Comma</a></li> <li><a href="#Comment">Comment</a></li> <li><a href="#CommentChar">CommentChar</a></li> <li><a href="#CompleteValue()">CompleteValue</a></li> <li><a href="#CreateSourceEventStream()">CreateSourceEventStream</a></li> <li><a href="#custom-directive">custom directive</a></li> <li><a href="#DefaultValue">DefaultValue</a></li> <li><a href="#Definition">Definition</a></li> <li><a href="#Description">Description</a></li> <li><a href="#DetectFragmentCycles()">DetectFragmentCycles</a></li> <li><a href="#Digit">Digit</a></li> <li><a href="#Directive">Directive</a></li> <li><a href="#DirectiveDefinition">DirectiveDefinition</a></li> <li><a href="#DirectiveLocation">DirectiveLocation</a></li> <li><a href="#DirectiveLocations">DirectiveLocations</a></li> <li><a href="#Directives">Directives</a></li> <li><a href="#Document">Document</a></li> <li><a href="#DoesFragmentTypeApply()">DoesFragmentTypeApply</a></li> <li><a href="#EnumTypeDefinition">EnumTypeDefinition</a></li> <li><a href="#EnumTypeExtension">EnumTypeExtension</a></li> <li><a href="#EnumValue">EnumValue</a></li> <li><a href="#EnumValueDefinition">EnumValueDefinition</a></li> <li><a href="#EnumValuesDefinition">EnumValuesDefinition</a></li> <li><a href="#EscapedCharacter">EscapedCharacter</a></li> <li><a href="#EscapedUnicode">EscapedUnicode</a></li> <li><a href="#ExecutableDefinition">ExecutableDefinition</a></li> <li><a href="#ExecutableDirectiveLocation">ExecutableDirectiveLocation</a></li> <li><a href="#ExecutableDocument">ExecutableDocument</a></li> <li><a href="#ExecuteField()">ExecuteField</a></li> <li><a href="#ExecuteMutation()">ExecuteMutation</a></li> <li><a href="#ExecuteQuery()">ExecuteQuery</a></li> <li><a href="#ExecuteRequest()">ExecuteRequest</a></li> <li><a href="#ExecuteSelectionSet()">ExecuteSelectionSet</a></li> <li><a href="#ExecuteSubscriptionEvent()">ExecuteSubscriptionEvent</a></li> <li><a href="#ExponentIndicator">ExponentIndicator</a></li> <li><a href="#ExponentPart">ExponentPart</a></li> <li><a href="#Field">Field</a></li> <li><a href="#FieldDefinition">FieldDefinition</a></li> <li><a href="#FieldsDefinition">FieldsDefinition</a></li> <li><a href="#FieldsInSetCanMerge()">FieldsInSetCanMerge</a></li> <li><a href="#FloatValue">FloatValue</a></li> <li><a href="#FractionalPart">FractionalPart</a></li> <li><a href="#FragmentDefinition">FragmentDefinition</a></li> <li><a href="#FragmentName">FragmentName</a></li> <li><a href="#FragmentSpread">FragmentSpread</a></li> <li><a href="#GetOperation()">GetOperation</a></li> <li><a href="#GetPossibleTypes()">GetPossibleTypes</a></li> <li><a href="#Ignored">Ignored</a></li> <li><a href="#ImplementsInterfaces">ImplementsInterfaces</a></li> <li><a href="#InlineFragment">InlineFragment</a></li> <li><a href="#InputFieldsDefinition">InputFieldsDefinition</a></li> <li><a href="#InputObjectTypeDefinition">InputObjectTypeDefinition</a></li> <li><a href="#InputObjectTypeExtension">InputObjectTypeExtension</a></li> <li><a href="#InputValueDefinition">InputValueDefinition</a></li> <li><a href="#IntegerPart">IntegerPart</a></li> <li><a href="#InterfaceTypeDefinition">InterfaceTypeDefinition</a></li> <li><a href="#InterfaceTypeExtension">InterfaceTypeExtension</a></li> <li><a href="#IntValue">IntValue</a></li> <li><a href="#IsInputType()">IsInputType</a></li> <li><a href="#IsOutputType()">IsOutputType</a></li> <li><a href="#IsValidImplementation()">IsValidImplementation</a></li> <li><a href="#IsValidImplementationFieldType()">IsValidImplementationFieldType</a></li> <li><a href="#IsVariableUsageAllowed()">IsVariableUsageAllowed</a></li> <li><a href="#Letter">Letter</a></li> <li><a href="#LineTerminator">LineTerminator</a></li> <li><a href="#ListType">ListType</a></li> <li><a href="#ListValue">ListValue</a></li> <li><a href="#MapSourceToResponseEvent()">MapSourceToResponseEvent</a></li> <li><a href="#MergeSelectionSets()">MergeSelectionSets</a></li> <li><a href="#Name">Name</a></li> <li><a href="#NameContinue">NameContinue</a></li> <li><a href="#NamedType">NamedType</a></li> <li><a href="#NameStart">NameStart</a></li> <li><a href="#NegativeSign">NegativeSign</a></li> <li><a href="#NonNullType">NonNullType</a></li> <li><a href="#NonZeroDigit">NonZeroDigit</a></li> <li><a href="#NullValue">NullValue</a></li> <li><a href="#ObjectField">ObjectField</a></li> <li><a href="#ObjectTypeDefinition">ObjectTypeDefinition</a></li> <li><a href="#ObjectTypeExtension">ObjectTypeExtension</a></li> <li><a href="#ObjectValue">ObjectValue</a></li> <li><a href="#OperationDefinition">OperationDefinition</a></li> <li><a href="#OperationType">OperationType</a></li> <li><a href="#Punctuator">Punctuator</a></li> <li><a href="#ResolveAbstractType()">ResolveAbstractType</a></li> <li><a href="#ResolveFieldEventStream()">ResolveFieldEventStream</a></li> <li><a href="#ResolveFieldValue()">ResolveFieldValue</a></li> <li><a href="#RootOperationTypeDefinition">RootOperationTypeDefinition</a></li> <li><a href="#SameResponseShape()">SameResponseShape</a></li> <li><a href="#scalar-specification-url">scalar specification URL</a></li> <li><a href="#ScalarTypeDefinition">ScalarTypeDefinition</a></li> <li><a href="#ScalarTypeExtension">ScalarTypeExtension</a></li> <li><a href="#SchemaDefinition">SchemaDefinition</a></li> <li><a href="#SchemaExtension">SchemaExtension</a></li> <li><a href="#Selection">Selection</a></li> <li><a href="#SelectionSet">SelectionSet</a></li> <li><a href="#Sign">Sign</a></li> <li><a href="#SourceCharacter">SourceCharacter</a></li> <li><a href="#StringCharacter">StringCharacter</a></li> <li><a href="#StringValue">StringValue</a></li> <li><a href="#Subscribe()">Subscribe</a></li> <li><a href="#Token">Token</a></li> <li><a href="#Type">Type</a></li> <li><a href="#TypeCondition">TypeCondition</a></li> <li><a href="#TypeDefinition">TypeDefinition</a></li> <li><a href="#TypeExtension">TypeExtension</a></li> <li><a href="#TypeSystemDefinition">TypeSystemDefinition</a></li> <li><a href="#TypeSystemDefinitionOrExtension">TypeSystemDefinitionOrExtension</a></li> <li><a href="#TypeSystemDirectiveLocation">TypeSystemDirectiveLocation</a></li> <li><a href="#TypeSystemDocument">TypeSystemDocument</a></li> <li><a href="#TypeSystemExtension">TypeSystemExtension</a></li> <li><a href="#TypeSystemExtensionDocument">TypeSystemExtensionDocument</a></li> <li><a href="#UnicodeBOM">UnicodeBOM</a></li> <li><a href="#UnionMemberTypes">UnionMemberTypes</a></li> <li><a href="#UnionTypeDefinition">UnionTypeDefinition</a></li> <li><a href="#UnionTypeExtension">UnionTypeExtension</a></li> <li><a href="#Unsubscribe()">Unsubscribe</a></li> <li><a href="#Value">Value</a></li> <li><a href="#Variable">Variable</a></li> <li><a href="#VariableDefinition">VariableDefinition</a></li> <li><a href="#VariableDefinitions">VariableDefinitions</a></li> <li><a href="#WhiteSpace">WhiteSpace</a></li> </ol> </section> </article> <footer> Written in <a href="https://spec-md.com" target="_blank">Spec Markdown</a>.</footer> <input hidden class="spec-sidebar-toggle" type="checkbox" id="spec-sidebar-toggle" aria-hidden /><label for="spec-sidebar-toggle" aria-hidden><div class="spec-sidebar-button">☰</div></label> <div class="spec-sidebar" aria-hidden> <div class="spec-toc"> <div class="title"><a href="#">GraphQL</a></div> <ol><li id="_sidebar_1"><a href="#sec-Overview">1Overview</a></li> <li id="_sidebar_2"><a href="#sec-Language">2Language</a> <input hidden class="toggle" type="checkbox" id="_toggle_2" /><label for="_toggle_2"></label> <ol> <li id="_sidebar_2.1"><a href="#sec-Language.Source-Text">2.1Source Text</a> <input hidden class="toggle" type="checkbox" id="_toggle_2.1" /><label for="_toggle_2.1"></label> <ol> <li id="_sidebar_2.1.1"><a href="#sec-Unicode">2.1.1Unicode</a></li> <li id="_sidebar_2.1.2"><a href="#sec-White-Space">2.1.2White Space</a></li> <li id="_sidebar_2.1.3"><a href="#sec-Line-Terminators">2.1.3Line Terminators</a></li> <li id="_sidebar_2.1.4"><a href="#sec-Comments">2.1.4Comments</a></li> <li id="_sidebar_2.1.5"><a href="#sec-Insignificant-Commas">2.1.5Insignificant Commas</a></li> <li id="_sidebar_2.1.6"><a href="#sec-Language.Source-Text.Lexical-Tokens">2.1.6Lexical Tokens</a></li> <li id="_sidebar_2.1.7"><a href="#sec-Language.Source-Text.Ignored-Tokens">2.1.7Ignored Tokens</a></li> <li id="_sidebar_2.1.8"><a href="#sec-Punctuators">2.1.8Punctuators</a></li> <li id="_sidebar_2.1.9"><a href="#sec-Names">2.1.9Names</a></li> </ol> </li> <li id="_sidebar_2.2"><a href="#sec-Document">2.2Document</a></li> <li id="_sidebar_2.3"><a href="#sec-Language.Operations">2.3Operations</a></li> <li id="_sidebar_2.4"><a href="#sec-Selection-Sets">2.4Selection Sets</a></li> <li id="_sidebar_2.5"><a href="#sec-Language.Fields">2.5Fields</a></li> <li id="_sidebar_2.6"><a href="#sec-Language.Arguments">2.6Arguments</a></li> <li id="_sidebar_2.7"><a href="#sec-Field-Alias">2.7Field Alias</a></li> <li id="_sidebar_2.8"><a href="#sec-Language.Fragments">2.8Fragments</a> <input hidden class="toggle" type="checkbox" id="_toggle_2.8" /><label for="_toggle_2.8"></label> <ol> <li id="_sidebar_2.8.1"><a href="#sec-Type-Conditions">2.8.1Type Conditions</a></li> <li id="_sidebar_2.8.2"><a href="#sec-Inline-Fragments">2.8.2Inline Fragments</a></li> </ol> </li> <li id="_sidebar_2.9"><a href="#sec-Input-Values">2.9Input Values</a> <input hidden class="toggle" type="checkbox" id="_toggle_2.9" /><label for="_toggle_2.9"></label> <ol> <li id="_sidebar_2.9.1"><a href="#sec-Int-Value">2.9.1Int Value</a></li> <li id="_sidebar_2.9.2"><a href="#sec-Float-Value">2.9.2Float Value</a></li> <li id="_sidebar_2.9.3"><a href="#sec-Boolean-Value">2.9.3Boolean Value</a></li> <li id="_sidebar_2.9.4"><a href="#sec-String-Value">2.9.4String Value</a></li> <li id="_sidebar_2.9.5"><a href="#sec-Null-Value">2.9.5Null Value</a></li> <li id="_sidebar_2.9.6"><a href="#sec-Enum-Value">2.9.6Enum Value</a></li> <li id="_sidebar_2.9.7"><a href="#sec-List-Value">2.9.7List Value</a></li> <li id="_sidebar_2.9.8"><a href="#sec-Input-Object-Values">2.9.8Input Object Values</a></li> </ol> </li> <li id="_sidebar_2.10"><a href="#sec-Language.Variables">2.10Variables</a></li> <li id="_sidebar_2.11"><a href="#sec-Type-References">2.11Type References</a></li> <li id="_sidebar_2.12"><a href="#sec-Language.Directives">2.12Directives</a></li> </ol> </li> <li id="_sidebar_3"><a href="#sec-Type-System">3Type System</a> <input hidden class="toggle" type="checkbox" id="_toggle_3" /><label for="_toggle_3"></label> <ol> <li id="_sidebar_3.1"><a href="#sec-Type-System-Extensions">3.1Type System Extensions</a></li> <li id="_sidebar_3.2"><a href="#sec-Descriptions">3.2Descriptions</a></li> <li id="_sidebar_3.3"><a href="#sec-Schema">3.3Schema</a> <input hidden class="toggle" type="checkbox" id="_toggle_3.3" /><label for="_toggle_3.3"></label> <ol> <li id="_sidebar_3.3.1"><a href="#sec-Root-Operation-Types">3.3.1Root Operation Types</a></li> <li id="_sidebar_3.3.2"><a href="#sec-Schema-Extension">3.3.2Schema Extension</a></li> </ol> </li> <li id="_sidebar_3.4"><a href="#sec-Types">3.4Types</a> <input hidden class="toggle" type="checkbox" id="_toggle_3.4" /><label for="_toggle_3.4"></label> <ol> <li id="_sidebar_3.4.1"><a href="#sec-Wrapping-Types">3.4.1Wrapping Types</a></li> <li id="_sidebar_3.4.2"><a href="#sec-Input-and-Output-Types">3.4.2Input and Output Types</a></li> <li id="_sidebar_3.4.3"><a href="#sec-Type-Extensions">3.4.3Type Extensions</a></li> </ol> </li> <li id="_sidebar_3.5"><a href="#sec-Scalars">3.5Scalars</a> <input hidden class="toggle" type="checkbox" id="_toggle_3.5" /><label for="_toggle_3.5"></label> <ol> <li id="_sidebar_3.5.1"><a href="#sec-Int">3.5.1Int</a></li> <li id="_sidebar_3.5.2"><a href="#sec-Float">3.5.2Float</a></li> <li id="_sidebar_3.5.3"><a href="#sec-String">3.5.3String</a></li> <li id="_sidebar_3.5.4"><a href="#sec-Boolean">3.5.4Boolean</a></li> <li id="_sidebar_3.5.5"><a href="#sec-ID">3.5.5ID</a></li> <li id="_sidebar_3.5.6"><a href="#sec-Scalar-Extensions">3.5.6Scalar Extensions</a></li> </ol> </li> <li id="_sidebar_3.6"><a href="#sec-Objects">3.6Objects</a> <input hidden class="toggle" type="checkbox" id="_toggle_3.6" /><label for="_toggle_3.6"></label> <ol> <li id="_sidebar_3.6.1"><a href="#sec-Field-Arguments">3.6.1Field Arguments</a></li> <li id="_sidebar_3.6.2"><a href="#sec-Field-Deprecation">3.6.2Field Deprecation</a></li> <li id="_sidebar_3.6.3"><a href="#sec-Object-Extensions">3.6.3Object Extensions</a></li> </ol> </li> <li id="_sidebar_3.7"><a href="#sec-Interfaces">3.7Interfaces</a> <input hidden class="toggle" type="checkbox" id="_toggle_3.7" /><label for="_toggle_3.7"></label> <ol> <li id="_sidebar_3.7.1"><a href="#sec-Interface-Extensions">3.7.1Interface Extensions</a></li> </ol> </li> <li id="_sidebar_3.8"><a href="#sec-Unions">3.8Unions</a> <input hidden class="toggle" type="checkbox" id="_toggle_3.8" /><label for="_toggle_3.8"></label> <ol> <li id="_sidebar_3.8.1"><a href="#sec-Union-Extensions">3.8.1Union Extensions</a></li> </ol> </li> <li id="_sidebar_3.9"><a href="#sec-Enums">3.9Enums</a> <input hidden class="toggle" type="checkbox" id="_toggle_3.9" /><label for="_toggle_3.9"></label> <ol> <li id="_sidebar_3.9.1"><a href="#sec-Enum-Extensions">3.9.1Enum Extensions</a></li> </ol> </li> <li id="_sidebar_3.10"><a href="#sec-Input-Objects">3.10Input Objects</a> <input hidden class="toggle" type="checkbox" id="_toggle_3.10" /><label for="_toggle_3.10"></label> <ol> <li id="_sidebar_3.10.1"><a href="#sec-Input-Object-Extensions">3.10.1Input Object Extensions</a></li> </ol> </li> <li id="_sidebar_3.11"><a href="#sec-List">3.11List</a></li> <li id="_sidebar_3.12"><a href="#sec-Non-Null">3.12Non-Null</a> <input hidden class="toggle" type="checkbox" id="_toggle_3.12" /><label for="_toggle_3.12"></label> <ol> <li id="_sidebar_3.12.1"><a href="#sec-Combining-List-and-Non-Null">3.12.1Combining List and Non-Null</a></li> </ol> </li> <li id="_sidebar_3.13"><a href="#sec-Type-System.Directives">3.13Directives</a> <input hidden class="toggle" type="checkbox" id="_toggle_3.13" /><label for="_toggle_3.13"></label> <ol> <li id="_sidebar_3.13.1"><a href="#sec--skip">3.13.1@skip</a></li> <li id="_sidebar_3.13.2"><a href="#sec--include">3.13.2@include</a></li> <li id="_sidebar_3.13.3"><a href="#sec--deprecated">3.13.3@deprecated</a></li> <li id="_sidebar_3.13.4"><a href="#sec--specifiedBy">3.13.4@specifiedBy</a></li> </ol> </li> </ol> </li> <li id="_sidebar_4"><a href="#sec-Introspection">4Introspection</a> <input hidden class="toggle" type="checkbox" id="_toggle_4" /><label for="_toggle_4"></label> <ol> <li id="_sidebar_4.1"><a href="#sec-Type-Name-Introspection">4.1Type Name Introspection</a></li> <li id="_sidebar_4.2"><a href="#sec-Schema-Introspection">4.2Schema Introspection</a> <input hidden class="toggle" type="checkbox" id="_toggle_4.2" /><label for="_toggle_4.2"></label> <ol> <li id="_sidebar_4.2.1"><a href="#sec-The-__Schema-Type">4.2.1The __Schema Type</a></li> <li id="_sidebar_4.2.2"><a href="#sec-The-__Type-Type">4.2.2The __Type Type</a></li> <li id="_sidebar_4.2.3"><a href="#sec-The-__Field-Type">4.2.3The __Field Type</a></li> <li id="_sidebar_4.2.4"><a href="#sec-The-__InputValue-Type">4.2.4The __InputValue Type</a></li> <li id="_sidebar_4.2.5"><a href="#sec-The-__EnumValue-Type">4.2.5The __EnumValue Type</a></li> <li id="_sidebar_4.2.6"><a href="#sec-The-__Directive-Type">4.2.6The __Directive Type</a></li> </ol> </li> </ol> </li> <li id="_sidebar_5"><a href="#sec-Validation">5Validation</a> <input hidden class="toggle" type="checkbox" id="_toggle_5" /><label for="_toggle_5"></label> <ol> <li id="_sidebar_5.1"><a href="#sec-Documents">5.1Documents</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.1" /><label for="_toggle_5.1"></label> <ol> <li id="_sidebar_5.1.1"><a href="#sec-Executable-Definitions">5.1.1Executable Definitions</a></li> </ol> </li> <li id="_sidebar_5.2"><a href="#sec-Validation.Operations">5.2Operations</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.2" /><label for="_toggle_5.2"></label> <ol> <li id="_sidebar_5.2.1"><a href="#sec-Named-Operation-Definitions">5.2.1Named Operation Definitions</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.2.1" /><label for="_toggle_5.2.1"></label> <ol> <li id="_sidebar_5.2.1.1"><a href="#sec-Operation-Name-Uniqueness">5.2.1.1Operation Name Uniqueness</a></li> </ol> </li> <li id="_sidebar_5.2.2"><a href="#sec-Anonymous-Operation-Definitions">5.2.2Anonymous Operation Definitions</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.2.2" /><label for="_toggle_5.2.2"></label> <ol> <li id="_sidebar_5.2.2.1"><a href="#sec-Lone-Anonymous-Operation">5.2.2.1Lone Anonymous Operation</a></li> </ol> </li> <li id="_sidebar_5.2.3"><a href="#sec-Subscription-Operation-Definitions">5.2.3Subscription Operation Definitions</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.2.3" /><label for="_toggle_5.2.3"></label> <ol> <li id="_sidebar_5.2.3.1"><a href="#sec-Single-root-field">5.2.3.1Single root field</a></li> </ol> </li> </ol> </li> <li id="_sidebar_5.3"><a href="#sec-Validation.Fields">5.3Fields</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.3" /><label for="_toggle_5.3"></label> <ol> <li id="_sidebar_5.3.1"><a href="#sec-Field-Selections">5.3.1Field Selections</a></li> <li id="_sidebar_5.3.2"><a href="#sec-Field-Selection-Merging">5.3.2Field Selection Merging</a></li> <li id="_sidebar_5.3.3"><a href="#sec-Leaf-Field-Selections">5.3.3Leaf Field Selections</a></li> </ol> </li> <li id="_sidebar_5.4"><a href="#sec-Validation.Arguments">5.4Arguments</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.4" /><label for="_toggle_5.4"></label> <ol> <li id="_sidebar_5.4.1"><a href="#sec-Argument-Names">5.4.1Argument Names</a></li> <li id="_sidebar_5.4.2"><a href="#sec-Argument-Uniqueness">5.4.2Argument Uniqueness</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.4.2" /><label for="_toggle_5.4.2"></label> <ol> <li id="_sidebar_5.4.2.1"><a href="#sec-Required-Arguments">5.4.2.1Required Arguments</a></li> </ol> </li> </ol> </li> <li id="_sidebar_5.5"><a href="#sec-Validation.Fragments">5.5Fragments</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.5" /><label for="_toggle_5.5"></label> <ol> <li id="_sidebar_5.5.1"><a href="#sec-Fragment-Declarations">5.5.1Fragment Declarations</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.5.1" /><label for="_toggle_5.5.1"></label> <ol> <li id="_sidebar_5.5.1.1"><a href="#sec-Fragment-Name-Uniqueness">5.5.1.1Fragment Name Uniqueness</a></li> <li id="_sidebar_5.5.1.2"><a href="#sec-Fragment-Spread-Type-Existence">5.5.1.2Fragment Spread Type Existence</a></li> <li id="_sidebar_5.5.1.3"><a href="#sec-Fragments-On-Composite-Types">5.5.1.3Fragments On Composite Types</a></li> <li id="_sidebar_5.5.1.4"><a href="#sec-Fragments-Must-Be-Used">5.5.1.4Fragments Must Be Used</a></li> </ol> </li> <li id="_sidebar_5.5.2"><a href="#sec-Fragment-Spreads">5.5.2Fragment Spreads</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.5.2" /><label for="_toggle_5.5.2"></label> <ol> <li id="_sidebar_5.5.2.1"><a href="#sec-Fragment-spread-target-defined">5.5.2.1Fragment spread target defined</a></li> <li id="_sidebar_5.5.2.2"><a href="#sec-Fragment-spreads-must-not-form-cycles">5.5.2.2Fragment spreads must not form cycles</a></li> <li id="_sidebar_5.5.2.3"><a href="#sec-Fragment-spread-is-possible">5.5.2.3Fragment spread is possible</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.5.2.3" /><label for="_toggle_5.5.2.3"></label> <ol> <li id="_sidebar_5.5.2.3.1"><a href="#sec-Object-Spreads-In-Object-Scope">5.5.2.3.1Object Spreads In Object Scope</a></li> <li id="_sidebar_5.5.2.3.2"><a href="#sec-Abstract-Spreads-in-Object-Scope">5.5.2.3.2Abstract Spreads in Object Scope</a></li> <li id="_sidebar_5.5.2.3.3"><a href="#sec-Object-Spreads-In-Abstract-Scope">5.5.2.3.3Object Spreads In Abstract Scope</a></li> <li id="_sidebar_5.5.2.3.4"><a href="#sec-Abstract-Spreads-in-Abstract-Scope">5.5.2.3.4Abstract Spreads in Abstract Scope</a></li> </ol> </li> </ol> </li> </ol> </li> <li id="_sidebar_5.6"><a href="#sec-Values">5.6Values</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.6" /><label for="_toggle_5.6"></label> <ol> <li id="_sidebar_5.6.1"><a href="#sec-Values-of-Correct-Type">5.6.1Values of Correct Type</a></li> <li id="_sidebar_5.6.2"><a href="#sec-Input-Object-Field-Names">5.6.2Input Object Field Names</a></li> <li id="_sidebar_5.6.3"><a href="#sec-Input-Object-Field-Uniqueness">5.6.3Input Object Field Uniqueness</a></li> <li id="_sidebar_5.6.4"><a href="#sec-Input-Object-Required-Fields">5.6.4Input Object Required Fields</a></li> </ol> </li> <li id="_sidebar_5.7"><a href="#sec-Validation.Directives">5.7Directives</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.7" /><label for="_toggle_5.7"></label> <ol> <li id="_sidebar_5.7.1"><a href="#sec-Directives-Are-Defined">5.7.1Directives Are Defined</a></li> <li id="_sidebar_5.7.2"><a href="#sec-Directives-Are-In-Valid-Locations">5.7.2Directives Are In Valid Locations</a></li> <li id="_sidebar_5.7.3"><a href="#sec-Directives-Are-Unique-Per-Location">5.7.3Directives Are Unique Per Location</a></li> </ol> </li> <li id="_sidebar_5.8"><a href="#sec-Validation.Variables">5.8Variables</a> <input hidden class="toggle" type="checkbox" id="_toggle_5.8" /><label for="_toggle_5.8"></label> <ol> <li id="_sidebar_5.8.1"><a href="#sec-Variable-Uniqueness">5.8.1Variable Uniqueness</a></li> <li id="_sidebar_5.8.2"><a href="#sec-Variables-Are-Input-Types">5.8.2Variables Are Input Types</a></li> <li id="_sidebar_5.8.3"><a href="#sec-All-Variable-Uses-Defined">5.8.3All Variable Uses Defined</a></li> <li id="_sidebar_5.8.4"><a href="#sec-All-Variables-Used">5.8.4All Variables Used</a></li> <li id="_sidebar_5.8.5"><a href="#sec-All-Variable-Usages-are-Allowed">5.8.5All Variable Usages are Allowed</a></li> </ol> </li> </ol> </li> <li id="_sidebar_6"><a href="#sec-Execution">6Execution</a> <input hidden class="toggle" type="checkbox" id="_toggle_6" /><label for="_toggle_6"></label> <ol> <li id="_sidebar_6.1"><a href="#sec-Executing-Requests">6.1Executing Requests</a> <input hidden class="toggle" type="checkbox" id="_toggle_6.1" /><label for="_toggle_6.1"></label> <ol> <li id="_sidebar_6.1.1"><a href="#sec-Validating-Requests">6.1.1Validating Requests</a></li> <li id="_sidebar_6.1.2"><a href="#sec-Coercing-Variable-Values">6.1.2Coercing Variable Values</a></li> </ol> </li> <li id="_sidebar_6.2"><a href="#sec-Executing-Operations">6.2Executing Operations</a> <input hidden class="toggle" type="checkbox" id="_toggle_6.2" /><label for="_toggle_6.2"></label> <ol> <li id="_sidebar_6.2.1"><a href="#sec-Query">6.2.1Query</a></li> <li id="_sidebar_6.2.2"><a href="#sec-Mutation">6.2.2Mutation</a></li> <li id="_sidebar_6.2.3"><a href="#sec-Subscription">6.2.3Subscription</a> <input hidden class="toggle" type="checkbox" id="_toggle_6.2.3" /><label for="_toggle_6.2.3"></label> <ol> <li id="_sidebar_6.2.3.1"><a href="#sec-Source-Stream">6.2.3.1Source Stream</a></li> <li id="_sidebar_6.2.3.2"><a href="#sec-Response-Stream">6.2.3.2Response Stream</a></li> <li id="_sidebar_6.2.3.3"><a href="#sec-Unsubscribe">6.2.3.3Unsubscribe</a></li> </ol> </li> </ol> </li> <li id="_sidebar_6.3"><a href="#sec-Executing-Selection-Sets">6.3Executing Selection Sets</a> <input hidden class="toggle" type="checkbox" id="_toggle_6.3" /><label for="_toggle_6.3"></label> <ol> <li id="_sidebar_6.3.1"><a href="#sec-Normal-and-Serial-Execution">6.3.1Normal and Serial Execution</a></li> <li id="_sidebar_6.3.2"><a href="#sec-Field-Collection">6.3.2Field Collection</a></li> </ol> </li> <li id="_sidebar_6.4"><a href="#sec-Executing-Fields">6.4Executing Fields</a> <input hidden class="toggle" type="checkbox" id="_toggle_6.4" /><label for="_toggle_6.4"></label> <ol> <li id="_sidebar_6.4.1"><a href="#sec-Coercing-Field-Arguments">6.4.1Coercing Field Arguments</a></li> <li id="_sidebar_6.4.2"><a href="#sec-Value-Resolution">6.4.2Value Resolution</a></li> <li id="_sidebar_6.4.3"><a href="#sec-Value-Completion">6.4.3Value Completion</a></li> <li id="_sidebar_6.4.4"><a href="#sec-Handling-Field-Errors">6.4.4Handling Field Errors</a></li> </ol> </li> </ol> </li> <li id="_sidebar_7"><a href="#sec-Response">7Response</a> <input hidden class="toggle" type="checkbox" id="_toggle_7" /><label for="_toggle_7"></label> <ol> <li id="_sidebar_7.1"><a href="#sec-Response-Format">7.1Response Format</a> <input hidden class="toggle" type="checkbox" id="_toggle_7.1" /><label for="_toggle_7.1"></label> <ol> <li id="_sidebar_7.1.1"><a href="#sec-Data">7.1.1Data</a></li> <li id="_sidebar_7.1.2"><a href="#sec-Errors">7.1.2Errors</a></li> </ol> </li> <li id="_sidebar_7.2"><a href="#sec-Serialization-Format">7.2Serialization Format</a> <input hidden class="toggle" type="checkbox" id="_toggle_7.2" /><label for="_toggle_7.2"></label> <ol> <li id="_sidebar_7.2.1"><a href="#sec-JSON-Serialization">7.2.1JSON Serialization</a></li> <li id="_sidebar_7.2.2"><a href="#sec-Serialized-Map-Ordering">7.2.2Serialized Map Ordering</a></li> </ol> </li> </ol> </li> <li id="_sidebar_A"><a href="#sec-Appendix-Notation-Conventions">AAppendix: Notation Conventions</a> <input hidden class="toggle" type="checkbox" id="_toggle_A" /><label for="_toggle_A"></label> <ol> <li id="_sidebar_A.1"><a href="#sec-Context-Free-Grammar">A.1Context-Free Grammar</a></li> <li id="_sidebar_A.2"><a href="#sec-Lexical-and-Syntactical-Grammar">A.2Lexical and Syntactical Grammar</a></li> <li id="_sidebar_A.3"><a href="#sec-Grammar-Notation">A.3Grammar Notation</a></li> <li id="_sidebar_A.4"><a href="#sec-Grammar-Semantics">A.4Grammar Semantics</a></li> <li id="_sidebar_A.5"><a href="#sec-Algorithms">A.5Algorithms</a></li> </ol> </li> <li id="_sidebar_B"><a href="#sec-Appendix-Grammar-Summary">BAppendix: Grammar Summary</a> <input hidden class="toggle" type="checkbox" id="_toggle_B" /><label for="_toggle_B"></label> <ol> <li id="_sidebar_B.1"><a href="#sec-Appendix-Grammar-Summary.Source-Text">B.1Source Text</a></li> <li id="_sidebar_B.2"><a href="#sec-Appendix-Grammar-Summary.Ignored-Tokens">B.2Ignored Tokens</a></li> <li id="_sidebar_B.3"><a href="#sec-Appendix-Grammar-Summary.Lexical-Tokens">B.3Lexical Tokens</a></li> <li id="_sidebar_B.4"><a href="#sec-Document-Syntax">B.4Document Syntax</a></li> </ol> </li> <li id="_sidebar_index"><a href="#index">§Index</a></li> </ol> </div> </div> </body> </html>