RFC-0031 · GraphQL Introspection Adapter
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 the gnomon.io.graphql-introspect module — the GraphQL introspection adapter. When a client declaration uses spec: graphqlIntrospect("https://api.example.com/graphql") or spec: graphqlSchema("./schema.graphql"), the compiler invokes this adapter at compile time to obtain the GraphQL schema and generate gnomon.io.graphql operations registered on the client.
This RFC is distinct from RFC-0027 (GraphQL protocol binding) in the same way RFC-0030 (Protobuf adapter) is distinct from RFC-0026 (gRPC binding). RFC-0027 defines how the gnomon runtime executes GraphQL operations. This RFC defines how the adapter imports a GraphQL schema at compile time to produce those operations.
Two source forms are supported:
graphqlIntrospect(url)— sends the standard GraphQL introspection query to a live endpoint at compile time and derives the schema from the response.graphqlSchema(path)— parses a local Schema Definition Language (SDL) file without any network request.
// Example: introspection from a live endpoint
imports {
gnomon.io.graphql: "^1.0.0"
gnomon.io.graphql-introspect: "^1.0.0"
}
client GitHub {
meaning: "GitHub GraphQL API."
spec: graphqlIntrospect("https://api.github.com/graphql")
auth: bearer-token
}
// Example: local SDL file
client Shopify {
meaning: "Shopify Storefront API."
spec: graphqlSchema("./specs/shopify.graphql")
baseUrl: "$SHOPIFY_GRAPHQL_URL"
auth: bearer-token
}
2. Adapter Function Signatures
// Exported by gnomon.io.graphql-introspect
// Query a live endpoint for its schema via the GraphQL introspection protocol
function graphqlIntrospect(url: string): SpecImport
// Parse a local SDL file (.graphql or .gql)
// path is resolved relative to the declaring .gnm file
function graphqlSchema(path: string): SpecImport
Both functions return an opaque SpecImport token. The compiler resolves this token by invoking the adapter’s resolve() method (RFC-0024 §6.1) during the compilation phase.
For graphqlIntrospect, url must be an absolute HTTP or HTTPS URL. Relative URLs are not permitted and emit M31100 (error). The URL may contain no path component, in which case the adapter appends /graphql as a default.
For graphqlSchema, path is resolved relative to the directory of the declaring .gnm file, using the same resolution rules as RFC-0001 §4. The file must have a .graphql or .gql extension; other extensions emit M31101 (error).
3. Introspection Query
When graphqlIntrospect is used, the adapter sends the standard GraphQL introspection query as an HTTP POST to the specified URL with Content-Type: application/json.
The query requests the following fields from __schema:
{
__schema {
queryType { name }
mutationType { name }
subscriptionType { name }
types {
kind
name
description
fields(includeDeprecated: true) {
name
description
args {
name
description
type { ...TypeRef }
defaultValue
}
type { ...TypeRef }
isDeprecated
deprecationReason
}
inputFields {
name
description
type { ...TypeRef }
defaultValue
}
interfaces { ...TypeRef }
enumValues(includeDeprecated: true) {
name
description
isDeprecated
deprecationReason
}
possibleTypes { ...TypeRef }
}
}
}
fragment TypeRef on __Type {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
ofType {
kind
name
}
}
}
}
}
}
The adapter requires the following fields to be present in the response: name, kind, fields, inputFields, enumValues, possibleTypes, and ofType. If any required field is absent from the introspection response (for example, because the server has disabled introspection or is running a partial implementation), the adapter emits M31103 (error).
Built-in types (names beginning with __) are excluded from type registration.
4. Auth for Introspection
The HTTP request that the adapter sends for introspection is a compile-time operation, not a runtime operation. RFC-0025 §3 governs runtime credential resolution for live HTTP calls; it does not apply here. Instead, the adapter resolves credentials for the introspection request directly from the build environment using the following compile-time rules:
bearer-token— the adapter reads the token from the environment variable<ClientName>_TOKEN(uppercased, with dots replaced by underscores) in the build environment. If found, it addsAuthorization: Bearer <token>to the introspection request.api-key— the adapter reads the key from the environment variable<ClientName>_API_KEYand adds it as theX-Api-Keyheader.basic— the adapter reads<ClientName>_USERNAMEand<ClientName>_PASSWORDand addsAuthorization: Basic <base64(user:pass)>.none— no auth header is added.
These environment variables must be available in the build environment at compile time. If a required variable is not set, the introspection request is sent without auth, which may result in a 401 response and M31100 (error). This compile-time credential lookup is intentionally separate from the runtime credential store (RFC-0025 §3.1), which is resolved at call time by the runtime, not the compiler.
5. SDL File Parsing
When graphqlSchema(path) is used, the adapter reads the file at the resolved path and parses it as GraphQL SDL using the reference GraphQL parser. The parser is run in strict mode: syntax errors produce M31104 (error) with the line and column number from the parser’s error output.
The adapter supports:
type,input,enum,union,interface,scalardefinitionsextend typeandextend inputdefinitions (merged before type mapping)schema { query: ... mutation: ... subscription: ... }declarations- Directives (ignored; the adapter does not interpret directives for schema logic)
The adapter does not support:
@deprecatedaffecting operation generation (deprecated fields are included but marked in the TypeDefinition description)- Federation SDL extensions (
@key,@external, etc.) — ignored with an informational note - Executable document syntax (
query { ... }) — emits M31104
If no explicit schema { ... } declaration is present, the adapter applies the GraphQL specification default: the query root type is named Query, the mutation root type is Mutation, and the subscription root type is Subscription.
6. Type Mapping
Every GraphQL type is mapped to an gnomon Value type (RFC-0006 §4.A) or TypeDefinition. The adapter applies the following mapping:
| GraphQL SDL type | gnomon type | Notes |
|---|---|---|
String | Text | |
ID | Text | ID is always treated as an opaque string |
Int | Integer | |
Float | Decimal | |
Boolean | Boolean | |
type (object type) | TypeDefinition | Registered as <ClientName>.<TypeName> |
input | TypeDefinition | Registered as <ClientName>.<TypeName>; flagged as input-only |
enum | variant with Text values | Enum values become the variant arms |
union | variant | Each member type becomes a named arm |
interface | variant | Resolved to concrete types via possibleTypes (from introspection) or implementing types (from SDL) |
scalar (custom) | JSON | Emits M31102 (warning); no semantic mapping is available |
T! (non-null modifier) | Required field (required: true) | Absence of ! means optional |
[T] | List<T> | List nullability ([T]!, [T!], [T!]!) is normalized: the list field is required if the outermost ! is present; list elements are non-null if the inner ! is present |
6.1 Nullability normalization
GraphQL’s nullability rules are more granular than gnomon’s. The adapter normalizes as follows:
T(nullable) → optional field (required: false)T!(non-null) → required field (required: true)[T]→List<T>with optional field[T!]→List<T>(elements guaranteed non-null; this is a runtime constraint, not reflected in the gnomon type)[T]!→List<T>required field[T!]!→List<T>required field
6.2 Interface resolution
GraphQL interface types are mapped to variant with one arm per concrete implementing type, using possibleTypes from the introspection response or the implements keyword from SDL. If no implementing types are known at compile time, the interface is mapped to JSON with M31102 (warning).
7. Root Type to Operation Mapping
The three GraphQL root types produce operations with distinct semantics:
| GraphQL root type | gnomon operation semantics | Notes |
|---|---|---|
Query root type fields | Read-only operations | Each field on the query root type becomes one operation |
Mutation root type fields | Side-effecting operations | Each field on the mutation root type becomes one operation |
Subscription root type fields | Streaming operations returning Stream<T> | Each field on the subscription root type becomes one operation; integrates with RFC-0020 reactive query model |
Each field on a root type becomes one gnomon operation. The operation name is the field name, preserved as-is (GraphQL field names are conventionally camelCase). The adapter does not transform operation names.
If the schema has no mutation root type, no mutation operations are generated. If the schema has no subscription root type, no subscription operations are generated. A schema with no query root type is invalid per the GraphQL specification; the adapter emits M31103 if the query root type is absent.
8. Argument Mapping
GraphQL field arguments become input fields of the generated operation. Argument types are mapped via §6.
Argument ordering is preserved from the schema declaration. Required arguments (T!) become required input fields; optional arguments (T) become optional input fields with the default value, if declared, preserved in the field’s description.
For Query root fields, the entirety of the operation’s input is derived from the field’s arguments. For Mutation root fields, the same applies. There is no separate concept of a request body in GraphQL; all input flows through arguments.
The generated operation’s returns type is the mapped type of the field’s return type. If the return type is an object type, it is registered as a TypeDefinition (§6). If the return type is a scalar, it is mapped directly. If the return type is a union or interface, it is mapped to a variant.
9. Lockfile
The adapter contributes an entry to gnomon.lock (RFC-0024 §6.3).
For graphqlIntrospect(url):
- The
specHashis the SHA-256 of the canonical introspection JSON, computed after:- Parsing the response body as JSON.
- Extracting only the
data.__schema.typesarray (the authoritative schema content). - Removing all
__typenamefields. - Sorting the types array by
namelexicographically. - Sorting
fields,inputFields, andenumValuesarrays within each type byname. - Serializing to compact JSON with no whitespace.
- This normalization ensures that cosmetic differences in the server’s introspection response (field ordering, whitespace) do not cause spurious hash changes.
For graphqlSchema(path):
- The
specHashis the SHA-256 of the raw file contents.
{
"clientName": "GitHub",
"adapterModule": "gnomon.io.graphql-introspect",
"specHash": "sha256:<hex>",
"specSource": "https://api.github.com/graphql",
"resolvedAt": "2026-01-01T00:00:00Z",
"operationCount": 156
}
10. Caching and Refresh
Introspection is performed once per build, at compile time. The lockfile prevents re-querying on unchanged schemas: if the specHash stored in gnomon.lock matches the hash computed from the current introspection response or file, the adapter uses the cached operation set without re-parsing.
The lockfile MUST be committed to version control. This ensures that:
- Builds in CI environments without network access to the GraphQL endpoint can still compile, using the cached operation set.
- Schema changes are detected by comparing the hash of the new response against the committed lockfile hash.
To force re-introspection (for example, after a known schema update), pass the --refresh-specs flag to gnomon build. This flag causes the adapter to ignore the lockfile hash and re-query all spec-backed clients, updating the lockfile with the new hashes.
If graphqlIntrospect is used and the endpoint is unreachable at build time, and no lockfile entry is present, the compiler emits M24420 (RFC-0024 §7, error). If a lockfile entry is present, the adapter uses the cached operation set and emits M24421 (RFC-0024 §7, info).
11. Diagnostic Codes
This RFC owns the M31xxx diagnostic code range.
| Code | Description | Severity |
|---|---|---|
| M31100 | GraphQL introspection request failed (network error, non-200 response, or malformed JSON) | Error |
| M31101 | GraphQL SDL file not found at declared path | Error |
| M31102 | GraphQL type cannot be mapped to an gnomon type; field falls back to JSON (custom scalars, unresolvable interfaces) | Warning |
| M31103 | Introspection response is missing required fields, or query root type is absent | Error |
| M31104 | SDL parse error; file contains invalid GraphQL syntax | Error |
12. Failure Mode Summary
| Code | Description | Severity |
|---|---|---|
| M31100 | Introspection request failed | Error |
| M31101 | SDL file not found | Error |
| M31102 | Unmappable GraphQL type (JSON fallback) | Warning |
| M31103 | Introspection response missing required fields | Error |
| M31104 | SDL parse error | Error |
| M24420 | Spec unreachable, no lockfile entry (from RFC-0024) | Error |
| M24421 | Spec unreachable, using lockfile cache (from RFC-0024) | Info |
| M24422 | Adapter produced zero operations (from RFC-0024) | Warning |
| M24423 | Generated type name conflicts with existing type (from RFC-0024) | Error |