Skip to content

Commit 1b8fe7a

Browse files
benjieromanivantsovleebyron
authored
Leaf field selections clarification (#958)
Clarify both the formal and explanatory description of "Leaf Field Selections" validation rule. This clarifies the definition of a "leaf field" and when a subselection is or is not allowed, and expands the set of examples. Co-authored-by: Roman Ivantsov <[email protected]> Co-authored-by: Lee Byron <[email protected]>
1 parent a91e158 commit 1b8fe7a

File tree

1 file changed

+17
-7
lines changed

1 file changed

+17
-7
lines changed

spec/Section 5 -- Validation.md

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -575,16 +575,16 @@ fragment conflictingDifferingResponses on Pet {
575575
**Formal Specification**
576576

577577
- For each {selection} in the document:
578-
- Let {selectionType} be the result type of {selection}.
578+
- Let {selectionType} be the unwrapped result type of {selection}.
579579
- If {selectionType} is a scalar or enum:
580580
- The subselection set of that selection must be empty.
581581
- If {selectionType} is an interface, union, or object:
582582
- The subselection set of that selection must NOT BE empty.
583583

584584
**Explanatory Text**
585585

586-
Field selections on scalars or enums are never allowed, because they are the
587-
leaf nodes of any GraphQL operation.
586+
A field subselection is not allowed on leaf fields. A leaf field is any field
587+
with a scalar or enum unwrapped type.
588588

589589
The following is valid.
590590

@@ -604,9 +604,8 @@ fragment scalarSelectionsNotAllowedOnInt on Dog {
604604
}
605605
```
606606

607-
Conversely the leaf field selections of GraphQL operations must be of type
608-
scalar or enum. Leaf selections on objects, interfaces, and unions without
609-
subfields are disallowed.
607+
Conversely, non-leaf fields must have a field subselection. A non-leaf field is
608+
any field with an object, interface, or union unwrapped type.
610609

611610
Let's assume the following additions to the query root operation type of the
612611
schema:
@@ -619,7 +618,8 @@ extend type Query {
619618
}
620619
```
621620

622-
The following examples are invalid
621+
The following examples are invalid because they include non-leaf fields without
622+
a field subselection.
623623

624624
```graphql counter-example
625625
query directQueryOnObjectWithoutSubFields {
@@ -635,6 +635,16 @@ query directQueryOnUnionWithoutSubFields {
635635
}
636636
```
637637

638+
However the following example is valid since it includes a field subselection.
639+
640+
```graphql example
641+
query directQueryOnObjectWithSubFields {
642+
human {
643+
name
644+
}
645+
}
646+
```
647+
638648
## Arguments
639649

640650
Arguments are provided to both fields and directives. The following validation

0 commit comments

Comments
 (0)