GraphQL Specification

GraphQL is a query language designed for building client applications. It provides an intuitive and flexible syntax for describing data requirements and interactions.

Key characteristics include:

• Not a programming language: It is used to make requests to application services that have capabilities defined by the GraphQL specification.
• Language/Storage Agnostic: It does not mandate specific programming languages or storage systems; instead, services map their capabilities to the GraphQL type system.
• Hierarchical Structure: GraphQL requests are structured hierarchically, mirroring the shape of the data in the response.
• Strong-typing: Every service defines an application-specific type system. This allows tools to validate requests for syntactic and type correctness before execution.
• Client-specified responses: Clients specify exactly what data they need at field-level granularity. A response contains exactly what was requested and no more.
• Self-describing: Through introspection, the GraphQL type system can be queried by the GraphQL language itself, allowing for the discovery of capabilities and documentation.

{
  user(id: 4) {
    name
  }
}

A GraphQL List is a collection type that declares the type of each item within it (the item type). Lists are serialized as ordered sequences. You can denote a list by wrapping the item type in square brackets.

Syntax

• Single list: pets: [Pet]
• Nested lists: matrix: [[Int]]

Result Coercion (Server Behavior)

• If the item type is nullable (e.g., [Int]), an error occurring during the coercion of an individual item results in a {null} value at that position in the list, accompanied by an execution error in the response.
• If the item type is non-null (e.g., [Int!]), an error occurring at an individual item results in an execution error for the entire list.

Input Coercion (Client Behavior)

When providing input to a list, if the provided value is not a list and not {null}, GraphQL will coerce it into a list of size one containing that value. This allows clients to pass a single value to an argument that expects a list.

# Examples of type declarations
field: [String]
matrix: [[Int]]
nonNullList: [Int!]!

A GraphQL Union represents an object that could be one of a list of GraphQL Object types, but provides no guaranteed fields across those types. Unlike interfaces, unions do not define any fields themselves.

Querying Unions: Because unions define no fields, you cannot query fields directly on a union type. You must use type refining fragments (such as inline fragments) or the __typename meta-field to access specific fields on the underlying object types.

Constraints:

• Union members must be Object base types. Scalar, Interface, and Union types cannot be members of a union.
• All member types in a union must be unique.

union SearchResult = Photo | Person

type Person {
  name: String
}

type Photo {
  width: Int
}

# Valid query using inline fragments
{
  firstSearchResult {
    ... on Person {
      name
    }
    ... on Photo {
      width
    }
  }
}

Arguments provided in an operation must be coerced into the types defined by the schema.

Rules for Coercion:

• Variables: If an argument is a {Variable}, its value is retrieved from variableValues. Variables themselves are not coerced during field execution because they are expected to be validated during the initial operation coercion phase.
• Literals: If an argument is a literal value, it is coerced according to the input coercion rules of the argument's type.
• Default Values: If no value is provided for an argument, the schema's defaultValue is used. The default value is coerced according to the input coercion rules.
• Non-Null Constraints: If an argument is a Non-Nullable type and no value is provided (and no default exists) or the value is null, an execution error is raised.

Note: Any request error raised during argument coercion should be treated as an execution error.

An Object type must be a super-set of all interfaces it implements. To be a valid implementation, the following rules apply via the IsValidImplementation(type, implementedType) logic:

1. Interface Inheritance: If the implementedType (the interface) declares it implements other interfaces, the type (the object) must also declare it implements those same interfaces.
2. Field Presence: The object type must include a field of the same name for every field defined in the interface.
3. Argument Invariance: For every field in the interface, the implementing object field must include an argument of the same name, and that argument must accept the exact same type (invariant).
4. Additional Arguments: An object field may include additional arguments not defined in the interface, but they must not be required (i.e., they must be nullable).
5. Type Covariance: The return type of the object field must be equal to or a sub-type of the interface field's return type. Valid sub-types include:
   • The same type.
   • An Object type that is a possible type of a Union type defined in the interface.
   • An Object or Interface type that implements the interface type defined in the field.
   • A List type where the item type is a valid sub-type of the interface's item type.
   • A Non-Null variant of a valid sub-type.