This repository was archived by the owner on Jul 25, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 45
/
Copy pathGraphQL Spec.html
1164 lines (1078 loc) · 260 KB
/
GraphQL Spec.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<!-- saved from url=(0035)https://facebook.github.io/graphql/ -->
<html><!-- Built with spec-md --><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><title>GraphQL</title><link href="https://facebook.github.io/graphql/spec.css" rel="stylesheet"><link href="https://facebook.github.io/graphql/highlight.css" rel="stylesheet"></head><body><header><h1>GraphQL</h1><section id="intro"><p><em>Working Draft – October 2015</em></p><p><strong>Introduction</strong></p><p>This is a Draft RFC Specification for GraphQL, a query language created by Facebook in 2012 for describing the capabilities and requirements of data models for client‐server applications. The development of this standard started in 2015. GraphQL is a new and evolving language and is not complete. Significant enhancement will continue in future editions of this specification.</p><p><strong>Copyright notice</strong></p><p>Copyright (c) 2015, Facebook, Inc. All rights reserved.</p><p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p><ul><li>Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.</li><li>Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.</li><li>Neither the name Facebook nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.</li></ul><p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p></section><div class="spec-toc"><ol><li><a href="https://facebook.github.io/graphql/#sec-Overview"><span class="spec-secid">1</span>Overview</a></li><li><a href="https://facebook.github.io/graphql/#sec-Language"><span class="spec-secid">2</span>Language</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Source-Text"><span class="spec-secid">2.1</span>Source Text</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Unicode"><span class="spec-secid">2.1.1</span>Unicode</a></li><li><a href="https://facebook.github.io/graphql/#sec-White-Space"><span class="spec-secid">2.1.2</span>White Space</a></li><li><a href="https://facebook.github.io/graphql/#sec-Line-Terminators"><span class="spec-secid">2.1.3</span>Line Terminators</a></li><li><a href="https://facebook.github.io/graphql/#sec-Comments"><span class="spec-secid">2.1.4</span>Comments</a></li><li><a href="https://facebook.github.io/graphql/#sec-Insignificant-Commas"><span class="spec-secid">2.1.5</span>Insignificant Commas</a></li><li><a href="https://facebook.github.io/graphql/#sec-Source-Text.Lexical-Tokens"><span class="spec-secid">2.1.6</span>Lexical Tokens</a></li><li><a href="https://facebook.github.io/graphql/#sec-Source-Text.Ignored-Tokens"><span class="spec-secid">2.1.7</span>Ignored Tokens</a></li><li><a href="https://facebook.github.io/graphql/#sec-Punctuators"><span class="spec-secid">2.1.8</span>Punctuators</a></li><li><a href="https://facebook.github.io/graphql/#sec-Names"><span class="spec-secid">2.1.9</span>Names</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document"><span class="spec-secid">2.2</span>Query Document</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Operations"><span class="spec-secid">2.2.1</span>Operations</a></li><li><a href="https://facebook.github.io/graphql/#sec-Selection-Sets"><span class="spec-secid">2.2.2</span>Selection Sets</a></li><li><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Fields"><span class="spec-secid">2.2.3</span>Fields</a></li><li><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Arguments"><span class="spec-secid">2.2.4</span>Arguments</a></li><li><a href="https://facebook.github.io/graphql/#sec-Field-Alias"><span class="spec-secid">2.2.5</span>Field Alias</a></li><li><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Fragments"><span class="spec-secid">2.2.6</span>Fragments</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Type-Conditions"><span class="spec-secid">2.2.6.1</span>Type Conditions</a></li><li><a href="https://facebook.github.io/graphql/#sec-Inline-Fragments"><span class="spec-secid">2.2.6.2</span>Inline Fragments</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Input-Values"><span class="spec-secid">2.2.7</span>Input Values</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Int-Value"><span class="spec-secid">2.2.7.1</span>Int Value</a></li><li><a href="https://facebook.github.io/graphql/#sec-Float-Value"><span class="spec-secid">2.2.7.2</span>Float Value</a></li><li><a href="https://facebook.github.io/graphql/#sec-Boolean-Value"><span class="spec-secid">2.2.7.3</span>Boolean Value</a></li><li><a href="https://facebook.github.io/graphql/#sec-String-Value"><span class="spec-secid">2.2.7.4</span>String Value</a></li><li><a href="https://facebook.github.io/graphql/#sec-Enum-Value"><span class="spec-secid">2.2.7.5</span>Enum Value</a></li><li><a href="https://facebook.github.io/graphql/#sec-List-Value"><span class="spec-secid">2.2.7.6</span>List Value</a></li><li><a href="https://facebook.github.io/graphql/#sec-Input-Object-Values"><span class="spec-secid">2.2.7.7</span>Input Object Values</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Variables"><span class="spec-secid">2.2.8</span>Variables</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Variable-use-within-Fragments"><span class="spec-secid">2.2.8.1</span>Variable use within Fragments</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Input-Types"><span class="spec-secid">2.2.9</span>Input Types</a></li><li><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Directives"><span class="spec-secid">2.2.10</span>Directives</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Fragment-Directives"><span class="spec-secid">2.2.10.1</span>Fragment Directives</a></li></ol></li></ol></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Type-System"><span class="spec-secid">3</span>Type System</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Types"><span class="spec-secid">3.1</span>Types</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Scalars"><span class="spec-secid">3.1.1</span>Scalars</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Built-in-Scalars"><span class="spec-secid">3.1.1.1</span>Built-in Scalars</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Int"><span class="spec-secid">3.1.1.1.1</span>Int</a></li><li><a href="https://facebook.github.io/graphql/#sec-Float"><span class="spec-secid">3.1.1.1.2</span>Float</a></li><li><a href="https://facebook.github.io/graphql/#sec-String"><span class="spec-secid">3.1.1.1.3</span>String</a></li><li><a href="https://facebook.github.io/graphql/#sec-Boolean"><span class="spec-secid">3.1.1.1.4</span>Boolean</a></li><li><a href="https://facebook.github.io/graphql/#sec-ID"><span class="spec-secid">3.1.1.1.5</span>ID</a></li></ol></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Objects"><span class="spec-secid">3.1.2</span>Objects</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Object-Field-Arguments"><span class="spec-secid">3.1.2.1</span>Object Field Arguments</a></li><li><a href="https://facebook.github.io/graphql/#sec-Object-Field-deprecation"><span class="spec-secid">3.1.2.2</span>Object Field deprecation</a></li><li><a href="https://facebook.github.io/graphql/#sec-Object-type-validation"><span class="spec-secid">3.1.2.3</span>Object type validation</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Interfaces"><span class="spec-secid">3.1.3</span>Interfaces</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Interface-type-validation"><span class="spec-secid">3.1.3.1</span>Interface type validation</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Unions"><span class="spec-secid">3.1.4</span>Unions</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Union-type-validation"><span class="spec-secid">3.1.4.1</span>Union type validation</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Enums"><span class="spec-secid">3.1.5</span>Enums</a></li><li><a href="https://facebook.github.io/graphql/#sec-Input-Objects"><span class="spec-secid">3.1.6</span>Input Objects</a></li><li><a href="https://facebook.github.io/graphql/#sec-Lists"><span class="spec-secid">3.1.7</span>Lists</a></li><li><a href="https://facebook.github.io/graphql/#sec-Non-Null"><span class="spec-secid">3.1.8</span>Non-Null</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Type-System.Directives"><span class="spec-secid">3.2</span>Directives</a><ol><li><a href="https://facebook.github.io/graphql/#sec--skip"><span class="spec-secid">3.2.1</span>@skip</a></li><li><a href="https://facebook.github.io/graphql/#sec--include"><span class="spec-secid">3.2.2</span>@include</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Starting-types"><span class="spec-secid">3.3</span>Starting types</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Introspection"><span class="spec-secid">4</span>Introspection</a><ol><li><a href="https://facebook.github.io/graphql/#sec-General-Principles"><span class="spec-secid">4.1</span>General Principles</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Naming-conventions"><span class="spec-secid">4.1.1</span>Naming conventions</a></li><li><a href="https://facebook.github.io/graphql/#sec-Documentation"><span class="spec-secid">4.1.2</span>Documentation</a></li><li><a href="https://facebook.github.io/graphql/#sec-Deprecation"><span class="spec-secid">4.1.3</span>Deprecation</a></li><li><a href="https://facebook.github.io/graphql/#sec-Type-Name-Introspection"><span class="spec-secid">4.1.4</span>Type Name Introspection</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Schema-Introspection"><span class="spec-secid">4.2</span>Schema Introspection</a><ol><li><a href="https://facebook.github.io/graphql/#sec-The-__Type-Type"><span class="spec-secid">4.2.1</span>The "__Type" Type</a></li><li><a href="https://facebook.github.io/graphql/#sec-Type-Kinds"><span class="spec-secid">4.2.2</span>Type Kinds</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Scalar"><span class="spec-secid">4.2.2.1</span>Scalar</a></li><li><a href="https://facebook.github.io/graphql/#sec-Object"><span class="spec-secid">4.2.2.2</span>Object</a></li><li><a href="https://facebook.github.io/graphql/#sec-Union"><span class="spec-secid">4.2.2.3</span>Union</a></li><li><a href="https://facebook.github.io/graphql/#sec-Interface"><span class="spec-secid">4.2.2.4</span>Interface</a></li><li><a href="https://facebook.github.io/graphql/#sec-Enum"><span class="spec-secid">4.2.2.5</span>Enum</a></li><li><a href="https://facebook.github.io/graphql/#sec-Input-Object"><span class="spec-secid">4.2.2.6</span>Input Object</a></li><li><a href="https://facebook.github.io/graphql/#sec-List"><span class="spec-secid">4.2.2.7</span>List</a></li><li><a href="https://facebook.github.io/graphql/#sec-Non-null"><span class="spec-secid">4.2.2.8</span>Non-null</a></li><li><a href="https://facebook.github.io/graphql/#sec-Combining-List-and-Non-Null"><span class="spec-secid">4.2.2.9</span>Combining List and Non-Null</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-The-__Field-Type"><span class="spec-secid">4.2.3</span>The __Field Type</a></li><li><a href="https://facebook.github.io/graphql/#sec-The-__InputValue-Type"><span class="spec-secid">4.2.4</span>The __InputValue Type</a></li></ol></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Validation"><span class="spec-secid">5</span>Validation</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Validation.Operations"><span class="spec-secid">5.1</span>Operations</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Named-Operation-Definitions"><span class="spec-secid">5.1.1</span>Named Operation Definitions</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Operation-Name-Uniqueness"><span class="spec-secid">5.1.1.1</span>Operation Name Uniqueness</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Anonymous-Operation-Definitions"><span class="spec-secid">5.1.2</span>Anonymous Operation Definitions</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Lone-Anonymous-Operation"><span class="spec-secid">5.1.2.1</span>Lone Anonymous Operation</a></li></ol></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Validation.Fields"><span class="spec-secid">5.2</span>Fields</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Field-Selections-on-Objects-Interfaces-and-Unions-Types"><span class="spec-secid">5.2.1</span>Field Selections on Objects, Interfaces, and Unions Types</a></li><li><a href="https://facebook.github.io/graphql/#sec-Field-Selection-Merging"><span class="spec-secid">5.2.2</span>Field Selection Merging</a></li><li><a href="https://facebook.github.io/graphql/#sec-Leaf-Field-Selections"><span class="spec-secid">5.2.3</span>Leaf Field Selections</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Validation.Arguments"><span class="spec-secid">5.3</span>Arguments</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Argument-Names"><span class="spec-secid">5.3.1</span>Argument Names</a></li><li><a href="https://facebook.github.io/graphql/#sec-Argument-Uniqueness"><span class="spec-secid">5.3.2</span>Argument Uniqueness</a></li><li><a href="https://facebook.github.io/graphql/#sec-Argument-Values-Type-Correctness"><span class="spec-secid">5.3.3</span>Argument Values Type Correctness</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Compatible-Values"><span class="spec-secid">5.3.3.1</span>Compatible Values</a></li><li><a href="https://facebook.github.io/graphql/#sec-Required-Arguments"><span class="spec-secid">5.3.3.2</span>Required Arguments</a></li></ol></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Validation.Fragments"><span class="spec-secid">5.4</span>Fragments</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Fragment-Declarations"><span class="spec-secid">5.4.1</span>Fragment Declarations</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Fragment-Name-Uniqueness"><span class="spec-secid">5.4.1.1</span>Fragment Name Uniqueness</a></li><li><a href="https://facebook.github.io/graphql/#sec-Fragment-Spread-Type-Existence"><span class="spec-secid">5.4.1.2</span>Fragment Spread Type Existence</a></li><li><a href="https://facebook.github.io/graphql/#sec-Fragments-On-Composite-Types"><span class="spec-secid">5.4.1.3</span>Fragments On Composite Types</a></li><li><a href="https://facebook.github.io/graphql/#sec-Fragments-Must-Be-Used"><span class="spec-secid">5.4.1.4</span>Fragments Must Be Used</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Fragment-Spreads"><span class="spec-secid">5.4.2</span>Fragment Spreads</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Fragment-spread-target-defined"><span class="spec-secid">5.4.2.1</span>Fragment spread target defined</a></li><li><a href="https://facebook.github.io/graphql/#sec-Fragment-spreads-must-not-form-cycles"><span class="spec-secid">5.4.2.2</span>Fragment spreads must not form cycles</a></li><li><a href="https://facebook.github.io/graphql/#sec-Fragment-spread-is-possible"><span class="spec-secid">5.4.2.3</span>Fragment spread is possible</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Object-Spreads-In-Object-Scope"><span class="spec-secid">5.4.2.3.1</span>Object Spreads In Object Scope</a></li><li><a href="https://facebook.github.io/graphql/#sec-Abstract-Spreads-in-Object-Scope"><span class="spec-secid">5.4.2.3.2</span>Abstract Spreads in Object Scope</a></li><li><a href="https://facebook.github.io/graphql/#sec-Object-Spreads-In-Abstract-Scope"><span class="spec-secid">5.4.2.3.3</span>Object Spreads In Abstract Scope</a></li><li><a href="https://facebook.github.io/graphql/#sec-Abstract-Spreads-in-Abstract-Scope"><span class="spec-secid">5.4.2.3.4</span>Abstract Spreads in Abstract Scope</a></li></ol></li></ol></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Values"><span class="spec-secid">5.5</span>Values</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Input-Object-Field-Uniqueness"><span class="spec-secid">5.5.1</span>Input Object Field Uniqueness</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Validation.Directives"><span class="spec-secid">5.6</span>Directives</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Directives-Are-Defined"><span class="spec-secid">5.6.1</span>Directives Are Defined</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Validation.Operations"><span class="spec-secid">5.7</span>Operations</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Validation.Operations.Variables"><span class="spec-secid">5.7.1</span>Variables</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Variable-Default-Values-Are-Correctly-Typed"><span class="spec-secid">5.7.1.1</span>Variable Default Values Are Correctly Typed</a></li><li><a href="https://facebook.github.io/graphql/#sec-Variables-Are-Input-Types"><span class="spec-secid">5.7.1.2</span>Variables Are Input Types</a></li><li><a href="https://facebook.github.io/graphql/#sec-All-Variable-Uses-Defined"><span class="spec-secid">5.7.1.3</span>All Variable Uses Defined</a></li><li><a href="https://facebook.github.io/graphql/#sec-All-Variables-Used"><span class="spec-secid">5.7.1.4</span>All Variables Used</a></li><li><a href="https://facebook.github.io/graphql/#sec-All-Variable-Usages-are-Allowed"><span class="spec-secid">5.7.1.5</span>All Variable Usages are Allowed</a></li></ol></li></ol></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Execution"><span class="spec-secid">6</span>Execution</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Evaluating-requests"><span class="spec-secid">6.1</span>Evaluating requests</a></li><li><a href="https://facebook.github.io/graphql/#sec-Coercing-Variables"><span class="spec-secid">6.2</span>Coercing Variables</a></li><li><a href="https://facebook.github.io/graphql/#sec-Evaluating-operations"><span class="spec-secid">6.3</span>Evaluating operations</a></li><li><a href="https://facebook.github.io/graphql/#sec-Evaluating-selection-sets"><span class="spec-secid">6.4</span>Evaluating selection sets</a></li><li><a href="https://facebook.github.io/graphql/#sec-Evaluating-a-grouped-field-set"><span class="spec-secid">6.5</span>Evaluating a grouped field set</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Field-entries"><span class="spec-secid">6.5.1</span>Field entries</a></li><li><a href="https://facebook.github.io/graphql/#sec-Normal-evaluation"><span class="spec-secid">6.5.2</span>Normal evaluation</a></li><li><a href="https://facebook.github.io/graphql/#sec-Serial-execution"><span class="spec-secid">6.5.3</span>Serial execution</a></li><li><a href="https://facebook.github.io/graphql/#sec-Error-handling"><span class="spec-secid">6.5.4</span>Error handling</a></li><li><a href="https://facebook.github.io/graphql/#sec-Nullability"><span class="spec-secid">6.5.5</span>Nullability</a></li></ol></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Response"><span class="spec-secid">7</span>Response</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Serialization-Format"><span class="spec-secid">7.1</span>Serialization Format</a><ol><li><a href="https://facebook.github.io/graphql/#sec-JSON-Serialization"><span class="spec-secid">7.1.1</span>JSON Serialization</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Response-Format"><span class="spec-secid">7.2</span>Response Format</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Data"><span class="spec-secid">7.2.1</span>Data</a></li><li><a href="https://facebook.github.io/graphql/#sec-Errors"><span class="spec-secid">7.2.2</span>Errors</a></li></ol></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Appendix-Notation-Conventions"><span class="spec-secid">A</span>Appendix: Notation Conventions</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Context-Free-Grammar"><span class="spec-secid">A.1</span>Context-Free Grammar</a></li><li><a href="https://facebook.github.io/graphql/#sec-Lexical-and-Syntactical-Grammar"><span class="spec-secid">A.2</span>Lexical and Syntactical Grammar</a></li><li><a href="https://facebook.github.io/graphql/#sec-Grammar-Notation"><span class="spec-secid">A.3</span>Grammar Notation</a></li><li><a href="https://facebook.github.io/graphql/#sec-Grammar-Semantics"><span class="spec-secid">A.4</span>Grammar Semantics</a></li><li><a href="https://facebook.github.io/graphql/#sec-Algorithms"><span class="spec-secid">A.5</span>Algorithms</a></li></ol></li><li><a href="https://facebook.github.io/graphql/#sec-Appendix-Grammar-Summary"><span class="spec-secid">B</span>Appendix: Grammar Summary</a><ol><li><a href="https://facebook.github.io/graphql/#sec-Appendix-Grammar-Summary.Ignored-Tokens"><span class="spec-secid">B.1</span>Ignored Tokens</a></li><li><a href="https://facebook.github.io/graphql/#sec-Appendix-Grammar-Summary.Lexical-Tokens"><span class="spec-secid">B.2</span>Lexical Tokens</a></li><li><a href="https://facebook.github.io/graphql/#sec-Appendix-Grammar-Summary.Query-Document"><span class="spec-secid">B.3</span>Query Document</a></li></ol></li></ol></div></header><section id="sec-Overview"><h2><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Overview">1</a></span>Overview</h2><p>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.</p><p>For example, this GraphQL request will receive the name of the user with id 4 from the Facebook implementation of GraphQL.</p><pre><code>{
user(id: 4) {
name
}
}
</code></pre><p>Which produces the resulting data (in JSON):</p><pre><code>{
<span class="hljs-string">"user"</span>: {
<span class="hljs-string">"name"</span>: <span class="hljs-string">"Mark Zuckerberg"</span>
}
}
</code></pre><p>GraphQL is not a programming language capable of arbitrary computation, but is instead a language used to query application servers that have capabilities defined in this specification. GraphQL does not mandate a particular programming language or storage system for application servers that implement it. Instead, application servers 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.</p><p>GraphQL has a number of design principles:</p><ul><li><strong>Hierarchical</strong>: Most product development today involves the creation and manipulation of view hierarchies. To achieve congruence with the structure of these applications, a GraphQL query itself is structured hierarchically. The query is shaped just like the data it returns. It is a natural way for clients to describe data requirements.</li><li><strong>Product‐centric</strong>: 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 build the language and runtime necessary to enable that.</li><li><strong>Strong‐typing</strong>: Every GraphQL server defines an application‐specific type system. Queries are executed within the context of that type system. Given a query, tools can ensure that the query is both syntactically correct and valid within the GraphQL type system before execution, i.e. at development time, and the server can make certain guarantees about the shape and nature of the response.</li><li><strong>Client‐specified queries</strong>: Through its type system, a GraphQL server 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 queries are specified at field‐level granularity. In the majority of client‐server applications written without GraphQL, the server determines the data returned in its various scripted endpoints. A GraphQL query, on the other hand, returns exactly what a client asks for and no more.</li><li><strong>Introspective</strong>: GraphQL is introspective. A GraphQL server’s type system must 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><p>Because of these principles, GraphQL is a powerful and productive environment for building client applications. Product developers and designers building applications against working GraphQL servers -- 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 servers and tools.</p><p>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 server 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. </p></section><section id="sec-Language"><h2><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Language">2</a></span>Language</h2><p>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 and mutations are both operations) as well as fragments, a common unit of composition allowing for query reuse.</p><p>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 (defined by a double‐colon <code>::</code>).</p><section id="sec-Source-Text"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Source-Text">2.1</a></span>Source Text</h3><div class="spec-production d2" id="SourceCharacter"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#SourceCharacter">SourceCharacter</a></span><div class="spec-rhs"><span class="spec-rx">/[\u0009\u000A\u000D\u0020-\uFFFF]/</span></div></div><p>GraphQL documents are expressed as a sequence of <a href="http://unicode.org/standard/standard.html">Unicode</a> characters. 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.</p><section id="sec-Unicode"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Unicode">2.1.1</a></span>Unicode</h4><div class="spec-production d2" id="UnicodeBOM"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#UnicodeBOM">UnicodeBOM</a></span><div class="spec-rhs"><span class="spec-prose">Byte Order Mark (U+FEFF)</span></div></div><p>Non‐ASCII Unicode characters may freely appear within <span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringValue">StringValue</a></span> and <span class="spec-nt"><a href="https://facebook.github.io/graphql/#Comment">Comment</a></span> portions of GraphQL.</p><p>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.</p></section><section id="sec-White-Space"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-White-Space">2.1.2</a></span>White Space</h4><div class="spec-production d2" id="WhiteSpace"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#WhiteSpace">WhiteSpace</a></span><div class="spec-rhs"><span class="spec-prose">Horizontal Tab (U+0009)</span></div><div class="spec-rhs"><span class="spec-prose">Space (U+0020)</span></div></div><p>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 query document, however white space characters may appear within a <span class="spec-nt">String</span> or <span class="spec-nt"><a href="https://facebook.github.io/graphql/#Comment">Comment</a></span> token.</p><div class="spec-note">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"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Line-Terminators">2.1.3</a></span>Line Terminators</h4><div class="spec-production d2" id="LineTerminator"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#LineTerminator">LineTerminator</a></span><div class="spec-rhs"><span class="spec-prose">New Line (U+000A)</span></div><div class="spec-rhs"><span class="spec-prose">Carriage Return (U+000D)</span><span class="spec-lookahead not"><span class="spec-prose">New Line (U+000A)</span></span></div><div class="spec-rhs"><span class="spec-prose">Carriage Return (U+000D)</span><span class="spec-prose">New Line (U+000A)</span></div></div><p>Like white space, line terminators are used to improve the legibility of source text, any amount may appear before or after any other token and have no significance to the semantic meaning of a GraphQL query document. Line terminators are not found within any other token.</p><div class="spec-note">Any error reporting which provide the line number in the source of the offending syntax should use the preceding amount of <span class="spec-nt"><a href="https://facebook.github.io/graphql/#LineTerminator">LineTerminator</a></span> to produce the line number.</div></section><section id="sec-Comments"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Comments">2.1.4</a></span>Comments</h4><div class="spec-production d2" id="Comment"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Comment">Comment</a></span><div class="spec-rhs"><span class="spec-t">#</span><span class="spec-nt list optional"><a href="https://facebook.github.io/graphql/#CommentChar">CommentChar</a><span class="spec-mods"><span class="spec-mod list">list</span><span class="spec-mod optional">opt</span></span></span></div></div><div class="spec-production d2" id="CommentChar"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#CommentChar">CommentChar</a></span><div class="spec-rhs"><span class="spec-constrained"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#SourceCharacter">SourceCharacter</a></span><span class="spec-butnot"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#LineTerminator">LineTerminator</a></span></span></span></div></div><p>GraphQL source documents may contain single‐line comments, starting with the <span class="spec-t">#</span> marker.</p><p>A comment can contain any Unicode code point except <span class="spec-nt"><a href="https://facebook.github.io/graphql/#LineTerminator">LineTerminator</a></span> so a comment always consists of all code points starting with the <span class="spec-t">#</span> character up to but not including the line terminator.</p><p>Comments behave like white space and may appear after any token, or before a line terminator, and have no significance to the semantic meaning of a GraphQL query document.</p></section><section id="sec-Insignificant-Commas"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Insignificant-Commas">2.1.5</a></span>Insignificant Commas</h4><div class="spec-production d2" id="Comma"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Comma">Comma</a></span><div class="spec-rhs"><span class="spec-t">,</span></div></div><p>Similar to white space and line terminators, commas (<span class="spec-t">,</span>) are used to improve the legibility of source text and separate lexical tokens but are otherwise syntactically and semantically insignificant within GraphQL query documents.</p><p>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.</p></section><section id="sec-Source-Text.Lexical-Tokens"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Source-Text.Lexical-Tokens">2.1.6</a></span>Lexical Tokens</h4><div class="spec-production d2" id="Token"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Token">Token</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Punctuator">Punctuator</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#IntValue">IntValue</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FloatValue">FloatValue</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringValue">StringValue</a></span></div></div><p>A GraphQL document is comprised of several kinds of indivisible lexical tokens defined here in a lexical grammar by patterns of source Unicode characters.</p><p>Tokens are later used as terminal symbols in a GraphQL query document syntactic grammars.</p></section><section id="sec-Source-Text.Ignored-Tokens"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Source-Text.Ignored-Tokens">2.1.7</a></span>Ignored Tokens</h4><div class="spec-production d2" id="Ignored"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Ignored">Ignored</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#UnicodeBOM">UnicodeBOM</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#WhiteSpace">WhiteSpace</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#LineTerminator">LineTerminator</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Comment">Comment</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Comma">Comma</a></span></div></div><p>Before and after every lexical token may be any amount of ignored tokens including <span class="spec-nt"><a href="https://facebook.github.io/graphql/#WhiteSpace">WhiteSpace</a></span> and <span class="spec-nt"><a href="https://facebook.github.io/graphql/#Comment">Comment</a></span>. No ignored regions of a source document are significant, however ignored source characters may appear within a lexical token in a significant way, for example a <span class="spec-nt">String</span> may contain white space characters.</p><p>No characters are ignored while parsing a given token, as an example no white space characters are permitted between the characters defining a <span class="spec-nt"><a href="https://facebook.github.io/graphql/#FloatValue">FloatValue</a></span>.</p></section><section id="sec-Punctuators"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Punctuators">2.1.8</a></span>Punctuators</h4><div class="spec-production d2" id="Punctuator"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Punctuator">Punctuator</a></span><div class="spec-oneof"><table><tbody><tr><td class="spec-rhs"><span class="spec-t">!</span></td><td class="spec-rhs"><span class="spec-t">$</span></td><td class="spec-rhs"><span class="spec-t">(</span></td><td class="spec-rhs"><span class="spec-t">)</span></td><td class="spec-rhs"><span class="spec-t">...</span></td><td class="spec-rhs"><span class="spec-t">:</span></td><td class="spec-rhs"><span class="spec-t">=</span></td><td class="spec-rhs"><span class="spec-t">@</span></td><td class="spec-rhs"><span class="spec-t">[</span></td><td class="spec-rhs"><span class="spec-t">]</span></td><td class="spec-rhs"><span class="spec-t">{</span></td><td class="spec-rhs"><span class="spec-t">}</span></td></tr></tbody></table></div></div><p>GraphQL documents include punctuation in order to describe structure. GraphQL is a data description language and not a programming language, therefore GraphQL lacks the punctionation often used to describe mathematical expressions.</p></section><section id="sec-Names"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Names">2.1.9</a></span>Names</h4><div class="spec-production d2" id="Name"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span><div class="spec-rhs"><span class="spec-rx">/[_A-Za-z][_0-9A-Za-z]*/</span></div></div><p>GraphQL query documents are full of named things: operations, fields, arguments, directives, fragments, and variables. All names must follow the same grammatical form.</p><p>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.</p><p>Names in GraphQL are limited to this <acronym>ASCII</acronym> subset of possible characters to support interoperation with as many other systems as possible.</p></section></section><section id="sec-Language.Query-Document"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document">2.2</a></span>Query Document</h3><div class="spec-production" id="Document"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Document">Document</a></span><div class="spec-rhs"><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#Definition">Definition</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span></div></div><div class="spec-production" id="Definition"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Definition">Definition</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#OperationDefinition">OperationDefinition</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FragmentDefinition">FragmentDefinition</a></span></div></div><p>A GraphQL query document describes a complete file or request string received by a GraphQL service. A document contains multiple definitions of Operations and Fragments. GraphQL query documents are only executable by a server if they contain an operation. However documents which do not contain operations may still be parsed and validated to allow client to represent a single request across many documents.</p><p>If a document contains only one operation, that operation may be unnamed or represented in the shorthand form, which omits both the query keyword and operation name. Otherwise, if a GraphQL query document contains multiple operations, each operation must be named. When submitting a query document with multiple operations to a GraphQL service, the name of the desired operation to be executed must also be provided.</p><section id="sec-Language.Query-Document.Operations"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Operations">2.2.1</a></span>Operations</h4><div class="spec-production" id="OperationDefinition"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#OperationDefinition">OperationDefinition</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#OperationType">OperationType</a></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#Name">Name</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#VariableDefinitions">VariableDefinitions</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#Directives">Directives</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#SelectionSet">SelectionSet</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#SelectionSet">SelectionSet</a></span></div></div><div class="spec-production" id="OperationType"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#OperationType">OperationType</a></span><div class="spec-oneof"><table><tbody><tr><td class="spec-rhs"><span class="spec-t">query</span></td><td class="spec-rhs"><span class="spec-t">mutation</span></td></tr></tbody></table></div></div><p>There are two types of operations that GraphQL models:</p><ul><li>query – a read‐only fetch.</li><li>mutation – a write followed by a fetch.</li></ul><p>Each operation is represented by an optional operation name and a selection set.</p><p>For example, this mutation operation might “like” a story and then retrieve the new number of likes:</p><pre><code>mutation {
likeStory(storyID: 12345) {
story {
likeCount
}
}
}
</code></pre><p><strong>Query shorthand</strong></p><p>If a document contains only one query operation, and that query defines no variables and contains no directives, that operation may be represented in a short‐hand form which omits the query keyword and query name.</p><p>For example, this unnamed query operation is written via query shorthand.</p><pre><code>{
field
}
</code></pre><div class="spec-note">many examples below will use the query short‐hand syntax.</div></section><section id="sec-Selection-Sets"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Selection-Sets">2.2.2</a></span>Selection Sets</h4><div class="spec-production" id="SelectionSet"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#SelectionSet">SelectionSet</a></span><div class="spec-rhs"><span class="spec-t">{</span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#Selection">Selection</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span><span class="spec-t">}</span></div></div><div class="spec-production" id="Selection"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Selection">Selection</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Field">Field</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FragmentSpread">FragmentSpread</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#InlineFragment">InlineFragment</a></span></div></div><p>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.</p><pre><code>{
id
firstName
lastName
}
</code></pre><p>In this query, the <code>id</code>, <code>firstName</code>, and <code>lastName</code> fields form a selection set. Selection sets may also contain fragment references.</p></section><section id="sec-Language.Query-Document.Fields"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Fields">2.2.3</a></span>Fields</h4><div class="spec-production" id="Field"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Field">Field</a></span><div class="spec-rhs"><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#Alias">Alias</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#Arguments">Arguments</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#Directives">Directives</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#SelectionSet">SelectionSet</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span></div></div><p>A selection set is primarily composed of fields. A field describes one discrete piece of information available to request within a selection set.</p><p>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.</p><p>For example, this operation selects fields of complex data and relationships down to scalar values.</p><pre><code>{
me {
id
firstName
lastName
birthday {
month
day
}
friends {
name
}
}
}
</code></pre><p>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.</p><pre><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.Query-Document.Arguments"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Arguments">2.2.4</a></span>Arguments</h4><div class="spec-production" id="Arguments"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Arguments">Arguments</a></span><div class="spec-rhs"><span class="spec-t">(</span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#Argument">Argument</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span><span class="spec-t">)</span></div></div><div class="spec-production" id="Argument"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Argument">Argument</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span><span class="spec-t">:</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Value">Value</a></span></div></div><p>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 server’s implementation.</p><p>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>:</p><pre><code>{
user(id: 4) {
id
name
profilePic(size: 100)
}
}
</code></pre><p>Many arguments can exist for a given field:</p><pre><code>{
user(id: 4) {
id
name
profilePic(width: 100, height: 50)
}
}
</code></pre><p><strong>Arguments are unordered</strong></p><p>Arguments may be provided in any syntactic order and maintain identical semantic meaning.</p><p>These two queries are semantically identical:</p><pre><code>{
picture(width: 200, height: 100)
}
</code></pre><pre><code>{
picture(height: 100, width: 200)
}
</code></pre></section><section id="sec-Field-Alias"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Field-Alias">2.2.5</a></span>Field Alias</h4><div class="spec-production" id="Alias"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Alias">Alias</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span><span class="spec-t">:</span></div></div><p>By default, the key in the response object will use the field name queried. However, you can define a different name by specifying an alias.</p><p>In this example, we can fetch two profile pictures of different sizes and ensure the resulting object will not have duplicate keys:</p><pre><code>{
user(id: 4) {
id
name
smallPic: profilePic(size: 64)
bigPic: profilePic(size: 1024)
}
}
</code></pre><p>Which returns the result:</p><pre><code>{
<span class="hljs-string">"user"</span>: {
<span class="hljs-string">"id"</span>: <span class="hljs-number">4</span>,
<span class="hljs-string">"name"</span>: <span class="hljs-string">"Mark Zuckerberg"</span>,
<span class="hljs-string">"smallPic"</span>: <span class="hljs-string">"https://cdn.site.io/pic-4-64.jpg"</span>,
<span class="hljs-string">"bigPic"</span>: <span class="hljs-string">"https://cdn.site.io/pic-4-1024.jpg"</span>
}
}
</code></pre><p>Since the top level of a query is a field, it also can be given an alias:</p><pre><code>{
zuck: user(id: 4) {
id
name
}
}
</code></pre><p>Returns the result:</p><pre><code>{
<span class="hljs-string">"zuck"</span>: {
<span class="hljs-string">"id"</span>: <span class="hljs-number">4</span>,
<span class="hljs-string">"name"</span>: <span class="hljs-string">"Mark Zuckerberg"</span>
}
}
</code></pre><p>A field’s response key is its alias if an alias is provided, and it is otherwise the field’s name.</p></section><section id="sec-Language.Query-Document.Fragments"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Fragments">2.2.6</a></span>Fragments</h4><div class="spec-production" id="FragmentSpread"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FragmentSpread">FragmentSpread</a></span><div class="spec-rhs"><span class="spec-t">...</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FragmentName">FragmentName</a></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#Directives">Directives</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span></div></div><div class="spec-production" id="FragmentDefinition"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FragmentDefinition">FragmentDefinition</a></span><div class="spec-rhs"><span class="spec-t">fragment</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FragmentName">FragmentName</a></span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#TypeCondition">TypeCondition</a></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#Directives">Directives</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#SelectionSet">SelectionSet</a></span></div></div><div class="spec-production" id="FragmentName"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FragmentName">FragmentName</a></span><div class="spec-rhs"><span class="spec-constrained"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span><span class="spec-butnot"><span class="spec-t">on</span></span></span></div></div><p>Fragments are the primary unit of composition in GraphQL.</p><p>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.</p><p>For example, if we wanted to fetch some common information about mutual friends as well as friends of some user:</p><pre><code>query noFragments {
user(id: 4) {
friends(first: 10) {
id
name
profilePic(size: 50)
}
mutualFriends(first: 10) {
id
name
profilePic(size: 50)
}
}
}
</code></pre><p>The repeated fields could be extracted into a fragment and composed by a parent fragment or query.</p><pre><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><p>Fragments are consumed by using the spread operator (<code>...</code>). All fields selected by the fragment will be added to the query field selection at the same level as the fragment invocation. This happens through multiple levels of fragment spreads.</p><p>For example:</p><pre><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><p>The queries <code>noFragments</code>, <code>withFragments</code>, and <code>withNestedFragments</code> all produce the same response object.</p><section id="sec-Type-Conditions"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Type-Conditions">2.2.6.1</a></span>Type Conditions</h5><div class="spec-production" id="TypeCondition"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#TypeCondition">TypeCondition</a></span><div class="spec-rhs"><span class="spec-t">on</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#NamedType">NamedType</a></span></div></div><p>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>.</p><p>Fragments cannot be specified on any input value (scalar, enumeration, or input object).</p><p>Fragments can be specified on object types, interfaces, and unions.</p><p>Selections within fragments only return values when concrete type of the object it is operating on matches the type of the fragment.</p><p>For example in this query on the Facebook data model:</p><pre><code>query FragmentTyping {
profiles(handles: ["zuck", "cocacola"]) {
handle
...userFragment
...pageFragment
}
}
fragment userFragment on User {
friends {
count
}
}
fragment pageFragment on Page {
likers {
count
}
}
</code></pre><p>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.</p><pre><code>{
<span class="hljs-string">"profiles"</span> : [
{
<span class="hljs-string">"handle"</span> : <span class="hljs-string">"zuck"</span>,
<span class="hljs-string">"friends"</span> : { <span class="hljs-string">"count"</span> : <span class="hljs-number">1234</span> }
},
{
<span class="hljs-string">"handle"</span> : <span class="hljs-string">"cocacola"</span>,
<span class="hljs-string">"likers"</span> : { <span class="hljs-string">"count"</span> : <span class="hljs-number">90234512</span> }
}
]
}
</code></pre></section><section id="sec-Inline-Fragments"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Inline-Fragments">2.2.6.2</a></span>Inline Fragments</h5><div class="spec-production" id="InlineFragment"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#InlineFragment">InlineFragment</a></span><div class="spec-rhs"><span class="spec-t">...</span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#TypeCondition">TypeCondition</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#Directives">Directives</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#SelectionSet">SelectionSet</a></span></div></div><p>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.</p><pre><code>query inlineFragmentTyping {
profiles(handles: ["zuck", "cocacola"]) {
handle
... on User {
friends {
count
}
}
... on Page {
likers {
count
}
}
}
}
</code></pre><p>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.</p><pre><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"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Input-Values">2.2.7</a></span>Input Values</h4><div class="spec-production" id="Value"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Value">Value</a><span class="spec-mods"><span class="spec-params"><span class="spec-param">Const</span></span></span></span><div class="spec-rhs"><span class="spec-condition not">Const</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Variable">Variable</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#IntValue">IntValue</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FloatValue">FloatValue</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringValue">StringValue</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#BooleanValue">BooleanValue</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#EnumValue">EnumValue</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ListValue">ListValue</a><span class="spec-mods"><span class="spec-params"><span class="spec-param conditional">Const</span></span></span></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ObjectValue">ObjectValue</a><span class="spec-mods"><span class="spec-params"><span class="spec-param conditional">Const</span></span></span></span></div></div><p>Field and directive arguments accept input values of various literal primitives; input values can be scalars, enumeration values, lists, or input objects.</p><p>If not defined as constant (for example, in <span class="spec-nt"><a href="https://facebook.github.io/graphql/#DefaultValue">DefaultValue</a></span>), input values can be specified as a variable. List and inputs objects may also contain variables (unless defined to be constant).</p><section id="sec-Int-Value"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Int-Value">2.2.7.1</a></span>Int Value</h5><div class="spec-production d2" id="IntValue"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#IntValue">IntValue</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#IntegerPart">IntegerPart</a></span></div></div><div class="spec-production d2" id="IntegerPart"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#IntegerPart">IntegerPart</a></span><div class="spec-rhs"><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#NegativeSign">NegativeSign</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-t">0</span></div><div class="spec-rhs"><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#NegativeSign">NegativeSign</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#NonZeroDigit">NonZeroDigit</a></span><span class="spec-nt list optional"><a href="https://facebook.github.io/graphql/#Digit">Digit</a><span class="spec-mods"><span class="spec-mod list">list</span><span class="spec-mod optional">opt</span></span></span></div></div><div class="spec-production d2" id="NegativeSign"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#NegativeSign">NegativeSign</a></span><div class="spec-rhs"><span class="spec-t">-</span></div></div><div class="spec-production d2" id="Digit"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Digit">Digit</a></span><div class="spec-oneof"><table><tbody><tr><td class="spec-rhs"><span class="spec-t">0</span></td><td class="spec-rhs"><span class="spec-t">1</span></td><td class="spec-rhs"><span class="spec-t">2</span></td><td class="spec-rhs"><span class="spec-t">3</span></td><td class="spec-rhs"><span class="spec-t">4</span></td><td class="spec-rhs"><span class="spec-t">5</span></td><td class="spec-rhs"><span class="spec-t">6</span></td><td class="spec-rhs"><span class="spec-t">7</span></td><td class="spec-rhs"><span class="spec-t">8</span></td><td class="spec-rhs"><span class="spec-t">9</span></td></tr></tbody></table></div></div><div class="spec-production d2" id="NonZeroDigit"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#NonZeroDigit">NonZeroDigit</a></span><div class="spec-rhs"><span class="spec-constrained"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Digit">Digit</a></span><span class="spec-butnot"><span class="spec-t">0</span></span></span></div></div><p>An Int number is specified without a decimal point or exponent (ex. <code>1</code>).</p></section><section id="sec-Float-Value"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Float-Value">2.2.7.2</a></span>Float Value</h5><div class="spec-production d2" id="FloatValue"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FloatValue">FloatValue</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#IntegerPart">IntegerPart</a></span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FractionalPart">FractionalPart</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#IntegerPart">IntegerPart</a></span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ExponentPart">ExponentPart</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#IntegerPart">IntegerPart</a></span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FractionalPart">FractionalPart</a></span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ExponentPart">ExponentPart</a></span></div></div><div class="spec-production d2" id="FractionalPart"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#FractionalPart">FractionalPart</a></span><div class="spec-rhs"><span class="spec-t">.</span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#Digit">Digit</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span></div></div><div class="spec-production d2" id="ExponentPart"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ExponentPart">ExponentPart</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ExponentIndicator">ExponentIndicator</a></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#Sign">Sign</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#Digit">Digit</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span></div></div><div class="spec-production d2" id="ExponentIndicator"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ExponentIndicator">ExponentIndicator</a></span><div class="spec-oneof"><table><tbody><tr><td class="spec-rhs"><span class="spec-t">e</span></td><td class="spec-rhs"><span class="spec-t">E</span></td></tr></tbody></table></div></div><div class="spec-production d2" id="Sign"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Sign">Sign</a></span><div class="spec-oneof"><table><tbody><tr><td class="spec-rhs"><span class="spec-t">+</span></td><td class="spec-rhs"><span class="spec-t">-</span></td></tr></tbody></table></div></div><p>A Float number includes either a decimal point (ex. <code>1.0</code>) or an exponent (ex. <code>1e50</code>) or both (ex. <code>6.0221413e23</code>).</p></section><section id="sec-Boolean-Value"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Boolean-Value">2.2.7.3</a></span>Boolean Value</h5><div class="spec-production" id="BooleanValue"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#BooleanValue">BooleanValue</a></span><div class="spec-oneof"><table><tbody><tr><td class="spec-rhs"><span class="spec-t">true</span></td><td class="spec-rhs"><span class="spec-t">false</span></td></tr></tbody></table></div></div><p>The two keywords <code>true</code> and <code>false</code> represent the two boolean values.</p></section><section id="sec-String-Value"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-String-Value">2.2.7.4</a></span>String Value</h5><div class="spec-production d2" id="StringValue"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringValue">StringValue</a></span><div class="spec-rhs"><span class="spec-t">""</span></div><div class="spec-rhs"><span class="spec-t">"</span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#StringCharacter">StringCharacter</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span><span class="spec-t">"</span></div></div><div class="spec-production d2" id="StringCharacter"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringCharacter">StringCharacter</a></span><div class="spec-rhs"><span class="spec-constrained"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#SourceCharacter">SourceCharacter</a></span><span class="spec-butnot"><span class="spec-t">"</span><span class="spec-t">\</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#LineTerminator">LineTerminator</a></span></span></span></div><div class="spec-rhs"><span class="spec-t">\u</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#EscapedUnicode">EscapedUnicode</a></span></div><div class="spec-rhs"><span class="spec-t">\</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#EscapedCharacter">EscapedCharacter</a></span></div></div><div class="spec-production d2" id="EscapedUnicode"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#EscapedUnicode">EscapedUnicode</a></span><div class="spec-rhs"><span class="spec-rx">/[0-9A-Fa-f]{4}/</span></div></div><div class="spec-production d2" id="EscapedCharacter"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#EscapedCharacter">EscapedCharacter</a></span><div class="spec-oneof"><table><tbody><tr><td class="spec-rhs"><span class="spec-t">"</span></td><td class="spec-rhs"><span class="spec-t">\</span></td><td class="spec-rhs"><span class="spec-t">/</span></td><td class="spec-rhs"><span class="spec-t">b</span></td><td class="spec-rhs"><span class="spec-t">f</span></td><td class="spec-rhs"><span class="spec-t">n</span></td><td class="spec-rhs"><span class="spec-t">r</span></td><td class="spec-rhs"><span class="spec-t">t</span></td></tr></tbody></table></div></div><p>Strings are sequences of characters wrapped in double‐quotes (<code>"</code>). (ex. <code>"Hello World"</code>). White space and other otherwise‐ignored characters are significant within a string value.</p><div class="spec-note">Unicode characters are allowed within String value literals, however GraphQL source must not contain some ASCII control characters so escape sequences must be used to represent these characters.</div><p><strong>Semantics</strong></p><div class="spec-semantic d2"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringValue">StringValue</a></span><div class="spec-rhs"><span class="spec-t">""</span></div><ol><li>Return an empty Unicode character sequence.</li></ol></div><div class="spec-semantic d2"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringValue">StringValue</a></span><div class="spec-rhs"><span class="spec-t">"</span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#StringCharacter">StringCharacter</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span><span class="spec-t">"</span></div><ol><li>Return the Unicode character sequence of all <span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringCharacter">StringCharacter</a></span> Unicode character values.</li></ol></div><div class="spec-semantic d2"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringCharacter">StringCharacter</a></span><div class="spec-rhs"><span class="spec-constrained"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#SourceCharacter">SourceCharacter</a></span><span class="spec-butnot"><span class="spec-t">"</span><span class="spec-t">\</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#LineTerminator">LineTerminator</a></span></span></span></div><ol><li>Return the character value of <span class="spec-nt"><a href="https://facebook.github.io/graphql/#SourceCharacter">SourceCharacter</a></span>.</li></ol></div><div class="spec-semantic d2"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringCharacter">StringCharacter</a></span><div class="spec-rhs"><span class="spec-t">\u</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#EscapedUnicode">EscapedUnicode</a></span></div><ol><li>Return the character value represented by the UTF16 hexidecimal identifier <span class="spec-nt"><a href="https://facebook.github.io/graphql/#EscapedUnicode">EscapedUnicode</a></span>.</li></ol></div><div class="spec-semantic d2"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#StringCharacter">StringCharacter</a></span><div class="spec-rhs"><span class="spec-t">\</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#EscapedCharacter">EscapedCharacter</a></span></div><ol><li>Return the character value of <span class="spec-nt"><a href="https://facebook.github.io/graphql/#EscapedCharacter">EscapedCharacter</a></span>.</li></ol></div></section><section id="sec-Enum-Value"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Enum-Value">2.2.7.5</a></span>Enum Value</h5><div class="spec-production" id="EnumValue"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#EnumValue">EnumValue</a></span><div class="spec-rhs"><span class="spec-constrained"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span><span class="spec-butnot"><span class="spec-t">true</span><span class="spec-t">false</span><span class="spec-t">null</span></span></span></div></div><p>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.</p><p>An enum value cannot be “null” in order to avoid confusion. GraphQL does not supply a value literal to represent the concept <span class="spec-keyword">null</span>.</p></section><section id="sec-List-Value"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-List-Value">2.2.7.6</a></span>List Value</h5><div class="spec-production" id="ListValue"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ListValue">ListValue</a><span class="spec-mods"><span class="spec-params"><span class="spec-param">Const</span></span></span></span><div class="spec-rhs"><span class="spec-t">[</span><span class="spec-t">]</span></div><div class="spec-rhs"><span class="spec-t">[</span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#Value">Value</a><span class="spec-mods"><span class="spec-params"><span class="spec-param conditional">Const</span></span><span class="spec-mod list">list</span></span></span><span class="spec-t">]</span></div></div><p>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>).</p><p>Commas are optional throughout GraphQL so trailing commas are allowed and repeated commas do not represent missing values.</p><p><strong>Semantics</strong></p><div class="spec-semantic"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ListValue">ListValue</a></span><div class="spec-rhs"><span class="spec-t">[</span><span class="spec-t">]</span></div><ol><li>Return a new empty list value.</li></ol></div><div class="spec-semantic"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ListValue">ListValue</a></span><div class="spec-rhs"><span class="spec-t">[</span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#Value">Value</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span><span class="spec-t">]</span></div><ol><li>Let <var>inputList</var> be a new empty list value.</li><li>For each <span class="spec-nt list"><a href="https://facebook.github.io/graphql/#Value">Value</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span><ol><li>Let <var>value</var> be the result of evaluating <span class="spec-nt"><a href="https://facebook.github.io/graphql/#Value">Value</a></span>.</li><li>Append <var>value</var> to <var>inputList</var>.</li></ol></li><li>Return <var>inputList</var></li></ol></div></section><section id="sec-Input-Object-Values"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Input-Object-Values">2.2.7.7</a></span>Input Object Values</h5><div class="spec-production" id="ObjectValue"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ObjectValue">ObjectValue</a><span class="spec-mods"><span class="spec-params"><span class="spec-param">Const</span></span></span></span><div class="spec-rhs"><span class="spec-t">{</span><span class="spec-t">}</span></div><div class="spec-rhs"><span class="spec-t">{</span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#ObjectField">ObjectField</a><span class="spec-mods"><span class="spec-params"><span class="spec-param conditional">Const</span></span><span class="spec-mod list">list</span></span></span><span class="spec-t">}</span></div></div><div class="spec-production" id="ObjectField"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ObjectField">ObjectField</a><span class="spec-mods"><span class="spec-params"><span class="spec-param">Const</span></span></span></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span><span class="spec-t">:</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Value">Value</a><span class="spec-mods"><span class="spec-params"><span class="spec-param conditional">Const</span></span></span></span></div></div><p>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.”</p><p><strong>Semantics</strong></p><div class="spec-semantic"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ObjectValue">ObjectValue</a></span><div class="spec-rhs"><span class="spec-t">{</span><span class="spec-t">}</span></div><ol><li>Return a new input object value with no fields.</li></ol></div><div class="spec-semantic"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ObjectValue">ObjectValue</a></span><div class="spec-rhs"><span class="spec-t">{</span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#ObjectField">ObjectField</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span><span class="spec-t">}</span></div><ol><li>Let <var>inputObject</var> be a new input object value with no fields.</li><li>For each <var>field</var> in <span class="spec-nt list"><a href="https://facebook.github.io/graphql/#ObjectField">ObjectField</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span><ol><li>Let <var>name</var> be <span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span> in <var>field</var>.</li><li>Let <var>value</var> be the result of evaluating <span class="spec-nt"><a href="https://facebook.github.io/graphql/#Value">Value</a></span> in <var>field</var>.</li><li>Add a field to <var>inputObject</var> of name <var>name</var> containing value <var>value</var>.</li></ol></li><li>Return <var>inputObject</var></li></ol></div></section></section><section id="sec-Language.Query-Document.Variables"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Variables">2.2.8</a></span>Variables</h4><div class="spec-production" id="Variable"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Variable">Variable</a></span><div class="spec-rhs"><span class="spec-t">$</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span></div></div><div class="spec-production" id="VariableDefinitions"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#VariableDefinitions">VariableDefinitions</a></span><div class="spec-rhs"><span class="spec-t">(</span><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#VariableDefinition">VariableDefinition</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span><span class="spec-t">)</span></div></div><div class="spec-production" id="VariableDefinition"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#VariableDefinition">VariableDefinition</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Variable">Variable</a></span><span class="spec-t">:</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Type">Type</a></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#DefaultValue">DefaultValue</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span></div></div><div class="spec-production" id="DefaultValue"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#DefaultValue">DefaultValue</a></span><div class="spec-rhs"><span class="spec-t">=</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Value">Value</a><span class="spec-mods"><span class="spec-params"><span class="spec-param">Const</span></span></span></span></div></div><p>A GraphQL query can be parameterized with variables, maximizing query reuse, and avoiding costly string building in clients at runtime.</p><p>If not defined as constant (for example, in <span class="spec-nt"><a href="https://facebook.github.io/graphql/#DefaultValue">DefaultValue</a></span>), a <span class="spec-nt"><a href="https://facebook.github.io/graphql/#Variable">Variable</a></span> can be supplied for an input value.</p><p>Variables must be defined at the top of an operation and are in scope throughout the execution of that operation.</p><p>In this example, we want to fetch a profile picture size based on the size of a particular device:</p><pre><code>query getZuckProfile($devicePicSize: Int) {
user(id: 4) {
id
name
profilePic(size: $devicePicSize)
}
}
</code></pre><p>Values for those variables are provided to a GraphQL service along with a request so they may be substituted during execution. If providing JSON for the variables’ values, we could run this query and request profilePic of size <code>60</code> width:</p><pre><code>{
<span class="hljs-string">"devicePicSize"</span>: <span class="hljs-number">60</span>
}
</code></pre><section id="sec-Variable-use-within-Fragments"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Variable-use-within-Fragments">2.2.8.1</a></span>Variable use within Fragments</h5><p>Query variables can be used within fragments. Query 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, the operation cannot be executed.</p></section></section><section id="sec-Input-Types"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Input-Types">2.2.9</a></span>Input Types</h4><div class="spec-production" id="Type"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Type">Type</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#NamedType">NamedType</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ListType">ListType</a></span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#NonNullType">NonNullType</a></span></div></div><div class="spec-production" id="NamedType"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#NamedType">NamedType</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span></div></div><div class="spec-production" id="ListType"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ListType">ListType</a></span><div class="spec-rhs"><span class="spec-t">[</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Type">Type</a></span><span class="spec-t">]</span></div></div><div class="spec-production" id="NonNullType"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#NonNullType">NonNullType</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#NamedType">NamedType</a></span><span class="spec-t">!</span></div><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#ListType">ListType</a></span><span class="spec-t">!</span></div></div><p>GraphQL describes the types of data expected by query variables. Input types may be lists of another input type, or a non‐null variant of any other input type.</p><p><strong>Semantics</strong></p><div class="spec-semantic"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Type">Type</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span></div><ol><li>Let <var>name</var> be the string value of <span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span></li><li>Let <var>type</var> be the type defined in the Schema named <var>name</var></li><li><var>type</var> must not be <span class="spec-keyword">null</span></li><li>Return <var>type</var></li></ol></div><div class="spec-semantic"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Type">Type</a></span><div class="spec-rhs"><span class="spec-t">[</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Type">Type</a></span><span class="spec-t">]</span></div><ol><li>Let <var>itemType</var> be the result of evaluating <span class="spec-nt"><a href="https://facebook.github.io/graphql/#Type">Type</a></span></li><li>Let <var>type</var> be a List type where <var>itemType</var> is the contained type.</li><li>Return <var>type</var></li></ol></div><div class="spec-semantic"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Type">Type</a></span><div class="spec-rhs"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Type">Type</a></span><span class="spec-t">!</span></div><ol><li>Let <var>nullableType</var> be the result of evaluating <span class="spec-nt"><a href="https://facebook.github.io/graphql/#Type">Type</a></span></li><li>Let <var>type</var> be a Non‐Null type where <var>nullableType</var> is the contained type.</li><li>Return <var>type</var></li></ol></div></section><section id="sec-Language.Query-Document.Directives"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Language.Query-Document.Directives">2.2.10</a></span>Directives</h4><div class="spec-production" id="Directives"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Directives">Directives</a></span><div class="spec-rhs"><span class="spec-nt list"><a href="https://facebook.github.io/graphql/#Directive">Directive</a><span class="spec-mods"><span class="spec-mod list">list</span></span></span></div></div><div class="spec-production" id="Directive"><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Directive">Directive</a></span><div class="spec-rhs"><span class="spec-t">@</span><span class="spec-nt"><a href="https://facebook.github.io/graphql/#Name">Name</a></span><span class="spec-nt optional"><a href="https://facebook.github.io/graphql/#Arguments">Arguments</a><span class="spec-mods"><span class="spec-mod optional">opt</span></span></span></div></div><p>Directives provide a way to describe alternate runtime execution and type validation behavior in a GraphQL document.</p><p>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.</p><p>Directives have a name along with a list of arguments which may accept values of any input type.</p><p>Directives can be used to describe additional information for fields, fragments, and operations.</p><p>As future versions of GraphQL adopts new configurable execution capabilities, they may be exposed via directives.</p><section id="sec-Fragment-Directives"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Fragment-Directives">2.2.10.1</a></span>Fragment Directives</h5><p>Fragments may include directives to alter their behavior. At runtime, the directives provided on a fragment spread override those described on the definition.</p><p>For example, the following query:</p><pre><code>query hasConditionalFragment($condition: Boolean) {
...maybeFragment @include(if: $condition)
}
fragment maybeFragment on Query {
me {
name
}
}
</code></pre><p>Will have identical runtime behavior as</p><pre><code>query hasConditionalFragment($condition: Boolean) {
...maybeFragment
}
fragment maybeFragment on Query @include(if: $condition) {
me {
name
}
}
</code></pre><div class="spec-algo" id="FragmentSpreadDirectives()"><span class="spec-call"><a href="https://facebook.github.io/graphql/#FragmentSpreadDirectives()">FragmentSpreadDirectives</a>(<var>fragmentSpread</var>)</span><ol><li>Let <var>directives</var> be the set of directives on <var>fragmentSpread</var></li><li>Let <var>fragmentDefinition</var> be the FragmentDefinition in the document named <var>fragmentSpread</var> refers to.</li><li>For each <var>directive</var> in directives on <var>fragmentDefinition</var><ol><li>If <var>directives</var> does not contain a directive named <var>directive</var><ol><li>Add <var>directive</var> into <var>directives</var></li></ol></li></ol></li><li>Return <var>directives</var> </li></ol></div></section></section></section></section><section id="sec-Type-System"><h2><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Type-System">3</a></span>Type System</h2><p>The GraphQL Type system describes the capabilities of a GraphQL server and is used to determine if a query is valid. The type system also describes the input types of query variables to determine if values provided at runtime are valid.</p><p>A GraphQL server’s capabilities are referred to as that server’s “schema”. A schema is defined in terms of the types and directives it supports.</p><p>A given GraphQL schema must itself be internally valid. This section describes the rules for this validation process where relevant.</p><p>A GraphQL schema is represented by a root type for each kind of operation: query and mutation; this determines the place in the type system where those operations begin.</p><p>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).</p><p>All directives within a GraphQL schema must have unique names. A directive and a type may share the same name, since there is no ambiguity between them.</p><section id="sec-Types"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Types">3.1</a></span>Types</h3><p>The fundamental unit of any GraphQL Schema is the type. There are eight kinds of types in GraphQL.</p><p>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.</p><p>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.</p><p>GraphQL supports two abstract types: interfaces and unions.</p><p>An <code>Interface</code> defines a list of fields; <code>Object</code> types that implement that interface are guaranteed to implement those fields. Whenever the type system claims it will return an interface, it will return a valid implementing type.</p><p>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.</p><p>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. The type system might want to define that it returns a list of other types; 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 result will never be null. These two types are referred to as “wrapping types”; non‐wrapping types are referred to as “base types”. A wrapping type has an underlying “base type”, found by continually unwrapping the type until a base type is found.</p><p>Finally, oftentimes it is useful to provide complex structs as inputs to GraphQL queries; the <code>Input Object</code> type allows the schema to define exactly what data is expected from the client in these queries.</p><section id="sec-Scalars"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Scalars">3.1.1</a></span>Scalars</h4><p>As expected by the name, a scalar represents a primitive value in GraphQL. GraphQL responses take the form of a hierarchical tree; the leaves on these trees are GraphQL scalars.</p><p>All GraphQL scalars are representable as strings, though depending on the response format being used, there may be a more appropriate primitive for the given scalar type, and server should use those types when appropriate.</p><p>GraphQL provides a number of built‐in scalars, but type systems can add additional scalars with semantic meaning. For example, a GraphQL system could define a scalar called <code>Time</code> which, while serialized as a string, promises to conform to ISO‐8601. When querying a field of type <code>Time</code>, you can then rely on the ability to parse the result with an ISO‐8601 parser and use a client‐specific primitive for time. 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.</p><p><strong>Result Coercion</strong></p><p>A GraphQL server, when preparing a field of a given scalar type, must uphold the contract the scalar type describes, either by coercing the value or producing an error.</p><p>For example, a GraphQL server could be preparing a field with the scalar type <code>Int</code> and encounter a floating‐point number. Since the server must not break the contract by yielding a non‐integer, the server should truncate the fractional value and only yield the integer value. If the server encountered a boolean <code>true</code> value, it should return <code>1</code>. If the server encountered a string, it may attempt to parse the string for a base‐10 integer value. If the server encounters some value that cannot be reasonably coerced to an <code>Int</code>, then it must raise a field error.</p><p>Since this coercion behavior is not observable to clients of the GraphQL server, the precise rules of coercion are left to the implementation. The only requirement is that the server must yield values which adhere to the expected Scalar type.</p><p><strong>Input Coercion</strong></p><p>If a GraphQL server 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 query error must be raised.</p><p>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 query 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.</p><section id="sec-Built-in-Scalars"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Built-in-Scalars">3.1.1.1</a></span>Built-in Scalars</h5><p>GraphQL provides a basic set of well‐defined Scalar types. A GraphQL server should support all of these types, and a GraphQL server which provide a type by these names must adhere to the behavior described below.</p><section id="sec-Int"><h6><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Int">3.1.1.1.1</a></span>Int</h6><p>The Int scalar type represents a signed 32‐bit numeric non‐fractional values. Response formats that support a 32‐bit integer or a number type should use that type to represent this scalar.</p><p><strong>Result Coercion</strong></p><p>GraphQL servers should coerce non‐int raw values to Int when possible 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 <code>2</code> for the string <code>"2"</code>.</p><p><strong>Input Coercion</strong></p><p>When expected as an input type, only integer input values are accepted. All other input values, including strings with numeric content, must raise a query error indicating an incorrect type. If the integer input value represents a value less than -2<sup>31</sup> or greater than or equal to 2<sup>31</sup>, a query error should be raised.</p><div class="spec-note">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 id="sec-Float"><h6><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Float">3.1.1.1.2</a></span>Float</h6><p>The Float scalar type represents signed double‐precision fractional values as specified by <a href="http://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.</p><p><strong>Result Coercion</strong></p><p>GraphQL servers should coerce non‐floating‐point raw values to Float when possible 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>2.0</code> for the string <code>"2"</code>.</p><p><strong>Input Coercion</strong></p><p>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 query error indicating an incorrect type. If the integer input value represents a value not representable by IEEE 754, a query error should be raised.</p></section><section id="sec-String"><h6><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-String">3.1.1.1.3</a></span>String</h6><p>The String scalar type represents textual data, represented as UTF‐8 character sequences. The String type is most often used by GraphQL to represent free‐form human‐readable text. All response formats must support string representations, and that representation must be used here.</p><p><strong>Result Coercion</strong></p><p>GraphQL servers should coerce non‐string raw values to String when possible 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>.</p><p><strong>Input Coercion</strong></p><p>When expected as an input type, only valid UTF‐8 string input values are accepted. All other input values must raise a query error indicating an incorrect type.</p></section><section id="sec-Boolean"><h6><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Boolean">3.1.1.1.4</a></span>Boolean</h6><p>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>.</p><p><strong>Result Coercion</strong></p><p>GraphQL servers should coerce non‐boolean raw values to Boolean when possible otherwise they must raise a field error. Examples of this may include returning <code>true</code> for any non‐zero number.</p><p><strong>Input Coercion</strong></p><p>When expected as an input type, only boolean input values are accepted. All other input values must raise a query error indicating an incorrect type.</p></section><section id="sec-ID"><h6><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-ID">3.1.1.1.5</a></span>ID</h6><p>The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type is serialized in the same way as a <code>String</code>; however, it is not intended to be human‐readable. While it is often numeric, it should always serialize as a <code>String</code>.</p><p><strong>Result Coercion</strong></p><p>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="http://en.wikipedia.org/wiki/Globally_unique_identifier">GUID</a>.</p><p>GraphQL servers should coerce as appropriate given the ID formats they expect. When coercion is not possible they must raise a field error.</p><p><strong>Input Coercion</strong></p><p>When expected as an input type, any string (such as <code>"4"</code>) or integer (such as <code>4</code>) input value should be coerced to ID as appropriate for the ID formats a given GraphQL server expects. Any other input value, including float input values (such as <code>4.0</code>), must raise a query error indicating an incorrect type.</p></section></section></section><section id="sec-Objects"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Objects">3.1.2</a></span>Objects</h4><p>GraphQL queries are hierarchical and composed, describing a tree of information. While Scalar types describe the leaf values of these hierarchical queries, Objects describe the intermediate levels.</p><p>GraphQL Objects represent a list of named fields, each of which yield a value of a specific type. Object values are serialized as unordered maps, where the queried field names (or aliases) are the keys and the result of evaluating the field is the value.</p><p>For example, a type <code>Person</code> could be described as:</p><pre><code>type Person {
name: String
age: Int
picture: Url
}
</code></pre><p>Where <code>name</code> is a field that will yield a <code>String</code> value, and <code>age</code> is a field that will yield an <code>Int</code> value, and <code>picture</code> a field that will yield a <code>Url</code> value.</p><p>A query of an object value must select at least one field. This selection of fields will yield an unordered map containing exactly the subset of the object queried. Only fields that are declared on the object type may validly be queried on that object.</p><p>For example, selecting all the fields of <code>Person</code>:</p><pre><code>{
name
age
picture
}
</code></pre><p>Would yield the object:</p><pre><code>{
<span class="hljs-string">"name"</span>: <span class="hljs-string">"Mark Zuckerberg"</span>,
<span class="hljs-string">"age"</span>: <span class="hljs-number">30</span>,
<span class="hljs-string">"picture"</span>: <span class="hljs-string">"http://some.cdn/picture.jpg"</span>
}
</code></pre><p>While selecting a subset of fields:</p><pre><code>{
name
age
}
</code></pre><p>Must only yield exactly that subset:</p><pre><code>{
<span class="hljs-string">"name"</span>: <span class="hljs-string">"Mark Zuckerberg"</span>,
<span class="hljs-string">"age"</span>: <span class="hljs-number">30</span>
}
</code></pre><p>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.</p><p>For example, the <code>Person</code> type might include a <code>relationship</code>:</p><pre><code>type Person {
name: String
age: Int
picture: Url
relationship: Person
}
</code></pre><p>Valid queries must supply a nested field set for a field that returns an object, so this query is not valid:</p><pre class="spec-counter-example"><code>{
name
relationship
}
</code></pre><p>However, this example is valid:</p><pre><code>{
name
relationship {
name
}
}
</code></pre><p>And will yield the subset of each object type queried:</p><pre><code>{
<span class="hljs-string">"name"</span>: <span class="hljs-string">"Mark Zuckerberg"</span>,
<span class="hljs-string">"relationship"</span>: {
<span class="hljs-string">"name"</span>: <span class="hljs-string">"Priscilla Chan"</span>
}
}
</code></pre><p><strong>Result Coercion</strong></p><p>Determining the result of coercing an object is the heart of the GraphQL executor, so this is covered in that section of the spec.</p><p><strong>Input Coercion</strong></p><p>Objects are never valid inputs.</p><section id="sec-Object-Field-Arguments"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Object-Field-Arguments">3.1.2.1</a></span>Object Field Arguments</h5><p>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.</p><p>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.</p><pre><code>type Person {
name: String
picture(size: Int): Url
}
</code></pre><p>GraphQL queries can optionally specify arguments to their fields to provide these arguments.</p><p>This example query:</p><pre><code>{
name
picture(size: 600)
}
</code></pre><p>May yield the result:</p><pre><code>{
<span class="hljs-string">"name"</span>: <span class="hljs-string">"Mark Zuckerberg"</span>,
<span class="hljs-string">"picture"</span>: <span class="hljs-string">"http://some.cdn/picture_600.jpg"</span>
}
</code></pre><p>The type of an object field argument can be any Input type.</p></section><section id="sec-Object-Field-deprecation"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Object-Field-deprecation">3.1.2.2</a></span>Object Field deprecation</h5><p>Fields in an object may be marked as deprecated as deemed necessary by the application. It is still legal to query for these fields (to ensure existing clients are not broken by the change), but the fields should be appropriately treated in documentation and tooling.</p></section><section id="sec-Object-type-validation"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Object-type-validation">3.1.2.3</a></span>Object type validation</h5><p>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.</p><ol><li>The fields of an Object type must have unique names within that Object type; no two fields may share the same name.</li><li>An object type must be a super‐set of all interfaces it implements.<ol><li>The object type must include a field of the same name for every field defined in an interface.<ol><li>The object field must be of a type which is equal to or a sub‐type of the interface field (covariant).<ol><li>An object field type is a valid sub‐type if it is equal to (the same type as) the interface field type.</li><li>An object field type is a valid sub‐type if it is an Object type and the interface field type is either an Interface type or a Union type and the object field type is a possible type of the interface field type.</li><li>An object field type is a valid sub‐type if it is a List type and the interface field type is also a List type and the list‐item type of the object field type is a valid sub‐type of the list‐item type of the interface field type.</li><li>An object field type is a valid sub‐type if it is a Non‐Null variant of a valid sub‐type of the interface field type.</li></ol></li><li>The object field must include an argument of the same name for every argument defined in the interface field.<ol><li>The object field argument must accept the same type (invariant) as the interface field argument.</li></ol></li><li>The object field may include additional arguments not defined in the interface field, but any additional argument must not be required.</li></ol></li></ol></li></ol></section></section><section id="sec-Interfaces"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Interfaces">3.1.3</a></span>Interfaces</h4><p>GraphQL Interfaces represent a list of named fields and their arguments. GraphQL object can then implement an interface, which guarantees that they will contain the specified fields.</p><p>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.</p><p>For example, an interface may describe a required field and types such as <code>Person</code> or <code>Business</code> may then implement this interface.</p><pre><code>interface NamedEntity {
name: String
}
type Person implements NamedEntity {
name: String
age: Int
}
type Business implements NamedEntity {
name: String
employeeCount: Int
}
</code></pre><p>Fields which yield an interface are useful when one of many Object types are expected, but some fields should be guaranteed.</p><p>To continue the example, a <code>Contact</code> might refer to <code>NamedEntity</code>.</p><pre><code>type Contact {
entity: NamedEntity
phoneNumber: String
address: String
}
</code></pre><p>This allows us to write a query for a <code>Contact</code> that can select the common fields.</p><pre><code>{
entity {
name
}
phoneNumber
}
</code></pre><p>When querying for 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 query:</p><pre class="spec-counter-example"><code>{
entity {
name
age
}
phoneNumber
}
</code></pre><p>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>; the query can express this using a fragment or an inline fragment:</p><pre><code>{
entity {
name
... on Person {
age
}
},
phoneNumber
}
</code></pre><p><strong>Result Coercion</strong></p><p>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.</p><p><strong>Input Coercion</strong></p><p>Interfaces are never valid inputs.</p><section id="sec-Interface-type-validation"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Interface-type-validation">3.1.3.1</a></span>Interface type validation</h5><p>Interface types have the potential to be invalid if incorrectly defined.</p><ol><li>The fields of an Interface type must have unique names within that Interface type; no two fields may share the same name.</li></ol></section></section><section id="sec-Unions"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Unions">3.1.4</a></span>Unions</h4><p>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.</p><p>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 <strong>no</strong> fields may be queried on this type without the use of typed fragments.</p><p>For example, we might have the following type system:</p><pre><code>Union SearchResult = Photo | Person
type Person {
name: String
age: Int
}
type Photo {
height: Int
width: Int
}
type SearchQuery {
firstSearchResult: SearchResult
}
</code></pre><p>When querying the <code>firstSearchResult</code> field of type <code>SearchQuery</code>, the query would ask for all fields inside of a fragment indicating the appropriate type. If the query wanted the name if the result was a Person, and the height if it was a photo, the following query is invalid, because the union itself defines no fields:</p><pre class="spec-counter-example"><code>{
firstSearchResult {
name
height
}
}
</code></pre><p>Instead, the query would be:</p><pre><code>{
firstSearchResult {
... on Person {
name
}
... on Photo {
height
}
}
}
</code></pre><p><strong>Result Coercion</strong></p><p>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.</p><p><strong>Input Coercion</strong></p><p>Unions are never valid inputs.</p><section id="sec-Union-type-validation"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Union-type-validation">3.1.4.1</a></span>Union type validation</h5><p>Union types have the potential to be invalid if incorrectly defined.</p><ol><li>The member types of an Union type must all be Object base types; Scalar, Interface and Union types may not be member types of a Union. Similarly, wrapping types may not be member types of a Union.</li><li>A Union type must define one or more member types.</li></ol></section></section><section id="sec-Enums"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Enums">3.1.5</a></span>Enums</h4><p>GraphQL Enums are a variant on the Scalar type, which represents one of a finite set of possible values.</p><p>GraphQL Enums are not references for a numeric value, but are unique values in their own right. They serialize as a string: the name of the represented value.</p><p><strong>Result Coercion</strong></p><p>GraphQL servers must return one of the defined set of possible values. If a reasonable coercion is not possible they must raise a field error.</p><p><strong>Input Coercion</strong></p><p>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 query error.</p><p>Query 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.</p></section><section id="sec-Input-Objects"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Input-Objects">3.1.6</a></span>Input Objects</h4><p>Fields can define arguments that the client passes up with the query, to configure their behavior. These inputs can be Strings or Enums, but they sometimes need to be more complex than this.</p><p>The <code>Object</code> type defined above is inappropriate for re‐use here, because <code>Object</code>s can contain fields that express circular references or 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.</p><p>An <code>Input Object</code> 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.</p><p><strong>Result Coercion</strong></p><p>An input object is never a valid result.</p><p><strong>Input Coercion</strong></p><p>The input to an input object should be an unordered map, otherwise an error should be thrown. The result of the coercion is an unordered map, with an entry for each input field, whose key is the name of the input field. The value of an entry in the coerced map is the result of input coercing the value of the entry in the input with the same key; if the input does not have a corresponding entry, the value is the result of coercing null. The input coercion above should be performed according to the input coercion rules of the type declared by the input field.</p></section><section id="sec-Lists"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Lists">3.1.7</a></span>Lists</h4><p>A GraphQL list is a special collection type which declares the type of each item in the List (referred to as the <em>item type</em> 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>.</p><p><strong>Result Coercion</strong></p><p>GraphQL servers 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 they 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.</p><p><strong>Input Coercion</strong></p><p>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.</p><p>If the value passed as an input to a list type is <em>not</em> as list, it should be coerced as though the input was a list of size one, where the value passed is the only item in the list. This is to allow inputs that accept a “var args” to declare their input type as a list; if only one argument is passed (a common case), the client can just pass that value rather than constructing the list.</p></section><section id="sec-Non-Null"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Non-Null">3.1.8</a></span>Non-Null</h4><p>By default, all types in GraphQL are nullable; the <span class="spec-keyword">null</span> 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 <code>null</code> 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>.</p><p><strong>Result Coercion</strong></p><p>In all of the above result coercion, <span class="spec-keyword">null</span> 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 <span class="spec-keyword">null</span>, then the result of coercing the Non Null type is that result. If that result was <span class="spec-keyword">null</span>, then a field error must be raised.</p><p><strong>Input Coercion</strong></p><p>If the argument of a Non Null type is not provided, a query error must be raised.</p><p>If an argument of a Non Null type is provided with a literal value, it is coerced using the input coercion for the wrapped type.</p><p>If the argument of a Non Null is provided with a variable, a query error must be raised if the runtime provided value is not provided or is <span class="spec-keyword">null</span> in the provided representation (usually JSON). Otherwise, the coerced value is the result of using the input coercion for the wrapped type.</p><div class="spec-note">that <code>null</code> is not a value in GraphQL, so a query cannot look like:</div><pre class="spec-counter-example"><code>{
field(arg: null)
}
</code></pre><p>to indicate that the argument is <span class="spec-keyword">null</span>. Instead, an argument would be <span class="spec-keyword">null</span> only if it is omitted:</p><pre><code>{
field
}
</code></pre><p>Or if passed a variable of a nullable type that at runtime was not provided a value:</p><pre><code>query withNullableVariable($var: String) {
field(arg: $var)
}
</code></pre></section></section><section id="sec-Type-System.Directives"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Type-System.Directives">3.2</a></span>Directives</h3><p>A GraphQL schema includes a list of the directives the execution engine supports.</p><p>GraphQL implementations should provide the <code>@skip</code> and <code>@include</code> directives.</p><section id="sec--skip"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec--skip">3.2.1</a></span>@skip</h4><p>The <code>@skip</code> directive may be provided for fields or fragments, and allows for conditional exclusion during execution as described by the if argument.</p><p>In this example <code>experimentalField</code> will be queried only if the <code>$someTest</code> is provided a <code>false</code> value.</p><pre><code>query myQuery($someTest: Boolean) {
experimentalField @skip(if: $someTest)
}
</code></pre></section><section id="sec--include"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec--include">3.2.2</a></span>@include</h4><p>The <code>@include</code> directive may be provided for fields or fragments, and allows for conditional inclusion during execution as described by the if argument.</p><p>In this example <code>experimentalField</code> will be queried only if the <code>$someTest</code> is provided a <code>true</code> value.</p><pre><code>query myQuery($someTest: Boolean) {
experimentalField @include(if: $someTest)
}
</code></pre><p>In the case that both the <code>@skip</code> and <code>@include</code> directives are provided in the same context, the field or fragment <em>must</em> be queried only if the <code>@skip</code> condition is false <em>and</em> the <code>@include</code> condition is true. Stated conversely, the field/fragment must <em>not</em> be queried if either the <code>@skip</code> condition is true <em>or</em> the <code>@include</code> condition is false.</p></section></section><section id="sec-Starting-types"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Starting-types">3.3</a></span>Starting types</h3><p>A GraphQL schema includes types, indicating where query and mutation operations start. This provides the initial entry points into the type system. The query type must always be provided, and is an Object base type. The mutation type is optional; if it is null, that means the system does not support mutations. If it is provided, it must be an object base type.</p><p>The fields on the query type indicate what fields are available at the top level of a GraphQL query. For example, a basic GraphQL query like this one:</p><pre><code>query getMe {
me
}
</code></pre><p>Is valid when the type provided for the query starting type has a field named “me”. Similarly</p><pre><code>mutation setName {
setName(name: "Zuck") {
newName
}
}
</code></pre><p>Is valid when the type provided for the mutation starting type is not null, and has a field named “setName” with a string argument named “name”. </p></section></section><section id="sec-Introspection"><h2><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Introspection">4</a></span>Introspection</h2><p>A GraphQL server supports introspection over its schema. This schema is queried using GraphQL itself, creating a powerful platform for tool‐building.</p><p>Take an example query for a trivial app. In this case there is a User type with three fields: id, name, and birthday.</p><p>For example, given a server with the following type definition:</p><pre><code>type User {
id: String
name: String
birthday: Date
}
</code></pre><p>The query</p><pre><code>{
__type(name: "User") {
name
fields {
name
type {
name
}
}
}
}
</code></pre><p>would return</p><pre><code>{
<span class="hljs-string">"__type"</span>: {
<span class="hljs-string">"name"</span> : <span class="hljs-string">"User"</span>,
<span class="hljs-string">"fields"</span>: [
{
<span class="hljs-string">"name"</span>: <span class="hljs-string">"id"</span>,
<span class="hljs-string">"type"</span>: { <span class="hljs-string">"name"</span>: <span class="hljs-string">"String"</span> }
},
{
<span class="hljs-string">"name"</span>: <span class="hljs-string">"name"</span>,
<span class="hljs-string">"type"</span>: { <span class="hljs-string">"name"</span>: <span class="hljs-string">"String"</span> }
},
{
<span class="hljs-string">"name"</span>: <span class="hljs-string">"birthday"</span>,
<span class="hljs-string">"type"</span>: { <span class="hljs-string">"name"</span>: <span class="hljs-string">"Date"</span> }
},
]
}
}
</code></pre><section id="sec-General-Principles"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-General-Principles">4.1</a></span>General Principles</h3><section id="sec-Naming-conventions"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Naming-conventions">4.1.1</a></span>Naming conventions</h4><p>Types and fields required by the GraphQL introspection system that are used in the same context as user‐defined type and fields are prefixed with two underscores. This in order to avoid naming collisions with user‐defined GraphQL types. Conversely, GraphQL type system authors must not define any types, fields, arguments, or any other type system artifact with two leading underscores.</p></section><section id="sec-Documentation"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Documentation">4.1.2</a></span>Documentation</h4><p>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 server may return the <code>description</code> field using Markdown syntax. Therefore it is recommended that any tool that displays description use a Markdown renderer.</p></section><section id="sec-Deprecation"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Deprecation">4.1.3</a></span>Deprecation</h4><p>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>).</p><p>Tools built using GraphQL introspection should respect deprecation by discouraging deprecated use through information hiding or developer‐facing warnings.</p></section><section id="sec-Type-Name-Introspection"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Type-Name-Introspection">4.1.4</a></span>Type Name Introspection</h4><p>GraphQL supports type name introspection at any point within a query by the meta field <code>__typename: String!</code> when querying against any Object, Interface, or Union. It returns the name of the object type currently being queried.</p><p>This is most often used when querying against Interface or Union types to identify which actual type of the possible types has been returned.</p><p>This field is implicit and does not appear in the fields list in any defined type.</p></section></section><section id="sec-Schema-Introspection"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Schema-Introspection">4.2</a></span>Schema Introspection</h3><p>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.</p><pre><code>__schema : __Schema!
__type(name: String!) : __Type
</code></pre><p>These fields are implicit and do not appear in the fields list in the root type of the query operation.</p><p>The schema of the GraphQL schema introspection system:</p><pre><code>type __Schema {
types: [__Type!]!
queryType: __Type!
mutationType: __Type
directives: [__Directive!]!
}
type __Type {
kind: __TypeKind!
name: String
description: String
# OBJECT and INTERFACE only
fields(includeDeprecated: Boolean = false): [__Field!]
# OBJECT only
interfaces: [__Type!]
# INTERFACE and UNION only
possibleTypes: [__Type!]
# ENUM only
enumValues(includeDeprecated: Boolean = false): [__EnumValue!]
# INPUT_OBJECT only
inputFields: [__InputValue!]
# NON_NULL and LIST only
ofType: __Type
}
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
}
enum __TypeKind {
SCALAR
OBJECT
INTERFACE
UNION
ENUM
INPUT_OBJECT
LIST
NON_NULL
}
type __Directive {
name: String!
description: String
args: [__InputValue!]!
onOperation: Boolean!
onFragment: Boolean!
onField: Boolean!
}
</code></pre><section id="sec-The-__Type-Type"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-The-__Type-Type">4.2.1</a></span>The "__Type" Type</h4><p><code>__Type</code> is at the core of the type introspection system. It represents scalars, interfaces, object types, unions, enums in the system.</p><p><code>__Type</code> also represents type modifiers, which are used to modify a type that it refers to (<code>ofType: __Type</code>). This is how we represent lists, non‐nullable types, and the combinations thereof.</p></section><section id="sec-Type-Kinds"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Type-Kinds">4.2.2</a></span>Type Kinds</h4><p>There are several different kinds of type. In each kind, different fields are actually valid. These kinds are listed in the <code>__TypeKind</code> enumeration.</p><section id="sec-Scalar"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Scalar">4.2.2.1</a></span>Scalar</h5><p>Represents scalar types such as Int, String, and Boolean. Scalars cannot have fields.</p><p>A GraphQL type designer should describe the data format and scalar coercion rules in the description field of any scalar.</p><p>Fields</p><ul><li><code>kind</code> must return <code>__TypeKind.SCALAR</code>.</li><li><code>name</code> must return a String.</li><li><code>description</code> may return a String or <span class="spec-keyword">null</span>.</li><li>All other fields must return <span class="spec-keyword">null</span>.</li></ul></section><section id="sec-Object"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Object">4.2.2.2</a></span>Object</h5><p>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.</p><p>Fields</p><ul><li><code>kind</code> must return <code>__TypeKind.OBJECT</code>.</li><li><code>name</code> must return a String.</li><li><code>description</code> may return a String or <span class="spec-keyword">null</span>.</li><li><code>fields</code>: The set of fields query‐able on this type.<ul><li>Accepts the argument <code>includeDeprecated</code> which defaults to <span class="spec-keyword">false</span>. If <span class="spec-keyword">true</span>, deprecated fields are also returned.</li></ul></li><li><code>interfaces</code>: The set of interfaces that an object implements.</li><li>All other fields must return <span class="spec-keyword">null</span>.</li></ul></section><section id="sec-Union"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Union">4.2.2.3</a></span>Union</h5><p>Unions are an abstract types 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.</p><p>Fields</p><ul><li><code>kind</code> must return <code>__TypeKind.UNION</code>.</li><li><code>name</code> must return a String.</li><li><code>description</code> may return a String or <span class="spec-keyword">null</span>.</li><li><code>possibleTypes</code> returns the list of types that can be represented within this union. They must be object types.</li><li>All other fields must return <span class="spec-keyword">null</span>.</li></ul></section><section id="sec-Interface"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Interface">4.2.2.4</a></span>Interface</h5><p>Interfaces is 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>.</p><p>Fields</p><ul><li><code>kind</code> must return <code>__TypeKind.INTERFACE</code>.</li><li><code>name</code> must return a String.</li><li><code>description</code> may return a String or <span class="spec-keyword">null</span>.</li><li><code>fields</code>: The set of fields required by this interface.<ul><li>Accepts the argument <code>includeDeprecated</code> which defaults to <span class="spec-keyword">false</span>. If <span class="spec-keyword">true</span>, deprecated fields are also returned.</li></ul></li><li><code>possibleTypes</code> returns the list of types that implement this interface. They must be object types.</li><li>All other fields must return <span class="spec-keyword">null</span>.</li></ul></section><section id="sec-Enum"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Enum">4.2.2.5</a></span>Enum</h5><p>Enums are special scalars that can only have a defined set of values.</p><p>Fields</p><ul><li><code>kind</code> must return <code>__TypeKind.ENUM</code>.</li><li><code>name</code> must return a String.</li><li><code>description</code> may return a String or <span class="spec-keyword">null</span>.</li><li><code>enumValues</code>: The list of <code>EnumValue</code>. There must be at least one and they must have unique names.<ul><li>Accepts the argument <code>includeDeprecated</code> which defaults to <span class="spec-keyword">false</span>. If <span class="spec-keyword">true</span>, deprecated enum values are also returned.</li></ul></li><li>All other fields must return <span class="spec-keyword">null</span>.</li></ul></section><section id="sec-Input-Object"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Input-Object">4.2.2.6</a></span>Input Object</h5><p>Input objects are composite types used as inputs into queries defined as a list of named input values.</p><p>For example the input object <code>Point</code> could be defined as:</p><pre><code>type Point {
x: Int
y: Int
}
</code></pre><p>Fields</p><ul><li><code>kind</code> must return <code>__TypeKind.INPUT_OBJECT</code>.</li><li><code>name</code> must return a String.</li><li><code>description</code> may return a String or <span class="spec-keyword">null</span>.</li><li><code>inputFields</code>: a list of <code>InputValue</code>.</li><li>All other fields must return <span class="spec-keyword">null</span>.</li></ul></section><section id="sec-List"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-List">4.2.2.7</a></span>List</h5><p>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.</p><p>Fields</p><ul><li><code>kind</code> must return <code>__TypeKind.LIST</code>.</li><li><code>ofType</code>: Any type.</li><li>All other fields must return <span class="spec-keyword">null</span>.</li></ul></section><section id="sec-Non-null"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Non-null">4.2.2.8</a></span>Non-null</h5><p>GraphQL types are nullable. The value <span class="spec-keyword">null</span> is a valid response for field type.</p><p>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 <span class="spec-keyword">null</span> as a response, and indicate required inputs for arguments and input object fields.</p><ul><li><code>kind</code> must return <code>__TypeKind.NON_NULL</code>.</li><li><code>ofType</code>: Any type except Non‐null.</li><li>All other fields must return <span class="spec-keyword">null</span>.</li></ul></section><section id="sec-Combining-List-and-Non-Null"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Combining-List-and-Non-Null">4.2.2.9</a></span>Combining List and Non-Null</h5><p>List and Non‐Null can compose, representing more complex types.</p><p>If the modified type of a List is Non‐Null, then that List may not contain any <span class="spec-keyword">null</span> items.</p><p>If the modified type of a Non‐Null is List, then <span class="spec-keyword">null</span> is not accepted, however an empty list is accepted.</p><p>If the modified type of a List is a List, then each item in the first List is another List of the second List’s type.</p><p>A Non‐Null type cannot modify another Non‐Null type.</p></section></section><section id="sec-The-__Field-Type"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-The-__Field-Type">4.2.3</a></span>The __Field Type</h4><p>The <code>__Field</code> type represents each field in an Object or Interface type.</p><p>Fields</p><ul><li><code>name</code> must return a String</li><li><code>description</code> may return a String or <span class="spec-keyword">null</span></li><li><code>args</code> returns a List of <code>__InputValue</code> representing the arguments this field accepts.</li><li><code>type</code> must return a <code>__Type</code> that represents the type of value returned by this field.</li><li><code>isDeprecated</code> returns <span class="spec-keyword">true</span> if this field should no longer be used, otherwise <span class="spec-keyword">false</span>.</li><li><code>deprecationReason</code> optionally provides a reason why this field is deprecated.</li></ul></section><section id="sec-The-__InputValue-Type"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-The-__InputValue-Type">4.2.4</a></span>The __InputValue Type</h4><p>The <code>__InputValue</code> type represents field and directive arguments as well as the <code>inputFields</code> of an input object.</p><p>Fields</p><ul><li><code>name</code> must return a String</li><li><code>description</code> may return a String or <span class="spec-keyword">null</span></li><li><code>type</code> must return a <code>__Type</code> that represents the type this input value expects.</li><li><code>defaultValue</code> may return a String encoding (using the GraphQL language) 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 <span class="spec-keyword">null</span>. </li></ul></section></section></section><section id="sec-Validation"><h2><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Validation">5</a></span>Validation</h2><p>GraphQL does not just verify if a request is syntactically correct.</p><p>Prior to execution, it can also verify that a request is valid within the context of a given GraphQL schema. Validation is primarily targeted at development‐time tooling. Any client‐side tooling should return errors and not allow the formulation of queries known to violate the type system at a given point in time.</p><p>Total request validation on the server‐side during execution is optional. As schemas and systems change over time existing clients may end up emitting queries that are no longer valid given the current type system. Servers (as described in the Execution section of this spec) attempt to satisfy as much as the request as possible and continue to execute in the presence of type system errors rather than cease execution completely.</p><p>For this section of this schema, we will assume the following type system in order to demonstrate examples:</p><pre><code>enum DogCommand { SIT, DOWN, HEEL }
type Dog implements Pet {
name: String!
nickname: String
barkVolume: Int
doesKnowCommand(dogCommand: DogCommand!) : Boolean!
isHousetrained(atOtherHomes: Boolean): Boolean!
}
interface Sentient {
name: String!
}
interface Pet {
name: String!
}
type Alien implements Sentient {
name: String!
homePlanet: String
}
type Human implements Sentient {
name: String!
}
type Cat implements Pet {
name: String!
nickname: String
meowVolume: Int
}
union CatOrDog = Cat | Dog
union DogOrHuman = Dog | Human
union HumanOrAlien = Human | Alien
</code></pre><section id="sec-Validation.Operations"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Validation.Operations">5.1</a></span>Operations</h3><section id="sec-Named-Operation-Definitions"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Named-Operation-Definitions">5.1.1</a></span>Named Operation Definitions</h4><section id="sec-Operation-Name-Uniqueness"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Operation-Name-Uniqueness">5.1.1.1</a></span>Operation Name Uniqueness</h5><p><strong> Formal Specification </strong></p><ul><li>For each operation definition <var>operation</var> in the document</li><li>Let <var>operationName</var> be the name of <var>operation</var>.</li><li>If <var>operationName</var> exists<ul><li>Let <var>operations</var> be all operation definitions in the document named <var>operationName</var>.</li><li><var>operations</var> must be a set of one.</li></ul></li></ul><p><strong> Explanatory Text </strong></p><p>Each named operation definitions must be unique within a document when referred to by its name.</p><p>For example the following document is valid:</p><pre><code>query getDogName {
dog {
name
}
}
query getOwnerName {
dog {
owner {
name
}
}
}
</code></pre><p>While this document is invalid:</p><pre class="spec-counter-example"><code>query getName {
dog {
name
}
}
query getName {
dog {
owner {
name
}
}
}
</code></pre></section></section><section id="sec-Anonymous-Operation-Definitions"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Anonymous-Operation-Definitions">5.1.2</a></span>Anonymous Operation Definitions</h4><section id="sec-Lone-Anonymous-Operation"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Lone-Anonymous-Operation">5.1.2.1</a></span>Lone Anonymous Operation</h5><p><strong> Formal Specification </strong></p><ul><li>Let <var>operations</var> be all anonymous operation definitions in the document.</li><li><var>operations</var> must be a set of one.</li></ul><p><strong> Explanatory Text </strong></p><p>GraphQL allows a short‐hand form for defining query operations when only that one operation exists in the document.</p><p>For example the following document is valid:</p><pre><code>{
dog {
name
}
}
</code></pre><p>While this document is invalid:</p><pre class="spec-counter-example"><code>{
dog {
name
}
}
query getName {
dog {
owner {
name
}
}
}
</code></pre></section></section></section><section id="sec-Validation.Fields"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Validation.Fields">5.2</a></span>Fields</h3><section id="sec-Field-Selections-on-Objects-Interfaces-and-Unions-Types"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Field-Selections-on-Objects-Interfaces-and-Unions-Types">5.2.1</a></span>Field Selections on Objects, Interfaces, and Unions Types</h4><p><strong> Formal Specification </strong></p><ul><li>For each <var>selection</var> in the document.</li><li>Let <var>fieldName</var> be the target field of <var>selection</var></li><li><var>fieldName</var> must be defined on type in scope</li></ul><p><strong> Explanatory Text </strong></p><p>The target field of a field selection must defined on the scoped type of the selection set. There are no limitations on alias names.</p><p>For example the following fragment would not pass validation:</p><pre class="spec-counter-example"><code>fragment fieldNotDefined on Dog {
meowVolume
}
fragment aliasedLyingFieldTargetNotDefined on Dog {
barkVolume: kawVolume
}
</code></pre><p>For interfaces, direct field selection can only be done on fields. Fields of concrete implementors is not relevant to the validity of the given interface‐typed selection set.</p><p>For example, the following is valid:</p><pre><code>fragment interfaceFieldSelection on Pet {
name
}
</code></pre><p>and the following is invalid:</p><pre class="spec-counter-example"><code>fragment definedOnImplementorsButNotInterface on Pet {
nickname
}
</code></pre><p>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>__typename</var>. Fields from a union‐typed selection set must only be queried indirectly via a fragment.</p><p>For example the following is valid:</p><pre><code>fragment inDirectFieldSelectionOnUnion on CatOrDog {
__typename
... on Pet {
name
}
... on Dog {
barkVolume
}
}
</code></pre><p>But the following is invalid:</p><pre class="spec-counter-example"><code>fragment directFieldSelectionOnUnion on CatOrDog {
name
barkVolume
}
</code></pre></section><section id="sec-Field-Selection-Merging"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Field-Selection-Merging">5.2.2</a></span>Field Selection Merging</h4><p><strong> Formal Specification </strong></p><ul><li>Let <var>set</var> be any selection set defined in the GraphQL document</li><li>Let <var>fieldsForName</var> be the set of selections with a given response name in <var>set</var> including visiting fragments and inline fragments.</li><li>Given each pair of members <var>fieldA</var> and <var>fieldB</var> in <var>fieldsForName</var>:<ul><li>If the parent types of <var>fieldA</var> and <var>fieldB</var> are equal or if either is not an Object Type:<ul><li><var>fieldA</var> and <var>fieldB</var> must have identical field names.</li><li><var>fieldA</var> and <var>fieldB</var> must have identical return type.</li><li><var>fieldA</var> and <var>fieldB</var> must have identical sets of arguments.</li></ul></li></ul></li></ul><p><strong> Explanatory Text </strong></p><p>If multiple fields selections with the same response names are encountered during execution, the result should be unambiguous. Therefore any two field selections which might both be encountered for the same object are only valid if they are equivalent.</p><p>For simple hand‐written GraphQL, this rule is obviously a clear developer error, however nested fragments can make this difficult to detect manually.</p><p>The following selections correctly merge:</p><pre><code>fragment mergeIdenticalFields on Dog {
name
name
}
fragment mergeIdenticalAliasesAndFields on Dog {
otherName: name
otherName: name
}
</code></pre><p>The following is not able to merge:</p><pre class="spec-counter-example"><code>fragment conflictingBecauseAlias on Dog {
name: nickname
name
}
</code></pre><p>Identical arguments are also merged if they have identical arguments. Both values and variables can be correctly merged.</p><p>For example the following correctly merge:</p><pre><code>fragment mergeIdenticalFieldsWithIdenticalArgs on Dog {
doesKnowCommand(dogCommand: SIT)
doesKnowCommand(dogCommand: SIT)
}
fragment mergeIdenticalFieldsWithIdenticalValues on Dog {
doesKnowCommand(dogCommand: $dogCommand)
doesKnowCommand(dogCommand: $dogCommand)
}
</code></pre><p>The following do not correctly merge:</p><pre class="spec-counter-example"><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><p>The following would not merge together, however both cannot be encountered against the same object:</p><pre><code>fragment safeDifferingFields on Pet {
... on Dog {
name: nickname
}
... on Cat {
name
}
}
fragment safeDifferingArgs on Pet {
... on Dog {
doesKnowCommand(dogCommand: SIT)
}
... on Cat {
doesKnowCommand(catCommand: JUMP)
}
}
</code></pre></section><section id="sec-Leaf-Field-Selections"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Leaf-Field-Selections">5.2.3</a></span>Leaf Field Selections</h4><p><strong> Formal Specification </strong></p><ul><li>For each <var>selection</var> in the document</li><li>Let <var>selectionType</var> be the result type of <var>selection</var></li><li>If <var>selectionType</var> is a scalar:<ul><li>The subselection set of that selection must be empty</li></ul></li><li>If <var>selectionType</var> is an interface, union, or object<ul><li>The subselection set of that selection must NOT BE empty</li></ul></li></ul><p><strong> Explanatory Text </strong></p><p>Field selections on scalars are never allowed: scalars are the leaf nodes of any GraphQL query.</p><p>The following is valid.</p><pre><code>fragment scalarSelection on Dog {
barkVolume
}
</code></pre><p>The following is invalid.</p><pre class="spec-counter-example"><code>fragment scalarSelectionsNotAllowedOnBoolean on Dog {
barkVolume {
sinceWhen
}
}
</code></pre><p>Conversely the leaf field selections of GraphQL queries must be scalars. Leaf selections on objects, interfaces, and unions without subfields are disallowed.</p><p>Let’s assume the following query root type of the schema:</p><pre><code>type QueryRoot {
human: Human
pet: Pet
catOrDog: CatOrDog
}
</code></pre><p>The following examples are invalid</p><pre class="spec-counter-example"><code>query directQueryOnObjectWithoutSubFields {
human
}
query directQueryOnInterfaceWithoutSubFields {
pet
}
query directQueryOnUnionWithoutSubFields {
catOrDog
}
</code></pre></section></section><section id="sec-Validation.Arguments"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Validation.Arguments">5.3</a></span>Arguments</h3><p>Arguments are provided to both fields and directives. The following validation rules apply in both cases.</p><section id="sec-Argument-Names"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Argument-Names">5.3.1</a></span>Argument Names</h4><p><strong> Formal Specification </strong></p><ul><li>For each <var>argument</var> in the document</li><li>Let <var>argumentName</var> be the Name of <var>argument</var>.</li><li>Let <var>argumentDefinition</var> be the argument definition provided by the parent field or definition named <var>argumentName</var>.</li><li><var>argumentDefinition</var> must exist.</li></ul><p><strong> Explanatory Text </strong></p><p>Every argument provided to a field or directive must be defined in the set of possible arguments of that field or directive.</p><p>For example the following are valid:</p><pre><code>fragment argOnRequiredArg on Dog {
doesKnowCommand(dogCommand: SIT)
}
fragment argOnOptional on Dog {
isHousetrained(atOtherHomes: true) @include(if: true)
}
</code></pre><p>the following is invalid since <code>command</code> is not defined on <code>DogCommand</code>.</p><pre class="spec-counter-example"><code>fragment invalidArgName on Dog {
doesKnowCommand(command: CLEAN_UP_HOUSE)
}
</code></pre><p>and this is also invalid as <code>unless</code> is not defined on <code>@include</code>.</p><pre class="spec-counter-example"><code>fragment invalidArgName on Dog {
isHousetrained(atOtherHomes: true) @include(unless: false)
}
</code></pre><p>In order to explore more complicated argument examples, let’s add the following to our type system:</p><pre><code>type Arguments {
multipleReqs(x: Int!, y: Int!)
booleanArgField(booleanArg: Boolean)
floatArgField(floatArg: Float)
intArgField(intArg: Int)
nonNullBooleanArgField(nonNullBooleanArg: Boolean!)
}
</code></pre><p>Order does not matter in arguments. Therefore both the following example are valid.</p><pre><code>fragment multipleArgs on Arguments {
multipleReqs(x: 1, y: 2)
}
fragment multipleArgsReverseOrder on Arguments {
multipleReqs(y: 1, x: 2)
}
</code></pre></section><section id="sec-Argument-Uniqueness"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Argument-Uniqueness">5.3.2</a></span>Argument Uniqueness</h4><p>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.</p><p><strong> Formal Specification </strong></p><ul><li>For each <var>argument</var> in the Document.</li><li>Let <var>argumentName</var> be the Name of <var>argument</var>.</li><li>Let <var>arguments</var> be all Arguments named <var>argumentName</var> in the Argument Set which contains <var>argument</var>.</li><li><var>arguments</var> must be the set containing only <var>argument</var>.</li></ul></section><section id="sec-Argument-Values-Type-Correctness"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Argument-Values-Type-Correctness">5.3.3</a></span>Argument Values Type Correctness</h4><section id="sec-Compatible-Values"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Compatible-Values">5.3.3.1</a></span>Compatible Values</h5><p><strong> Formal Specification </strong></p><ul><li>For each <var>argument</var> in the document</li><li>Let <var>value</var> be the Value of <var>argument</var></li><li>If <var>value</var> is not a Variable<ul><li>Let <var>argumentName</var> be the Name of <var>argument</var>.</li><li>Let <var>argumentDefinition</var> be the argument definition provided by the parent field or definition named <var>argumentName</var>.</li><li>Let <var>type</var> be the type expected by <var>argumentDefinition</var>.</li><li>The type of <var>literalArgument</var> must be coercible to <var>type</var>.</li></ul></li></ul><p><strong> Explanatory Text </strong></p><p>Literal values must be compatible with the type defined by the argument they are being provided to, as per the coercion rules defined in the Type System chapter.</p><p>For example, an Int can be coerced into a Float.</p><pre><code>fragment goodBooleanArg on Arguments {
booleanArgField(booleanArg: true)
}
fragment coercedIntIntoFloatArg on Arguments {
floatArgField(floatArg: 1)
}
</code></pre><p>An incoercible conversion, is string to int. Therefore, the following example is invalid.</p><pre class="spec-counter-example"><code>fragment stringIntoInt on Arguments {
intArgField(intArg: "3")
}
</code></pre></section><section id="sec-Required-Arguments"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Required-Arguments">5.3.3.2</a></span>Required Arguments</h5><ul><li>For each Field or Directive in the document.</li><li>Let <var>arguments</var> be the arguments provided by the Field or Directive.</li><li>Let <var>argumentDefinitions</var> be the set of argument definitions of that Field or Directive.</li><li>For each <var>definition</var> in <var>argumentDefinitions</var><ul><li>Let <var>type</var> be the expected type of <var>definition</var></li><li>If <var>type</var> is Non‐Null<ul><li>Let <var>argumentName</var> be the name of <var>definition</var></li><li>Let <var>argument</var> be the argument in <var>arguments</var> named <var>argumentName</var></li><li><var>argument</var> must exist.</li></ul></li></ul></li></ul><p><strong> Explanatory Text </strong></p><p>Arguments can be required. Arguments are required if the type of the argument is non‐null. If it is not non‐null, the argument is optional.</p><p>For example the following are valid:</p><pre><code>fragment goodBooleanArg on Arguments {
booleanArgField(booleanArg: true)
}
fragment goodNonNullArg on Arguments {
nonNullBooleanArgField(nonNullBooleanArg: true)
}
</code></pre><p>The argument can be omitted from a field with a nullable argument.</p><p>Therefore the following query is valid:</p><pre><code>fragment goodBooleanArgDefault on Arguments {
booleanArgField
}
</code></pre><p>but this is not valid on a non‐null argument.</p><pre class="spec-counter-example"><code>fragment missingRequiredArg on Arguments {
notNullBooleanArgField
}
</code></pre></section></section></section><section id="sec-Validation.Fragments"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Validation.Fragments">5.4</a></span>Fragments</h3><section id="sec-Fragment-Declarations"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Fragment-Declarations">5.4.1</a></span>Fragment Declarations</h4><section id="sec-Fragment-Name-Uniqueness"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Fragment-Name-Uniqueness">5.4.1.1</a></span>Fragment Name Uniqueness</h5><p><strong> Formal Specification </strong></p><ul><li>For each fragment definition <var>fragment</var> in the document</li><li>Let <var>fragmentName</var> be the name of <var>fragment</var>.</li><li>Let <var>fragments</var> be all fragment definitions in the document named <var>fragmentName</var>.</li><li><var>fragments</var> must be a set of one.</li></ul><p><strong> Explanatory Text </strong></p><p>Fragment definitions are referenced in fragment spreads by name. To avoid ambiguity, each fragment’s name must be unique within a document.</p><p>Inline fragments are not considered fragment definitions, and unaffected by this validation rule.</p><p>For example the following document is valid:</p><pre><code>{
...fragmentOne
...fragmentTwo
}
fragment fragmentOne on Dog {
name
}
fragment fragmentTwo on Dog {
owner {
name
}
}
</code></pre><p>While this document is invalid:</p><pre class="spec-counter-example"><code>{
...fragmentOne
}
fragment fragmentOne on Dog {
name
}
fragment fragmentOne on Dog {
owner {
name
}
}
</code></pre></section><section id="sec-Fragment-Spread-Type-Existence"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Fragment-Spread-Type-Existence">5.4.1.2</a></span>Fragment Spread Type Existence</h5><p><strong> Formal Specification </strong></p><ul><li>For each named spread <var>namedSpread</var> in the document</li><li>Let <var>fragment</var> be the target of <var>namedSpread</var></li><li>The target type of <var>fragment</var> must be defined in the schema</li></ul><p><strong> Explanatory Text </strong></p><p>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 query does not validate.</p><p>For example the following fragments are valid:</p><pre><code>fragment correctType on Dog {
name
}
fragment inlineFragment on Dog {
... on Dog {
name
}
}
fragment inlineFragment on Dog {
... @include(if: true) {
name
}
}
</code></pre><p>and the following do not validate:</p><pre class="spec-counter-example"><code>fragment notOnExistingType on NotInSchema {
name
}
fragment inlineNotExistingType on Dog {
... on NotInSchema {
name
}
}
</code></pre></section><section id="sec-Fragments-On-Composite-Types"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Fragments-On-Composite-Types">5.4.1.3</a></span>Fragments On Composite Types</h5><p><strong> Formal Specification </strong></p><ul><li>For each <var>fragment</var> defined in the document.</li><li>The target type of fragment must have kind <span class="spec-nt">UNION</span>, <span class="spec-nt">INTERFACE</span>, or <span class="spec-nt">OBJECT</span>.</li></ul><p><strong> Explanatory Text </strong></p><p>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.</p><p>The following fragment declarations are valid:</p><pre><code>fragment fragOnObject on Dog {
name
}
fragment fragOnInterface on Pet {
name
}
fragment fragOnUnion on CatOrDog {
... on Dog {
name
}
}
</code></pre><p>and the following are invalid:</p><pre class="spec-counter-example"><code>fragment fragOnScalar on Int {
something
}
fragment inlineFragOnScalar on Dog {
... on Boolean {
somethingElse
}
}
</code></pre></section><section id="sec-Fragments-Must-Be-Used"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Fragments-Must-Be-Used">5.4.1.4</a></span>Fragments Must Be Used</h5><p><strong> Formal Specification </strong></p><ul><li>For each <var>fragment</var> defined in the document.</li><li><var>fragment</var> must be the target of at least one spread in the document</li></ul><p><strong> Explanatory Text </strong></p><p>Defined fragments must be used within a query document.</p><p>For example the following is an invalid query document:</p><pre class="spec-counter-example"><code>fragment nameFragment on Dog { # unused
name
}
{
dog {
name
}
}
</code></pre></section></section><section id="sec-Fragment-Spreads"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Fragment-Spreads">5.4.2</a></span>Fragment Spreads</h4><p>Field selection is also determined by spreading fragments into one another. The selection set of the target fragment is unioned with the selection set at the level at which the target fragment is referenced.</p><section id="sec-Fragment-spread-target-defined"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Fragment-spread-target-defined">5.4.2.1</a></span>Fragment spread target defined</h5><p><strong> Formal Specification </strong></p><ul><li>For every <var>namedSpread</var> in the document.</li><li>Let <var>fragment</var> be the target of <var>namedSpread</var></li><li><var>fragment</var> must be defined in the document</li></ul><p><strong> Explanatory Text </strong></p><p>Named fragment spreads must refer to fragments defined within the document. If the target of a spread is not defined, this is an error:</p><pre class="spec-counter-example"><code>{
dog {
...undefinedFragment
}
}
</code></pre></section><section id="sec-Fragment-spreads-must-not-form-cycles"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Fragment-spreads-must-not-form-cycles">5.4.2.2</a></span>Fragment spreads must not form cycles</h5><p><strong> Formal Specification </strong></p><ul><li>For each <var>fragmentDefinition</var> in the document</li><li>Let <var>visited</var> be the empty set.</li><li><span class="spec-call">DetectCycles(<var>fragmentDefinition</var>, <var>visited</var>)</span></li></ul><p><span class="spec-call">DetectCycles(<var>fragmentDefinition</var>, <var>visited</var>)</span> :</p><ul><li>Let <var>spreads</var> be all fragment spread descendants of <var>fragmentDefinition</var></li><li>For each <var>spread</var> in <var>spreads</var><ul><li><var>visited</var> must not contain <var>spread</var></li><li>Let <var>nextVisited</var> be the set including <var>spread</var> and members of <var>visited</var></li><li>Let <var>nextFragmentDefinition</var> be the target of <var>spread</var></li><li><span class="spec-call">DetectCycles(<var>nextFragmentDefinition</var>, <var>nextVisited</var>)</span></li></ul></li></ul><p><strong> Explanatory Text </strong></p><p>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.</p><p>This invalidates fragments that would result in an infinite spread:</p><pre class="spec-counter-example"><code>{
dog {
...nameFragment
}
}
fragment nameFragment on Dog {
name
...barkVolumeFragment
}
fragment barkVolumeFragment on Dog {
barkVolume
...nameFragment
}
</code></pre><p>If the above fragments were inlined, this would result in the infinitely large:</p><pre class="spec-counter-example"><code>{
dog {
name
barkVolume
name
barkVolume
name
barkVolume
name
# forever...
}
}
</code></pre><p>This also invalidates fragments that would result in an infinite recursion when executed against cyclic data:</p><pre class="spec-counter-example"><code>{
dog {
...dogFragment
}
}
fragment dogFragment on Dog {
name
owner {
...ownerFragment
}
}
fragment ownerFragment on Dog {
name
pets {
...dogFragment
}
}
</code></pre></section><section id="sec-Fragment-spread-is-possible"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Fragment-spread-is-possible">5.4.2.3</a></span>Fragment spread is possible</h5><p><strong> Formal Specification </strong></p><ul><li>For each <var>spread</var> (named or inline) in defined in the document.</li><li>Let <var>fragment</var> be the target of <var>spread</var></li><li>Let <var>fragmentType</var> be the type condition of <var>fragment</var></li><li>Let <var>parentType</var> be the type of the selection set containing <var>spread</var></li><li>Let <var>applicableTypes</var> be the intersection of <span class="spec-call"><a href="https://facebook.github.io/graphql/#GetPossibleTypes()">GetPossibleTypes</a>(<var>fragmentType</var>)</span> and <span class="spec-call"><a href="https://facebook.github.io/graphql/#GetPossibleTypes()">GetPossibleTypes</a>(<var>parentType</var>)</span></li><li><var>applicableTypes</var> must not be empty.</li></ul><div class="spec-algo" id="GetPossibleTypes()"><span class="spec-call"><a href="https://facebook.github.io/graphql/#GetPossibleTypes()">GetPossibleTypes</a>(<var>type</var>)</span><ol><li>If <var>type</var> is an object type, return a set containing <var>type</var></li><li>If <var>type</var> is an interface type, return the set of types implementing <var>type</var></li><li>If <var>type</var> is a union type, return the set of possible types of <var>type</var></li></ol></div><p><strong> Explanatory Text </strong></p><p>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.</p><section id="sec-Object-Spreads-In-Object-Scope"><h6><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Object-Spreads-In-Object-Scope">5.4.2.3.1</a></span>Object Spreads In Object Scope</h6><p>In the scope of a object type, the only valid object type fragment spread is one that applies to the same type that is in scope.</p><p>For example</p><pre><code>fragment dogFragment on Dog {
... on Dog {
barkVolume
}
}
</code></pre><p>and the following is invalid</p><pre class="spec-counter-example"><code>fragment catInDogFragmentInvalid on Dog {
... on Cat {
meowVolume
}
}
</code></pre></section><section id="sec-Abstract-Spreads-in-Object-Scope"><h6><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Abstract-Spreads-in-Object-Scope">5.4.2.3.2</a></span>Abstract Spreads in Object Scope</h6><p>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.</p><p>For example</p><pre><code>fragment petNameFragment on Pet {
name
}
fragment interfaceWithinObjectFragment on Dog {
...petNameFragment
}
</code></pre><p>is valid because <span class="spec-nt">Dog</span> implements Pet.</p><p>Likewise</p><pre><code>fragment catOrDogNameFragment on CatOrDog {
... on Cat {
meowVolume
}
}
fragment unionWithObjectFragment on Dog {
...CatOrDogFragment
}
</code></pre><p>is valid because <span class="spec-nt">Dog</span> is a member of the <span class="spec-nt">CatOrDog</span> union. It is worth noting that if one inspected the contents of the <span class="spec-nt">CatOrDogNameFragment</span> you could note that the 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.</p></section><section id="sec-Object-Spreads-In-Abstract-Scope"><h6><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Object-Spreads-In-Abstract-Scope">5.4.2.3.3</a></span>Object Spreads In Abstract Scope</h6><p>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 the that interface or union.</p><p>For example, the following fragments are valid:</p><pre><code>fragment petFragment on Pet {
name
... on Dog {
barkVolume
}
}
fragment catOrDogFragment on CatOrDog {
... on Cat {
meowVolume
}
}
</code></pre><p><var>petFragment</var> is valid because <span class="spec-nt">Dog</span> implements the interface <span class="spec-nt">Pet</span>. <var>catOrDogFragment</var> is valid because <span class="spec-nt">Cat</span> is a member of the <span class="spec-nt">CatOrDog</span> union.</p><p>By contrast the following fragments are invalid:</p><pre class="spec-counter-example"><code>fragment sentientFragment on Sentient {
... on Dog {
barkVolume
}
}
fragment humanOrAlienFragment on HumanOrAlien {
... on Cat {
meowVolume
}
}
</code></pre><p><span class="spec-nt">Dog</span> does not implement the interface <span class="spec-nt">Sentient</span> and therefore <var>sentientFragment</var> can never return meaningful results. Therefore the fragment is invalid. Likewise <span class="spec-nt">Cat</span> is not a member of the union <span class="spec-nt">HumanOrAlien</span>, and it can also never return meaningful results, making it invalid.</p></section><section id="sec-Abstract-Spreads-in-Abstract-Scope"><h6><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Abstract-Spreads-in-Abstract-Scope">5.4.2.3.4</a></span>Abstract Spreads in Abstract Scope</h6><p>Union or interfaces fragments can be used within each other. As long as there exists at least <em>one</em> object type that exists in the intersection of the possible types of the scope and the spread, the spread is considered valid.</p><p>So for example</p><pre><code>fragment unionWithInterface on Pet {
...dogOrHumanFragment
}
fragment dogOrHumanFragment on DogOrHuman {
... on Dog {
barkVolume
}
}
</code></pre><p>is consider valid because <span class="spec-nt">Dog</span> implements interface <span class="spec-nt">Pet</span> and is a member of <span class="spec-nt">DogOrHuman</span>.</p><p>However</p><pre class="spec-counter-example"><code>fragment nonIntersectingInterfaces on Pet {
...sentientFragment
}
fragment sentientFragment on Sentient {
name
}
</code></pre><p>is not valid because there exists no type that implements both <span class="spec-nt">Pet</span> and <span class="spec-nt">Sentient</span>.</p></section></section></section></section><section id="sec-Values"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Values">5.5</a></span>Values</h3><section id="sec-Input-Object-Field-Uniqueness"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Input-Object-Field-Uniqueness">5.5.1</a></span>Input Object Field Uniqueness</h4><p><strong> Formal Specification </strong></p><ul><li>For each input object value <var>inputObject</var> in the document.</li><li>For every <var>inputField</var> in <var>inputObject</var><ul><li>Let <var>name</var> be the Name of <var>inputField</var>.</li><li>Let <var>fields</var> be all Input Object Fields named <var>name</var> in <var>inputObject</var>.</li><li><var>fields</var> must be the set containing only <var>inputField</var>.</li></ul></li></ul><p><strong> Explanatory Text </strong></p><p>Input objects must not contain more than one fields of the same name, otherwise an amgibuity would exist which includes an ignored portion of syntax.</p><p>For example the following query will not pass validation.</p><pre class="spec-counter-example"><code>{
field(arg: { field: true, field: false })
}
</code></pre></section></section><section id="sec-Validation.Directives"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Validation.Directives">5.6</a></span>Directives</h3><section id="sec-Directives-Are-Defined"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Directives-Are-Defined">5.6.1</a></span>Directives Are Defined</h4><p><strong> Formal Specification </strong></p><ul><li>For every <var>directive</var> in a document.</li><li>Let <var>directiveName</var> be the name of <var>directive</var>.</li><li>Let <var>directiveDefinition</var> be the directive named <var>directiveName</var>.</li><li><var>directiveDefinition</var> must exist.</li></ul><p><strong> Explanatory Text </strong></p><p>GraphQL servers define what directives they support. For each usage of a directive, the directive must be available on that server.</p></section></section><section id="sec-Validation.Operations"><h3><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Validation.Operations">5.7</a></span>Operations</h3><section id="sec-Validation.Operations.Variables"><h4><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Validation.Operations.Variables">5.7.1</a></span>Variables</h4><section id="sec-Variable-Default-Values-Are-Correctly-Typed"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Variable-Default-Values-Are-Correctly-Typed">5.7.1.1</a></span>Variable Default Values Are Correctly Typed</h5><p><strong> Formal Specification </strong></p><ul><li>For every <var>operation</var> in a document</li><li>For every <var>variable</var> on each <var>operation</var><ul><li>Let <var>variableType</var> be the type of <var>variable</var></li><li>If <var>variableType</var> is non‐null it cannot have a default value</li><li>If <var>variable</var> has a default value it must be of the same types or able to be coerced to <var>variableType</var></li></ul></li></ul><p><strong> Explanatory Text </strong></p><p>Variable defined by operations are allowed to define default values if the type of that variable not non‐null.</p><p>For example the following query will pass validation.</p><pre><code>query houseTrainedQuery($atOtherHomes: Boolean = true) {
dog {
isHousetrained(atOtherHomes: $atOtherHomes)
}
}
</code></pre><p>However if the variable is defined as non‐null, default values are unreachable. Therefore queries such as the following fail validation</p><pre class="spec-counter-example"><code>query houseTrainedQuery($atOtherHomes: Boolean! = true) {
dog {
isHousetrained(atOtherHomes: $atOtherHomes)
}
}
</code></pre><p>Default values must be compatible with the types of variables. Types must match or they must be coercible to the type.</p><p>Non‐matching types fail, such as in the following example:</p><pre class="spec-counter-example"><code>query houseTrainedQuery($atOtherHomes: Boolean = "true") {
dog {
isHousetrained(atOtherHomes: $atOtherHomes)
}
}
</code></pre><p>However if a type is coercible the query will pass validation.</p><p>For example:</p><pre><code>query intToFloatQuery($floatVar: Float = 1) {
arguments {
floatArgField(floatArg: $floatVar)
}
}
</code></pre></section><section id="sec-Variables-Are-Input-Types"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-Variables-Are-Input-Types">5.7.1.2</a></span>Variables Are Input Types</h5><p><strong> Formal Specification </strong></p><ul><li>For every <var>operation</var> in a <var>document</var></li><li>For every <var>variable</var> on each <var>operation</var><ul><li>Let <var>variableType</var> be the type of <var>variable</var></li><li>While <var>variableType</var> is <span class="spec-nt">LIST</span> or <span class="spec-nt">NON_NULL</span><ul><li>Let <var>variableType</var> be the referenced type of <var>variableType</var></li></ul></li><li><var>variableType</var> must of kind <span class="spec-nt">SCALAR</span>, <span class="spec-nt">ENUM</span> or <span class="spec-nt">INPUT_OBJECT</span></li></ul></li></ul><p><strong> Explanatory Text </strong></p><p>Variables can only be scalars, enums, input objects, or lists and non‐null variants of those types. These are known as input types. Object, unions, and interfaces cannot be used as inputs.</p><p>The following queries are valid:</p><pre><code>query takesBoolean($atOtherHomes: Boolean) {
# ...
}
query takesComplexInput($complexInput: ComplexInput) {
# ...
}
query TakesListOfBooleanBang($booleans: [Boolean!]) {
# ...
}
</code></pre><p>The following queries are invalid:</p><pre class="spec-counter-example"><code>query takesCat($cat: Cat) {
# ...
}
query takesDogBang($dog: Dog!) {
# ...
}
query takesListOfPet($pets: [Pet]) {
# ...
}
query takesCatOrDog($catOrDog: CatOrDog) {
# ...
}
</code></pre></section><section id="sec-All-Variable-Uses-Defined"><h5><span class="spec-secid" title="link to this section"><a href="https://facebook.github.io/graphql/#sec-All-Variable-Uses-Defined">5.7.1.3</a></span>All Variable Uses Defined</h5><p><strong> Formal Specification </strong></p><ul><li>For each <var>operation</var> in a document<ul><li>For each <var>variableUsage</var> in scope, variable must be operation’s variable list.</li><li>Let <var>fragments</var> be every fragment reference by that operation transitively</li><li>For each <var>fragment</var> in <var>fragments</var><ul><li>For each <var>variableUsage</var> in scope of <var>fragment</var>, variable must be <var>operation</var>‘s variable list.</li></ul></li></ul></li></ul><p><strong> Explanatory Text </strong></p><p>Variables are scoped on a per‐operation basis. That means that any variable used within the context of a operation must be defined at the top level of that operation</p><p>For example:</p><pre><code>query variableIsDefined($atOtherHomes: Boolean) {
dog {
isHousetrained(atOtherHomes: $atOtherHomes)
}
}
</code></pre><p>is valid. $<var>atOtherHomes</var> is defined by the operation.</p><p>By contrast the following query is invalid:</p><pre class="spec-counter-example"><code>query variableIsNotDefined {
dog {
isHousetrained(atOtherHomes: $atOtherHomes)
}
}
</code></pre><p>$<var>atOtherHomes</var> is not defined by the operation.</p><p>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.</p><p>For example the following is valid:</p><pre><code>query variableIsDefinedUsedInSingleFragment($atOtherHomes: Boolean) {
dog {