# GRAPHQL Knowledge Patch > GraphQL - Skill: `nevaberry/graphql-knowledge-patch` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add nevaberry/graphql-knowledge-patch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/graphql-knowledge-patch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/graphql-knowledge-patch --- # GraphQL Knowledge Patch Use this skill when implementing, reviewing, or debugging GraphQL schemas, execution engines, clients, servers, gateways, or GraphQL-over-HTTP behavior. Start with the compatibility checks below, then open the topic reference that matches the work. ## Working Method 1. Identify whether the change concerns source syntax, schema validation, execution, or HTTP transport. 2. Inspect the implementation's declared GraphQL specification and GraphQL-over-HTTP support before changing behavior. 3. Apply the breaking and validation checks before adopting convenience behavior. 4. Keep transport errors distinct from GraphQL request and execution errors. 5. Test custom-scalar coercion, non-null propagation, and content negotiation explicitly when they are in scope. 6. Consult the repository's code, tests, and pinned dependencies for implementation-specific behavior. ## Reference Index | Reference | Topics | | --- | --- | | [language-and-schema.md](references/language-and-schema.md) | Unicode source text, escapes, schema coordinates, deprecation validation, stable ordering | | [execution.md](references/execution.md) | Request extensions, executable descriptions, default coercion, argument errors, response propagation | | [http-transport.md](references/http-transport.md) | Media negotiation, GET and POST envelopes, response status mapping, granular failures | ## Breaking and Validation Checks ### Do not pass explicit null to non-null control arguments The built-in `@deprecated` directive's `reason` argument and introspection's `includeDeprecated` arguments are non-null but retain defaults. Omission is valid; explicitly supplying `null` is invalid. Audit schema generation and introspection clients for patterns such as: ```graphql field: String @deprecated(reason: null) ``` and: ```graphql query { __type(name: "Business") { fields(includeDeprecated: null) { name } } } ``` Omit these arguments to select their defaults. ### Enforce interface deprecation consistency An object field cannot be deprecated unless the corresponding interface field is also deprecated. Reject a schema that deprecates only the implementing object's version of an interface field. When deprecating an implemented field: 1. Deprecate the interface field. 2. Deprecate the corresponding fields on implementing objects as needed. 3. Re-run schema validation before publishing the schema. ### Classify coercion failures by phase Variable coercion failures are request errors and prevent execution. Input coercion failures encountered while coercing a field's arguments are execution errors. The latter participate in partial-result handling and non-null propagation. Do not collapse both paths into one pre-execution error category. Tests should assert whether resolvers run, whether partial `data` is present, and where errors are reported. ### Negotiate the preferred response media type A conforming client includes `application/graphql-response+json` in `Accept`. When server support is unknown, send: ```http Accept: application/graphql-response+json, application/json;q=0.9 ``` Servers support the preferred media type and select the highest-priority supported type. If no response type is acceptable, returning `406` and stopping is the recommended behavior in the cases detailed by the transport reference. ### Do not assume every GraphQL response uses status 200 For `application/graphql-response+json`, response shape determines the status class: | Response shape | Status rule | | --- | --- | | `data` is non-null | Must be `2xx` | | `data` exists and `errors` is absent | Should be `200` | | `data` and `errors` both exist | Should be `294 Partial Success` | | `data` is absent | Must be an appropriate `4xx` or `5xx` | The custom `294` recommendation includes `data: null` with `errors`. A failure that prevents formation of a well-formed GraphQL response uses an appropriate `4xx` or `5xx` and must not claim the preferred GraphQL response media type. ## Language and Schema Quick Reference ### Encode supplementary characters with scalar escapes GraphQL source characters are Unicode scalar values through U+10FFFF. In quoted strings, prefer variable-width brace escapes for supplementary characters: ```graphql mutation { send(message: "\u{1F4A9}") } ``` Fixed-width escapes and valid surrogate-pair escapes remain accepted. An unpaired surrogate is invalid. Escape sequences are interpreted in quoted strings, not block strings. ### Use the schema-coordinate grammar Schema coordinates are whitespace-free identifiers for schema elements: ```text Business Business.name Query.searchBusiness(criteria:) @private @private(scope:) ``` `Type.member` can identify a field, input field, or enum value. Parenthesized forms identify field or directive arguments. There is no coordinate for union membership, and meta-fields and introspection types are not schema elements. ### Preserve stable order without assigning semantics Implementations should retain the order of semantically unordered collections where practical. This reduces needless churn for tools and people, but consumers must not treat the observed order as meaningful. ## Execution Quick Reference ### Reserve top-level request fields An execution request may include an `extensions` map for implementation-specific information. Do not invent other top-level request properties. Give extension keys unique prefixes to reduce collisions. ### Keep executable descriptions non-semantic Descriptions and comments on operations, fragments, and variable definitions must not affect execution, validation, or response content. They may support logging or developer tooling only when that use has no observable execution effect. ### Coerce defaults before runtime use When an omitted variable or field argument has a default, including `null`, coerce the default according to its declared input type before storing it or passing it to a resolver. For custom scalars, use the coerced runtime value, not the source literal. Schema argument-default coercion may be cached. ### Report one error per response position If an execution error already made a response position `null`, propagation through non-null parents does not add duplicate errors. A failed item in `[T!]` nulls the entire list position; unresolved siblings may be cancelled. If non-null propagation reaches the root, `data` becomes `null`. ## HTTP Request Quick Reference ### Interpret optional parameters carefully For GET requests, non-empty `variables` and `extensions` values are JSON strings. An empty optional parameter means omission. The URL value `operationName=null` selects an operation literally named `null`; omit the parameter or use an empty value to select no operation name. In a JSON POST envelope, an optional parameter whose JSON value is `null` is treated as omitted. ### Separate envelope validity from document validity Servers must support UTF-8 `application/json` POST bodies. Unknown JSON properties are ignored. A missing `query` or a parameter of the wrong type makes the transport request malformed. A string-valued `query` is transport-well-formed even if the contained GraphQL document later fails parsing or validation. A POST without `Content-Type` should receive an appropriate `4xx`. ### Use phase-specific failure statuses Common mappings include: - `400` for invalid JSON or an unparseable GraphQL document. - `405` for a mutation over GET, and preferably for an unsupported method. - `406` when no response media type is acceptable. - `408`, `413`, `414`, and `431` for request-production timeout, an oversized body, an oversized URI, and oversized headers. - `415` for an unsupported request media type. - `422` for malformed envelopes, validation failures, ambiguous operation selection, or variable coercion failures. - An appropriate `401` or `403` for permission failures. - An appropriate `5xx` for maintenance or load shedding, preferably `503`. Open [http-transport.md](references/http-transport.md) before implementing status handling; the media type determines whether a body is safely recognizable as a GraphQL response independently of status. ## Review Checklist - Validate non-null deprecation and introspection control arguments. - Validate interface and implementing-object deprecations together. - Test quoted-string scalar escapes separately from block strings. - Parse schema coordinates with their standalone grammar. - Coerce omitted defaults to runtime values before resolver invocation. - Distinguish variable coercion from field-argument coercion failures. - Deduplicate errors while propagating through non-null response positions. - Namespace request-extension keys and reject invented top-level fields. - Negotiate response media types before selecting response status behavior. - Treat GET and POST optional-parameter omission rules consistently. - Keep transport, GraphQL parsing, validation, and execution failures distinct. - Preserve stable collection order only as a presentation property.