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

Issue ID: graphql-data-input-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 enforceable size bounds
  • Cannot formally define structural expectations
  • Relies entirely on resolver-level validation

Unconstrained input lists are a common vector for:

  • Batch amplification attacks
  • Excessive database fan-out
  • N+1 query amplification
  • Memory exhaustion
  • CPU-intensive processing and increased resource consumption
  • Degraded performance

For example, an unconstrained list of identifiers in a mutation may allow thousands of elements in a single request, allowing attackers to submit a request containing an extremely large number of elements. This could significantly increase processing load.

Even if backend validation eventually limits processing, the absence of schema-level constraints increases attack surface and weakens contract enforcement. Using a wrapper constraint directive makes list structure explicit and enforceable at the API 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 input lists
  • Define minItems where empty lists are not valid for business logic
  • Align limits with backend processing capabilities
  • Avoid relying solely on resolver-level validation

Explicit wrapper constraints significantly improve API robustness, reduce abuse potential, and strengthen schema-driven security controls.