RFC-0028 · OpenAPI Schema 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.openapi module — the OpenAPI 3.x schema adapter. When a client declaration uses spec: openapi("./path/to/spec.yaml"), the compiler invokes this adapter at compile time to parse the spec and generate a set of gnomon.io.http operations registered on the client.
The adapter implements the adapter protocol defined in RFC-0024 §6. It owns no runtime behavior. Its sole responsibility is to read an OpenAPI document, resolve all $ref references, and produce OperationDefinition and TypeDefinition values in the form the compiler expects.
// Example usage
imports {
gnomon.io.http: "^1.0.0"
gnomon.io.openapi: "^1.0.0"
}
client WorkOS {
meaning: "WorkOS user management API."
spec: openapi("./specs/workos-v2.yaml")
baseUrl: "https://api.workos.com"
auth: bearer-token
}
After adaptation, WorkOS.listUsers, WorkOS.getUser, and so on are available as named operations in execute {} blocks and saga steps exactly as if they had been hand-authored.
2. Adapter Function Signature
// Exported by gnomon.io.openapi; called via spec: openapi(arg)
// path is resolved relative to the declaring .gnm file
function openapi(path: string): SpecImport
path may point to a YAML or JSON file. The adapter detects the format from the file extension (.yaml, .yml, .json). Files without a recognized extension are treated as YAML. Path resolution follows the same rules as import path resolution in RFC-0001 §4: the path is relative to the .gnm file containing the client declaration, not to the project root.
3. OpenAPI Version Support
The adapter reads the openapi: field at the root of the document to determine the specification version.
| Version | Support level |
|---|---|
| 3.0.x | Supported |
| 3.1.x | Supported |
| 2.x (Swagger) | Not supported — emits M28801 (error) |
| 1.x | Not supported — emits M28801 (error) |
Version detection is strict: if the openapi: field is absent or not a string beginning with 3., the adapter MUST emit M28801 and MUST halt.
OpenAPI 3.1 is a superset of 3.0 for the constructs this adapter handles. The primary difference the adapter MUST account for is that 3.1 uses JSON Schema draft 2020-12 vocabulary (including unevaluatedProperties, prefixItems, and the divergence of nullable → null type union). The adapter MUST normalize these differences before type mapping (§4).
4. Type Mapping
Every field in an OpenAPI schema MUST be mapped to an gnomon Value type (RFC-0006 §4.A). The adapter MUST apply the following rules in order. The first matching rule wins.
| OpenAPI schema construct | gnomon type |
|---|---|
type: string (no format) | Text |
type: string, format: date | Date |
type: string, format: date-time | Timestamp |
type: string, format: binary | Binary |
type: integer | Integer |
type: number | Decimal |
type: boolean | Boolean |
type: array | List<T> where T is the mapped items type |
$ref to a named schema in components/schemas | The gnomon TypeDefinition name for that schema (see §6) |
type: object with a $ref | The resolved TypeDefinition name |
type: object (inline, no $ref) | Anonymous record; the compiler inlines the fields directly into the containing input or output schema |
oneOf / anyOf | variant (RFC-0008 §6.5); each branch is a named arm mapped by its schema title, or Branch1…BranchN if no title is present |
allOf | Merged record; the adapter merges all branch fields into a single flat TypeDefinition |
nullable: true (OpenAPI 3.0) or type: ["...", "null"] (OpenAPI 3.1) | The base type mapped as an optional field (required: false) |
| Unrecognized schema construct | JSON fallback with M28802 warning |
4.1 Inline anonymous objects
When an OpenAPI schema defines type: object inline (without a $ref), the adapter MUST NOT invent a TypeDefinition name. Instead, it MUST expand the object’s properties as flat fields directly into the surrounding input {} or output schema. This mirrors what most OpenAPI code generators call “inlining.”
If the same anonymous schema appears in more than one location, each occurrence MUST be inlined independently; no deduplication is performed. Authors who want a shared type SHOULD use $ref to a named schema in components/schemas.
4.2 Nested List types
OpenAPI type: array MUST map to List<T>. If items is itself an array schema, the result is List<List<T>>. The adapter MUST recurse to any depth, but MUST emit M28802 if a recursion depth exceeds 8 (a pathological schema; falls back to List<JSON>).
5. Operation Generation
Each entry in the OpenAPI paths object, combined with its HTTP method, MUST produce one gnomon operation. The adapter MUST process all paths and all methods within each path.
5.1 Operation naming
The operation name MUST be determined as follows, in priority order:
- If the OpenAPI operation has an
operationIdfield, that value MUST be used directly as the operation name (preserving its casing). If the sameoperationIdappears more than once in the document, the adapter MUST emit M28803 (error) and MUST use the first occurrence. - If no
operationIdis present, the adapter MUST synthesize a name from the HTTP method and path: the method is lowercased, the path segments are joined in camelCase, and path parameter tokens ({id}) are stripped of braces. For example:GET /users/{id}→getUsersIdPOST /organizations/{orgId}/members→postOrganizationsOrgIdMembers
5.2 Input field generation
Input fields MUST be generated from three sources, merged in the following order (later sources MUST NOT shadow earlier ones; shadowing MUST emit M28803):
Path and query parameters (in: path, in: query) — each OpenAPI parameter object MUST become one input field. The field name MUST be the parameter name. The field type MUST be the mapped schema type (§4). Fields declared required: true in the parameter object MUST become required input fields; all others MUST be optional.
Header and cookie parameters (in: header, in: cookie) — these MUST also become input fields and MUST be passed through to the underlying gnomon.io.http operation. The compiler MUST mark these with an internal annotation so the HTTP binding knows to route them to the appropriate request location rather than the body.
Request body (requestBody) — if the operation declares a requestBody, the adapter MUST create a single input field named body. The field type MUST be resolved from the content["application/json"].schema entry. If no application/json content type is present, the adapter SHOULD fall back to content[*].schema (first match) and MUST emit a warning. If requestBody.required is true, the body field MUST be required; otherwise it MUST be optional.
5.3 Return type generation
The adapter MUST map HTTP response schemas to the gnomon returns type as follows:
responses["200"]orresponses["201"](whichever is present;200takes priority) — this MUST be the primary return type. The schema atcontent["application/json"].schemaMUST be mapped via §4.- Additional 2xx responses (
202,204, etc.) — their schemas MUST be merged into the return type as a union. If a 2xx response declares no body (204 No Content), the merge MUST producevoidas a possible return arm, which the compiler represents as an optional return. - If both
200and201are present, their schemas MUST be unioned.
5.4 Error mapping
HTTP status codes in the responses block outside the 2xx range MUST be added to the errors {} block of the generated operation. The adapter MUST use the following default mapping:
| Status code range | Default error class |
|---|---|
| 400 | terminal |
| 401, 403 | terminal |
| 404 | terminal |
| 409 | terminal |
| 422 | terminal |
| 429 | transient |
| 4xx (other) | terminal |
| 500, 502, 503, 504 | transient |
| 5xx (other) | transient |
timeout | transient |
network | transient |
Authors MAY override any of these defaults in the errors {} block on the parent client declaration. Operation-level overrides (if hand-editing the generated client is ever supported) MUST take priority over client-level defaults, which MUST take priority over adapter defaults, following RFC-0024 §4 specificity rules.
6. Component Schema Registration
Every entry in components/schemas MUST be parsed into an gnomon TypeDefinition and MUST be registered in the type namespace as <ClientName>.<SchemaName>.
For example, given:
components:
schemas:
User:
type: object
properties:
id:
type: string
email:
type: string
format: email
with a client WorkOS { ... }, the adapter MUST register WorkOS.User as a TypeDefinition with fields id: Text and email: Text.
Schema registration MUST follow these rules:
- Nested
$refwithin component schemas MUST be resolved recursively. Circular references MUST be detected and MUST produce M28804 (error). - If a component schema name conflicts with an existing type name in the project’s type namespace, the compiler MUST emit M24423 (defined in RFC-0024 §7).
- Schema names that are not valid gnomon identifiers MUST be normalized to camelCase by the adapter. The original name MUST be preserved in the type’s
meaningfield. allOfcomposition within a component schema MUST be resolved by the adapter before registration; the resulting TypeDefinition MUST contain the merged field set.
7. Security Scheme Mapping
OpenAPI securitySchemes declared in components/securitySchemes MUST be mapped to gnomon auth schemes. The mapping MUST be applied to the parent client’s auth: slot as follows:
| OpenAPI security scheme type | gnomon auth: value |
|---|---|
http + scheme: bearer | bearer-token |
apiKey | api-key |
http + scheme: basic | basic |
oauth2 | bearer-token (token acquisition is out of scope; the caller supplies the token) |
openIdConnect | bearer-token (same rationale as oauth2) |
The adapter MUST NOT override an auth: value already declared on the client. If the client declares auth: explicitly, the adapter MUST respect that declaration and MUST ignore the security scheme. If no auth: is declared on the client and the spec’s security array references exactly one scheme, the adapter MUST infer the auth: value from the mapping above.
If the spec’s security array references multiple schemes or per-operation security overrides are present, the adapter MUST emit an informational note and MUST use the first scheme. Per-operation auth overrides are not representable in the current gnomon client model.
8. Lockfile
The adapter contributes an entry to gnomon.lock (RFC-0024 §6.3) with the following values:
{
"clientName": "WorkOS",
"adapterModule": "gnomon.io.openapi",
"specHash": "sha256:<hex>",
"specSource": "./specs/workos-v2.yaml",
"resolvedAt": "2026-01-01T00:00:00Z",
"operationCount": 42
}
The specHash MUST be the SHA-256 hash of the spec file contents after $ref resolution and normalization — that is, the hash MUST be computed over the fully dereferenced document, not the raw file bytes. This ensures that changes to an $ref-referenced external file are detected even if the root spec file is unchanged.
The adapter MUST re-parse the spec only when the computed hash differs from the lockfile entry. If the spec file is unreachable and no lockfile entry is present, the compiler MUST emit M24420 (RFC-0024 §7). If the spec file is unreachable but a valid lockfile entry exists, the adapter MUST use the cached operation set and MUST emit M24421 (info).
9. Diagnostic Codes
This RFC owns the M28xxx diagnostic code range.
| Code | Description | Severity |
|---|---|---|
| M28800 | OpenAPI spec file not found at declared path | Error |
| M28801 | Unsupported OpenAPI version; must be 3.0.x or 3.1.x | Error |
| M28802 | OpenAPI schema type cannot be mapped to an gnomon type; field falls back to JSON | Warning |
| M28803 | Duplicate operationId in spec; first occurrence is used | Error |
| M28804 | $ref target is not resolvable within the spec; field falls back to JSON | Error |
10. Failure Mode Summary
| Code | Description | Severity |
|---|---|---|
| M28800 | Spec file not found | Error |
| M28801 | Unsupported OpenAPI version | Error |
| M28802 | Unmappable schema type (JSON fallback) | Warning |
| M28803 | Duplicate operationId | Error |
| M28804 | Unresolvable $ref | 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 |