Skip to content

Consistently use 'response name' not 'response key' #1147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Apr 17, 2025
Merged

Consistently use 'response name' not 'response key' #1147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
27e8bee
Consistently use 'response key' not 'response name'
benjie Mar 10, 2025
4a15e4a
Extract definition of response key from #1039
benjie Mar 10, 2025
b3cbb53
Utilise definition
benjie Mar 10, 2025
4eaaa4a
response key -> response name
benjie Mar 10, 2025
15d7f5c
Fix names in algorithms
benjie Mar 10, 2025
8cbde9c
Merge branch 'main' into response-key
leebyron Apr 17, 2025
43310af
latest changes
leebyron Apr 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions spec/Section 2 -- Language.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -466,8 +466,9 @@ These two operations are semantically identical:

Alias : Name :

By default a field's response key in the response object will use that field's
name. However, you can define a different response key by specifying an alias.
:: A _response name_ is the key in the response object which correlates with a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking out loud -
Should response object be updated to response map in #1039?

But then this will not be accurate with incremental delivery, as a response name can also appear in the subsequent payloads. Should there be a new term (Response Data Tree?) to refer to the entire response data?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is referring to the object in the response representing the current Object Type's data, as opposed to the entire response which may use multiple names/aliases which may or may not overlap. It's a good point though, we should be clearer about this!

field's result. By default the response name will use the field's name; however,
you can define a different response name by specifying an alias.

In this example, we can fetch two profile pictures of different sizes and ensure
the resulting response object will not have duplicate keys:
Expand Down
12 changes: 6 additions & 6 deletions spec/Section 5 -- Validation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -418,7 +418,7 @@ fragment directFieldSelectionOnUnion on CatOrDog {

FieldsInSetCanMerge(set):

- Let {fieldsForName} be the set of selections with a given response name in
- Let {fieldsForName} be the set of selections with a given _response name_ in
{set} including visiting fragments and inline fragments.
- Given each pair of distinct members {fieldA} and {fieldB} in {fieldsForName}:
- {SameResponseShape(fieldA, fieldB)} must be true.
Expand Down Expand Up @@ -450,7 +450,7 @@ SameResponseShape(fieldA, fieldB):
- Assert: {typeB} is an object, union or interface type.
- Let {mergedSet} be the result of adding the selection set of {fieldA} and the
selection set of {fieldB}.
- Let {fieldsForName} be the set of selections with a given response name in
- Let {fieldsForName} be the set of selections with a given _response name_ in
{mergedSet} including visiting fragments and inline fragments.
- Given each pair of distinct members {subfieldA} and {subfieldB} in
{fieldsForName}:
Expand All @@ -462,10 +462,10 @@ type that is either an Object, Interface or Union type.

**Explanatory Text**

If multiple field selections with the same response names are encountered during
execution, the field and arguments to execute and the resulting value should be
unambiguous. Therefore any two field selections which might both be encountered
for the same object are only valid if they are equivalent.
If multiple field selections with the same _response name_ are encountered
during execution, the field and arguments to execute and the resulting value
should be unambiguous. Therefore any two field selections which might both be
encountered for the same object are only valid if they are equivalent.

During execution, the simultaneous execution of fields with the same response
name is accomplished by {MergeSelectionSets()} and {CollectFields()}.
Expand Down
32 changes: 16 additions & 16 deletions spec/Section 6 -- Execution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -362,15 +362,15 @@ ExecuteSelectionSet(selectionSet, objectType, objectValue, variableValues):
- Let {groupedFieldSet} be the result of {CollectFields(objectType,
selectionSet, variableValues)}.
- Initialize {resultMap} to an empty ordered map.
- For each {groupedFieldSet} as {responseKey} and {fields}:
- For each {groupedFieldSet} as {responseName} and {fields}:
- Let {fieldName} be the name of the first entry in {fields}. Note: This value
is unaffected if an alias is used.
- Let {fieldType} be the return type defined for the field {fieldName} of
{objectType}.
- If {fieldType} is defined:
- Let {responseValue} be {ExecuteField(objectType, objectValue, fieldType,
fields, variableValues)}.
- Set {responseValue} as the value for {responseKey} in {resultMap}.
- Set {responseValue} as the value for {responseName} in {resultMap}.
- Return {resultMap}.

Note: {resultMap} is ordered by which fields appear first in the operation. This
Expand Down Expand Up @@ -496,8 +496,8 @@ A correct executor must generate the following result for that _selection set_:

Before execution, the _selection set_ is converted to a grouped field set by
calling {CollectFields()}. Each entry in the grouped field set is a list of
fields that share a response key (the alias if defined, otherwise the field
name). This ensures all fields with the same response key (including those in
fields that share a _response name_ (the alias if defined, otherwise the field
name). This ensures all fields with the same response name (including those in
referenced fragments) are executed at the same time.

As an example, collecting the fields of this selection set would collect two
Expand Down Expand Up @@ -539,11 +539,11 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
in {variableValues} with the value {true}, continue with the next
{selection} in {selectionSet}.
- If {selection} is a {Field}:
- Let {responseKey} be the response key of {selection} (the alias if
- Let {responseName} be the _response name_ of {selection} (the alias if
defined, otherwise the field name).
- Let {groupForResponseKey} be the list in {groupedFields} for
{responseKey}; if no such list exists, create it as an empty list.
- Append {selection} to the {groupForResponseKey}.
- Let {groupForResponseName} be the list in {groupedFields} for
{responseName}; if no such list exists, create it as an empty list.
- Append {selection} to the {groupForResponseName}.
- If {selection} is a {FragmentSpread}:
- Let {fragmentSpreadName} be the name of {selection}.
- If {fragmentSpreadName} is in {visitedFragments}, continue with the next
Expand All @@ -561,11 +561,11 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
{CollectFields(objectType, fragmentSelectionSet, variableValues,
visitedFragments)}.
- For each {fragmentGroup} in {fragmentGroupedFieldSet}:
- Let {responseKey} be the response key shared by all fields in
- Let {responseName} be the response name shared by all fields in
{fragmentGroup}.
- Let {groupForResponseKey} be the list in {groupedFields} for
{responseKey}; if no such list exists, create it as an empty list.
- Append all items in {fragmentGroup} to {groupForResponseKey}.
- Let {groupForResponseName} be the list in {groupedFields} for
{responseName}; if no such list exists, create it as an empty list.
- Append all items in {fragmentGroup} to {groupForResponseName}.
- If {selection} is an {InlineFragment}:
- Let {fragmentType} be the type condition on {selection}.
- If {fragmentType} is not {null} and {DoesFragmentTypeApply(objectType,
Expand All @@ -576,11 +576,11 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments):
{CollectFields(objectType, fragmentSelectionSet, variableValues,
visitedFragments)}.
- For each {fragmentGroup} in {fragmentGroupedFieldSet}:
- Let {responseKey} be the response key shared by all fields in
- Let {responseName} be the response name shared by all fields in
{fragmentGroup}.
- Let {groupForResponseKey} be the list in {groupedFields} for
{responseKey}; if no such list exists, create it as an empty list.
- Append all items in {fragmentGroup} to {groupForResponseKey}.
- Let {groupForResponseName} be the list in {groupedFields} for
{responseName}; if no such list exists, create it as an empty list.
- Append all items in {fragmentGroup} to {groupForResponseName}.
- Return {groupedFields}.

DoesFragmentTypeApply(objectType, fragmentType):
Expand Down
4 changes: 2 additions & 2 deletions spec/Section 7 -- Response.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,11 +56,11 @@ of a {ExecuteSelectionSet()}, or it is a position in a (potentially nested) List
value. Each response position is uniquely identifiable via a _response path_.

:: A _response path_ uniquely identifies a _response position_ via a list of
path segments (response keys or list indices) starting at the root of the
path segments (response names or list indices) starting at the root of the
response and ending with the associated response position.

The value for a _response path_ must be a list of path segments. Path segments
that represent field response keys must be strings, and path segments that
that represent field _response name_ must be strings, and path segments that
represent list indices must be 0-indexed integers. If a path segment is
associated with an aliased field it must use the aliased name, since it
represents a path in the response, not in the request.
Expand Down