Validation of @defer/@stream label arguments

[robrichard]

Context

raised by @BoD graphql/graphql-spec#742 (comment)

Should there be a formal validation rule for the label unicity? For instance it could clarify whether labels should be unique in an operation + any fragments it references.

The label argument on @defer and @stream is used by GraphQL clients to identify the data from patch responses and associate it with the correct fragment. If provided, the GraphQL Server must add it to the payload.

Validating this argument runs into the same issue that was discussed in @stream initialCount validation; the validation stage can happen before variables are known.

Three options considered:

1. No validation of the label argument
2. Raise a field error during execution if duplicate labels are encountered
3. Validation that prevents variables from being used in the label argument and checks for uniqueness. I'm not sure if there's value in having dynamic labels

Decision

Discussed at the March 2022 WG meeting and decided to add validation preventing variables in labels, and a validation enforcing uniqueness.

There haven't been any use cases raised that require variables for label values. This could be loosened later without breaking backwards compatibility if additional use cases are discovered.

Status

• defined in spec
• implemented in graphql-js

[glasser]

3 sounds reasonable to me. If this ends up preventing real use cases, we can always allow it later.

[robrichard]

This was discussed at the March 2022 WG meeting and we decided to add validation preventing variables in labels, and a validation enforcing uniqueness. Spec and reference implementation PRs have both been updated to reflect this.

[robrichard]

from @yaacovCR

Would it be possible to allow variables for label, as long as the same variable is not used more than once?

[robrichard]

I think that could work, it could be explored further if the current validation ends up preventing real use cases

[yaacovCR]

I guess you could run into an issue if different variables happened to have the same value, but I am not sure if we really need to validate for that, presumably if you are using variables as labels, you are doing so for a reason and ensuring they are unique on your own...

[BoD]

Sorry to come back to this topic again! A question arose while implementing this validation: is "document" meant to mean the whole document across multiple operations? For instance, this would mean the following is invalid:

query Query1 {
  field {
    ...fieldDetails1 @defer(label: "details")
  }
}

query Query2 {
  field {
    ...fieldDetails2 @defer(label: "details")
  }
}

even though this can never cause any ambiguity?

[robrichard]

@BoD "document" is intended to mean the entire document, not a specific operation in a document that contains multiple operations. I think it makes the validation significantly simpler (at least in the reference implementation) if the labels must be unique across the entire document instead of each operation. I think we can consider loosening this restriction if it's blocking any use cases.

[BoD]

Thanks a lot for the clarification.

In our case, implementing both versions is equivalent - we were just wondering if scoping the rule to the whole document was useful in a way that we missed.

[glasser]

@BoD Worth noting that in graphql-js, the "validation" stage does not actually take the specified operationName as an input.