GRAPHQL Knowledge Patch

GraphQL Knowledge Patch

Use this skill when implementing, reviewing, or troubleshooting GraphQL source text, schemas, execution, clients, servers, or the HTTP transport. Determine the specification and transport behavior implemented by the project, then open the reference that matches the task.

Project schemas, implementation documentation, tests, and observed behavior are authoritative when they differ from this guidance. Treat draft transport details as a protocol contract shared by the client, server, gateway, and intermediaries.

How to use this skill

1. Identify whether the task concerns the language, schema validation, execution, request encoding, response negotiation, or status handling.
2. Establish which GraphQL and GraphQL-over-HTTP rules the implementation claims to support.
3. Read the matching reference before changing parsers, validators, coercion, error propagation, media types, or status codes.
4. Test both success and failure paths at the boundary where behavior changes.
5. Prefer local implementation behavior when the project deliberately targets a different specification revision, and document that compatibility decision.

Reference index

Breaking changes and deprecations

Send an acceptable response type

• Conforming clients include application/graphql-response+json in Accept.

• When server support is uncertain, use the compatibility form:

  Accept: application/graphql-response+json, application/json;q=0.9
  

• Servers support application/graphql-response+json and honor the highest- priority supported response type.

• When no offered type is acceptable, return 406 and stop or disregard Accept; prefer 406 when the request offers neither a supported type nor application/json.

Do not pass null to non-null deprecation controls

• @deprecated(reason:) and introspection includeDeprecated arguments are non-null while retaining defaults.
• Callers may omit these arguments, but explicitly supplying null is invalid.

Keep interface and object deprecations consistent

• An object field that implements an interface field cannot be deprecated unless the corresponding interface field is also deprecated.
• Reject schemas that deprecate only the implementing object's field.

Distinguish variable and field-argument coercion failures

• Variable coercion failures are request errors and prevent execution.
• Input-coercion failures encountered while coercing a field's arguments are execution errors. Preserve partial-result handling and non-null propagation.

Do not assume every GraphQL failure is HTTP 200

• For application/graphql-response+json, a non-null data requires 2xx.
• If data is absent, use an appropriate 4xx or 5xx.
• The transport guidance distinguishes malformed transport, parse, validation, selection, coercion, authorization, timeout, and capacity failures.

HTTP quick reference

Encode requests precisely

• For GET, encode non-empty variables and extensions as JSON strings.
• Treat an empty optional GET parameter as omitted.
• operationName=null selects an operation literally named null; omit the parameter or send an empty value when no operation name is selected.
• In a JSON POST body, treat JSON null for an optional parameter as omission.
• Support UTF-8 application/json POST bodies. Reject a missing Content-Type with an appropriate 4xx when enforcing the recommended behavior.
• Ignore unknown JSON properties. Treat a missing query or a parameter of the wrong type as a malformed transport request.
• A string query is transport-well-formed even if GraphQL parsing or validation subsequently fails.

Interpret the negotiated media type

• With application/graphql-response+json, process the body as a GraphQL response regardless of HTTP status.
• Only that media type identifies a body as a GraphQL response independently of status.
• For a legacy client accepting only application/json, apply the same status rules, but send Content-Type: application/json only for 2xx responses.
• If a failure prevents creation of a well-formed GraphQL response, use a suitable 4xx or 5xx and do not label the body application/graphql-response+json.

Map response shapes before specific failures

294 is a custom, non-IETF recommendation. It also covers data: null with errors; use it only with application/graphql-response+json under this transport contract.

Choose granular failure statuses

• 400: invalid JSON or an unparseable GraphQL document.
• 405: mutation over GET; also recommended for an unsupported method.
• 406: no acceptable response media type.
• 408: request production timeout.
• 413: POST body too large.
• 414: URI too large.
• 415: unsupported request Content-Type.
• 422: malformed GraphQL-over-HTTP envelope, validation failure, ambiguous operation selection, or variable coercion failure.
• 431: request headers too large.
• Use an appropriate 401 or 403 for permission failures.
• Use an appropriate 5xx for maintenance or load shedding; prefer 503.

Execution quick reference

Coerce defaults into runtime values

• When an omitted variable or field argument has a default, coerce the default according to its declared input type before storing it or passing it to a resolver. This includes a default of null.
• For a custom scalar, pass the scalar's coerced runtime value, not its source literal.
• Implementations may cache coercion of schema argument defaults.

Propagate errors once per response position

• Add only one error for a response position. If an execution error has already made the position null, propagating it through non-null parents does not add duplicate errors.
• If one item of [T!] fails, null the entire list position.
• Unresolved sibling positions may be cancelled during propagation.
• Set data to null when propagation crosses non-null positions all the way to the root.

Keep executable descriptions non-semantic

• Descriptions and comments on operation, fragment, and variable definitions do not affect execution, validation, or the response.
• Consume them only for non-observable work such as logs and developer tooling.

Reserve request metadata for extensions

• An execution request may carry an extensions map for implementation-specific information.
• Do not invent additional top-level request properties.
• Give extension keys unique prefixes to reduce collisions.

Language and schema quick reference

Parse Unicode scalar source text

• Treat source characters as Unicode scalar values through U+10FFFF.
• A valid UTF-16 surrogate pair represents one source character; an unpaired surrogate is invalid.
• Quoted strings accept variable-width scalar escapes such as \u{1F4A9}.
• Keep fixed-width escapes and valid surrogate-pair escapes accepted, while preferring brace-form escapes for supplementary characters.
• Interpret escapes only in quoted strings, never in block strings.

Use schema coordinates for exact elements

• Coordinates are standalone and contain no whitespace.
• Use Type, Type.member, Type.field(argument:), @directive, and @directive(argument:) forms.
• Type.member can identify a field, input field, or enum value.
• Coordinates can name built-ins, but cannot identify union membership.
• Meta-fields and introspection types are not schema elements and have no schema coordinates.

Preserve stable order without assigning semantics

• Preserve the order of semantically unordered collections where practical to avoid needless churn in tools and human-readable output.
• Consumers must still not treat that order as semantically meaningful.

Verification checklist

1. Exercise quoted and block strings separately, including supplementary scalar escapes and invalid unpaired surrogates.
2. Validate schema-coordinate parsing without accepting whitespace or unsupported element categories.
3. Test omitted and explicit-null deprecation arguments independently.
4. Test variable coercion before execution and field-argument coercion during execution as distinct error phases.
5. Verify one error per response position through lists and nested non-null fields.
6. Negotiate both preferred and legacy response media types, including an unacceptable Accept value.
7. Test empty, omitted, JSON-null, and wrong-type optional request parameters.
8. Assert response media type, response shape, and status code together.
9. Keep the custom 294 path explicit in client, proxy, monitoring, and server tests wherever that recommendation is adopted.