RFC-0027 · GraphQL Protocol Binding
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Reference catalog: the diagnostics, linked-RFC graph, defined terms, and normative-rule index for this RFC are in the reference catalog, generated from the structured Lean module. This document carries the prose: design rationale, entity-shape definitions in context, and migration notes.
1. Purpose
This RFC defines gnomon.io.graphql — the GraphQL protocol binding module for client operations. It specifies the slot extensions that gnomon.io.graphql registers on operation {} blocks, allowing authors to hand-author GraphQL operations inline in a client.operations {} block without relying on a schema adapter.
gnomon.io.graphql is a protocol binding, not a schema adapter. It does not introspect a GraphQL schema endpoint or generate operations from SDL files. For spec-backed GraphQL clients driven by schema introspection, see RFC-0031 (GraphQL introspection adapter), which generates operations in the form defined by this RFC.
GraphQL is transport-agnostic; in practice, nearly all GraphQL APIs are served over HTTP. gnomon.io.graphql delegates all HTTP transport concerns — request dispatch, response handling, auth headers, and timeout — to gnomon.io.http (RFC-0025). This RFC specifies only the GraphQL-specific layer above that transport.
This RFC defines:
- The slot extensions registered on
operation {}bygnomon.io.graphql(§2) - The three GraphQL operation types and their gnomon semantics (§3)
- How
input {}fields are bound to GraphQL variables (§4) - How GraphQL error shapes are mapped to the gnomon error taxonomy (§5)
- How
auth:on the enclosingclientis applied at the HTTP transport layer (§6) - Diagnostic codes in the M27xxx range (§7)
2. Slot Extensions
When gnomon.io.graphql is imported, it registers the following slots on operation {} blocks within any client that uses it. These slots are parsed by the compiler after loading gnomon.io.graphql’s module manifest (per RFC-0024 §6.2).
| Slot | Type | Required | Default | Description |
|---|---|---|---|---|
operationType: | GraphQLOperationType | Yes | — | query | mutation | subscription. |
operationName: | Text | No | auto-generated | The named GraphQL operation string (e.g. GetUser). If omitted, the compiler generates a name from the gnomon operation name. |
selection: | Text | Yes | — | The GraphQL selection set as a string literal (everything inside the outer { } of the operation document, including field selections, aliases, fragments, and inline fragments). |
variables: | List<Text> | No | all input fields | Names of input {} fields to pass as GraphQL variables. If omitted, all input fields are included as variables. |
2.1 Module Manifest (Normative)
module gnomon.io.graphql {
extends {
operation {
operationType: GraphQLOperationType required
operationName: Text optional
selection: Text required
variables: List<Text> optional
}
}
}
2.2 Example
imports {
gnomon.io.http: "^1.0.0"
gnomon.io.graphql: "^1.0.0"
}
client GitHubGraphQL {
meaning: "GitHub GraphQL API v4."
baseUrl: "https://api.github.com/graphql"
auth: bearer-token
operations {
getRepository {
meaning: "Fetch name and description for a repository."
input {
owner: Text required
name: Text required
}
returns: Repository
errors {
4xx: terminal
5xx: transient
}
operationType: query
operationName: "GetRepository"
selection: """
repository(owner: $owner, name: $name) {
id
name
description
stargazerCount
isPrivate
}
"""
variables: [owner, name]
}
createIssue {
meaning: "Create a new issue via the GraphQL mutation API."
input {
repositoryId: Text required
title: Text required
body: Text optional
}
returns: CreatedIssue
errors {
4xx: terminal
5xx: transient
}
operationType: mutation
operationName: "CreateIssue"
selection: """
createIssue(input: {
repositoryId: $repositoryId,
title: $title,
body: $body
}) {
issue {
id
number
url
}
}
"""
}
}
}
3. Operation Type Semantics
3.1 query
A query operation is read-only. It maps to a GraphQL query document on the wire.
- Gnomon call site: any call site where the operation result is consumed without side effects. Typically used in
execute {}blocks inactiondeclarations where the result informs mutations but is not itself a mutation. - Caching:
queryoperations MAY be cached by the runtime (implementation-defined).mutationandsubscriptionoperations MUST NOT be cached.
3.2 mutation
A mutation operation is side-effecting. It maps to a GraphQL mutation document on the wire.
- Gnomon call site:
execute {}blocks inactiondeclarations. The result is bound and used in themutations {}block of the action (RFC-0008 §6.10). - Idempotency: mutations are not assumed to be idempotent. The runtime MUST NOT retry a mutation automatically unless the operation’s
errors {}block explicitly classifies the relevant error astransient.
3.3 subscription
A subscription operation is streaming. It maps to a GraphQL subscription document, delivered over a long-lived transport (typically WebSocket or SSE).
- Returns: MUST be
Stream<T>whereTis the per-event type. The compiler emits M27711 ifoperationType: subscriptionis declared but thereturnstype is notStream<T>. - Gnomon call site: integrates with RFC-0020 reactive subscriptions. The returned
Stream<T>handle follows the RFC-0020 subscription lifecycle (open, pause, close). - Transport: the specific subscription transport (WebSocket, SSE, HTTP chunked) is implementation-defined. This RFC specifies only the logical delivery contract.
4. Variable Binding
input {} fields are passed to the GraphQL server as the variables object in the request payload. The variables: slot controls which fields are included.
4.1 Default Behavior
If variables: is omitted, all input {} fields are serialized into the variables object, keyed by their field names.
4.2 Explicit Variable List
If variables: is declared, only the named fields are included in the variables object. Fields present in input {} but absent from variables: are not sent.
A field referenced as $fieldName in the selection: string but absent from the effective variable set (either the explicit variables: list or, if variables: is omitted, the input {} schema) causes M27713 at compile time.
4.3 Wire Format
The outbound HTTP request body is a JSON object with the following shape:
{
"query": "<operationType> <operationName> { <selection> }",
"variables": { "<fieldName>": <value>, ... },
"operationName": "<operationName>"
}
The query string is assembled by the runtime from the operationType:, operationName:, and selection: slots. Authors declare only the selection set; the runtime wraps it in the correct GraphQL document envelope.
4.4 Type Coercion
Each input {} field is serialized to its JSON representation. Gnomon primitive types map to JSON types as follows:
| Gnomon type | GraphQL scalar | JSON encoding |
|---|---|---|
Text | String | JSON string |
Integer | Int | JSON number (integer) |
Decimal | Float | JSON number (float) |
Boolean | Boolean | JSON boolean |
List<T> | [T] | JSON array |
| custom record | input object type | JSON object |
5. Error Shape Mapping
GraphQL responses always return HTTP 200 (assuming the transport is functioning). Errors are communicated in a top-level errors array in the response JSON, alongside a data field. The runtime handles three cases.
5.1 Clean Success
data is non-null and errors is absent or null. The runtime deserializes data against the operation’s returns schema and returns it.
5.2 Hard Error (No Data)
data is null and errors is non-null. The runtime inspects each error object in the array:
- If
extensions.codeis present and matches a selector declared in the operation’serrors {}block, the matching error classification is applied. - If no match is found, the runtime raises M27711 for each unhandled error entry.
5.3 Partial Success (Data and Errors Both Present)
data is non-null and errors is non-null. This indicates a partial result: some fields resolved successfully while others failed.
The runtime:
- Returns the
dataportion, deserialized against thereturnsschema. Fields absent fromdatadue to errors are set to their zero values. - Emits M27710 for each entry in the
errorsarray. Each M27710 diagnostic carries the error message, path, andextensions.codeif present. - The operation is considered to have succeeded from the call-site perspective. The caller may inspect structured diagnostics (implementation-defined) to detect partial failures.
Authors who require strict all-or-nothing semantics MUST declare a wildcard errors selector that classifies partial results as terminal. The runtime will then treat any non-null errors array as a failure regardless of whether data is present.
5.4 HTTP-Level Errors
If the underlying HTTP transport returns a non-200 status code (e.g. 401, 429, 503), that error is handled by gnomon.io.http (RFC-0025 §5) before the GraphQL response body is inspected. The GraphQL layer sees only responses where the HTTP transport succeeded.
6. Auth
GraphQL is transport-agnostic. Authentication is applied at the HTTP transport layer by gnomon.io.http (RFC-0025 §3). The auth: slot on the enclosing client is interpreted by gnomon.io.http according to the mappings defined in RFC-0025 §3, with no GraphQL-specific behavior.
For example, auth: bearer-token on a GraphQL client causes gnomon.io.http to add Authorization: Bearer <token> to every HTTP request. The GraphQL server receives this header in the same way as any HTTP server.
No GraphQL-specific auth mechanism (e.g. persisted query tokens, per-query API keys in the request body) is defined by this RFC.
7. Diagnostic Codes
All codes in the M27xxx range are owned by this RFC.
| Code | Severity | Description |
|---|---|---|
| M27710 | Warning | GraphQL partial result: both data and errors are present in the response. The operation succeeded, but some fields may be missing or null. |
| M27711 | Error | operationType: slot missing from a GraphQL operation in a client that imports gnomon.io.graphql; or operationType: subscription declared with a non-streaming returns type; or unhandled GraphQL hard error (no matching selector in errors {}). |
| M27712 | Error | selection: slot missing from a GraphQL operation. |
| M27713 | Error | A $variableName token referenced in the selection: string is not declared in the effective variables: list (explicit or implicit). |
7.1 Failure Mode Summary
| Code | Description | Severity |
|---|---|---|
| M27710 | GraphQL partial result | Warning |
| M27711 | Missing operationType:, subscription return type mismatch, or unhandled hard error | Error |
| M27712 | Missing selection: slot | Error |
| M27713 | Variable referenced in selection not in variable set | Error |
8. What This RFC Does NOT Define
- GraphQL schema introspection and operation generation → RFC-0031
- SDL (Schema Definition Language) parsing — adapters only; not part of this binding
- Fragment definitions shared across operations — deferred; the
selection:slot is a self-contained string and does not support cross-operation fragment sharing in this version - Persisted queries / automatic query persisting — implementation-defined
- Subscription transport details (WebSocket subprotocol, SSE framing) — implementation-defined; this RFC specifies logical delivery only
- Batch query support (
[]request body) — deferred