List in output is missing '@list' directive or equivalent

Issue ID: graphql-data-output-list-directive-needed

Average severity: High

Description

A list used in an input position does not declare a recognized wrapper constraint directive, such as @list or an equivalent directive supported by your validation framework.

In GraphQL, list types (for example, [UserId!]!) define the type of elements but not the structural constraints for them, such as:

  • Minimum number of items
  • Maximum number of items
  • Uniqueness of elements
  • Wrapper-level validation semantics

A wrapper constraint directive allows expressing these constraints explicitly at the schema level.

For more details, see the GraphQL constraints specification.

Possible exploit scenario

Without a wrapper constraint directive:

  • The list has no formal size bounds
  • The API contract does not specify expected collection limits
  • Abnormal or oversized responses are harder to detect
  • Automated auditing and validation become less precise

This can lead to:

  • Acciental bulk data exposure
  • Increased attack surface for enumeration
  • Increased response sizes
  • Performance degradation for API consumers, with downstream systems potentially overwhelmed
  • Amplification of response size in federated graphs
  • Difficulty detecting anomalous responses

If a backend filtering mechanism is bypassed or misconfigured, an attacker may trigger a query that returns a much larger dataset than intended. For example, a field expected to return recent transactions might accidentally return an entire historical dataset if backend filtering fails. Without a defined upper bound, this deviation might not be detectable at the contract level.

Remediation

Include a recognized wrapper constraint directive (such as @list) to all input list types. We recommend that you:

  • Always define maxItems for output lists
  • Define minItems when business logic guarantees at least one element
  • Align constraints with documented API behavior
  • Maintain consistent list constraints across federated subgraphs

Explicit wrapper constraints strengthen API contract clarity, reduce bulk exposure risk, and improve response validation capabilities.