gnomonlearn

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 {} by gnomon.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 enclosing client is 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).

SlotTypeRequiredDefaultDescription
operationType:GraphQLOperationTypeYes—query | mutation | subscription.
operationName:TextNoauto-generatedThe named GraphQL operation string (e.g. GetUser). If omitted, the compiler generates a name from the gnomon operation name.
selection:TextYes—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>Noall input fieldsNames 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 in action declarations where the result informs mutations but is not itself a mutation.
  • Caching: query operations MAY be cached by the runtime (implementation-defined). mutation and subscription operations 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 in action declarations. The result is bound and used in the mutations {} 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 as transient.

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> where T is the per-event type. The compiler emits M27711 if operationType: subscription is declared but the returns type is not Stream<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 typeGraphQL scalarJSON encoding
TextStringJSON string
IntegerIntJSON number (integer)
DecimalFloatJSON number (float)
BooleanBooleanJSON boolean
List<T>[T]JSON array
custom recordinput object typeJSON 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:

  1. If extensions.code is present and matches a selector declared in the operation’s errors {} block, the matching error classification is applied.
  2. 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:

  1. Returns the data portion, deserialized against the returns schema. Fields absent from data due to errors are set to their zero values.
  2. Emits M27710 for each entry in the errors array. Each M27710 diagnostic carries the error message, path, and extensions.code if present.
  3. 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.

CodeSeverityDescription
M27710WarningGraphQL partial result: both data and errors are present in the response. The operation succeeded, but some fields may be missing or null.
M27711ErroroperationType: 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 {}).
M27712Errorselection: slot missing from a GraphQL operation.
M27713ErrorA $variableName token referenced in the selection: string is not declared in the effective variables: list (explicit or implicit).

7.1 Failure Mode Summary

CodeDescriptionSeverity
M27710GraphQL partial resultWarning
M27711Missing operationType:, subscription return type mismatch, or unhandled hard errorError
M27712Missing selection: slotError
M27713Variable referenced in selection not in variable setError

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