GraphQL Query Validation

The initial validation layer checks if the incoming query string is a well-formed GraphQL document. The server's parser must successfully construct an Abstract Syntax Tree (AST). This step catches fundamental errors like:

• Unmatched braces or parentheses.
• Invalid characters or tokens.
• Malformed field arguments or directives. A query that fails here is rejected before any schema-aware checks begin.

The core of validation ensures the query aligns with the GraphQL schema's type system. The server verifies:

• Field Existence: Every selected field must be defined on the corresponding object type in the schema.
• Argument Compatibility: Provided arguments must match the defined names and expected input types (scalars, enums, input objects).
• Leaf Field Compliance: Fields at the leaves of the query must be of scalar or enum types; you cannot select sub-fields on a scalar. This guarantees the query is executable against the published data graph.

Validation enforces correct usage of operations and fragments, which are key for complex queries.

• Operation Uniqueness: Each named operation in a request must have a unique name.
• Fragment Spread Validity: All spread fragments (...FragmentName) must refer to a defined fragment, and the spread must be type-compatible with the context where it's used.
• Fragment Non-Cyclicity: Fragments must not form cycles (e.g., Fragment A spreads Fragment B which spreads Fragment A).
• Required Operation: A request must contain an operation (query, mutation, subscription).

Arguments and variable values undergo coercion and validation. The server checks if provided values can be converted to the expected input type defined in the schema.

• Scalar Validation: Strings, Ints, Floats, Booleans, and IDs are checked for format (e.g., Int must be a 32-bit signed integer).
• Enum Values: Provided values must match one of the allowed enum values exactly.
• Input Object Fields: All required fields on an input object type must be provided.
• Variable Definitions: Variables declared must be used, and their usage must be compatible with their defined type.

While not part of the official GraphQL spec, production systems implement complexity limits to prevent abusive or expensive queries. This is a critical security and performance validation.

• Query Depth: Limits the number of nested levels (e.g., user { posts { comments { author } } } has a depth of 4).
• Field Complexity: Assigns cost to fields, especially those causing database joins or expensive computations, and limits the total cost per query.
• Alias Multiplicity: Limits the number of aliases to prevent duplicate field requests that bypass depth limits.

Validation ensures directives and variables are used correctly within the query structure.

• Directive Locations: Every directive (e.g., @include, @skip, @deprecated) must be used in a valid location (FIELD, FRAGMENT_SPREAD, INLINE_FRAGMENT, etc.).
• Variable Uniqueness: All variable names within an operation must be unique.
• Variable Usage: All variables used in an operation must be defined in that operation's variable definition list.
• Required Variable Defaults: Variables cannot have default values if they are non-nullable (String!).

Contract testing is a methodology for ensuring that two independent services (like a client and a server) adhere to a shared API contract. Tools like Pact or Spring Cloud Contract generate tests from the API specification (OpenAPI for REST, GraphQL schema for GraphQL) to verify that:

• The provider's implementation matches the promised interface.
• The consumer's expectations are correctly defined. This approach catches breaking changes early without the complexity of full integration or end-to-end testing, making it essential for microservices and AI-agent integrations.

Semantic validation moves beyond checking syntax and type correctness to verify that data is meaningful within its business context. This involves enforcing logical rules that a schema alone cannot capture. Examples include:

• Ensuring a startDate field is chronologically before an endDate.
• Verifying that a discountCode is applicable to the items in a cart.
• Confirming a userId has permission to access the requested resource. While GraphQL's validation rules can check query depth, semantic validation often requires custom business logic executed after the initial query passes structural checks.

These are two fundamental phases of validation in API systems:

• Static Validation: Analysis performed without executing the main program. This includes linting a GraphQL schema for errors, validating an OpenAPI spec's structure, or using a type checker (like TypeScript) on client code that generates queries. It catches errors at build or design time.
• Dynamic Validation: Runtime checks that occur during execution. For GraphQL, this is the server-side query validation phase that inspects the incoming query's syntax, types, and complexity against the live schema. For REST APIs, this is validation middleware that checks request payloads against a JSON Schema. A robust system employs both.

Schema enforcement is the runtime application of strict validation rules to guarantee that all data inputs and outputs conform to a predefined model. It is the active practice that turns a passive schema document into a security and quality gate. Key implementations include:

• GraphQL servers rejecting queries that don't match the schema.
• API gateways using OpenAPI specs to validate and filter malformed requests.
• Using Pydantic models in Python or Zod in TypeScript to validate data at application boundaries. This practice is critical for structured output guarantees from AI agents and preventing malformed data from reaching business logic.