gnomonlearn
Docs/RFC-0028/Reference catalog

RFC-0028 · Reference catalog

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.

← Read the authored RFC

Generated reference catalog. This page renders structured Lean data for RFC-0028: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0028.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0028. Edit that source and regenerate this catalog.


Title: OpenAPI Schema Adapter
Status: draft
Diagnostic range: M28800-M28899

Depends on: RFC-0001, RFC-0006, RFC-0008, RFC-0024, RFC-0025

Proof citations in source: 19 / 19. Standalone proof verification is pending.


Definitions

(none defined)

Diagnostics

CodeSeverityDescription
M28800ErrorOpenAPI spec file not found at declared path
M28801ErrorUnsupported OpenAPI version; must be 3.0.x or 3.1.x
M28802WarningOpenAPI schema type cannot be mapped to an gnomon type; field falls back to JSON
M28803ErrorDuplicate operationId in spec; first occurrence is used
M28804Error$ref target is not resolvable within the spec; field falls back to JSON

Dependency neighborhood

graph LR
  nRFC_0028["RFC-0028"]
  nRFC_0001["RFC-0001"]
  nRFC_0028 --> nRFC_0001
  nRFC_0006["RFC-0006"]
  nRFC_0028 --> nRFC_0006
  nRFC_0008["RFC-0008"]
  nRFC_0028 --> nRFC_0008
  nRFC_0024["RFC-0024"]
  nRFC_0028 --> nRFC_0024
  nRFC_0025["RFC-0025"]
  nRFC_0028 --> nRFC_0025

Invariants

  1. An inline type:object schema without a $ref must not produce a TypeDefinition; its properties must be expanded as flat fields into the surrounding input or output schema, with no deduplication across occurrences. (enforced by: compile-time)
  2. Duplicate operationId values in a spec must emit M28803 and the first occurrence must be used. (enforced by: compile-time)
  3. Each combination of an OpenAPI paths entry and HTTP method must produce exactly one gnomon operation, processing all paths and methods. (enforced by: compile-time)
  4. Every OpenAPI schema field must be mapped to an gnomon Value type by applying the type-mapping rules in order, with the first matching rule winning. (enforced by: compile-time)
  5. Every entry in components/schemas must be parsed into a TypeDefinition and registered in the type namespace as .. (enforced by: compile-time)
  6. Header and cookie parameters must become input fields and be marked with an internal annotation so the HTTP binding routes them to the proper request location rather than the body. (enforced by: compile-time)
  7. If the openapi: field is absent or does not begin with ‘3.’, the adapter must emit M28801 and halt. (enforced by: compile-time)
  8. Input fields must be merged from path/query parameters, header/cookie parameters, and requestBody in that order, with later sources never shadowing earlier ones; shadowing must emit M28803. (enforced by: compile-time)
  9. Nested $ref within component schemas must be resolved recursively and circular references must be detected and produce M28804. (enforced by: compile-time)
  10. Nested OpenAPI array schemas must map to nested List to any depth, but recursion exceeding depth 8 must emit M28802 and fall back to List. (enforced by: compile-time)
  11. Non-2xx response status codes must populate the operation’s errors block using the adapter’s default terminal/transient classification, overridable by client-level errors with operation overrides taking highest priority. (enforced by: compile-time)
  12. Operation names must use the OpenAPI operationId verbatim when present; otherwise must be synthesized from lowercased method and camelCased path segments with parameter braces stripped. (enforced by: compile-time)
  13. Schema names that are not valid gnomon identifiers must be normalized to camelCase, with the original name preserved in the type’s meaning field. (enforced by: compile-time)
  14. The adapter must normalize OpenAPI 3.1 JSON Schema 2020-12 differences (unevaluatedProperties, prefixItems, nullable-as-null-union) before type mapping. (enforced by: compile-time)
  15. The adapter must not override an auth: value already declared on the client; an explicit auth: declaration causes the spec security scheme to be ignored. (enforced by: compile-time)
  16. The adapter must re-parse the spec only when the computed dereferenced hash differs from the lockfile entry; an unreachable spec with no lockfile entry emits M24420 and with a valid lockfile entry uses the cache and emits M24421. (enforced by: compile-time)
  17. The lockfile specHash must be the SHA-256 of the spec after $ref resolution and normalization, not the raw file bytes, so changes to externally referenced files are detected. (enforced by: compile-time)
  18. The path argument to openapi() must be resolved relative to the .gnm file containing the client declaration, not the project root, following RFC-0001 import-path resolution rules. (enforced by: compile-time)
  19. The primary return type must be taken from responses 200 or 201 (200 takes priority); additional 2xx responses must be unioned into the return type, and bodyless 2xx responses must contribute void as a possible arm represented as an optional return. (enforced by: compile-time)
  20. When an operation declares a requestBody, the adapter must create a single input field named body whose type comes from content[application/json].schema, falling back with a warning to the first content[*].schema if absent. (enforced by: compile-time)
  21. When no auth: is declared and the spec security array references exactly one scheme, the adapter must infer auth: from the OpenAPI-to-gnomon auth mapping; multiple schemes or per-operation overrides emit an informational note and the first scheme is used. (enforced by: compile-time)
  22. allOf composition within a component schema must be resolved by the adapter before registration so the resulting TypeDefinition contains the merged field set. (enforced by: compile-time)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

Adapter Function Signature

  1. MUST — Spec path resolution is relative to the .gnm file containing the client declaration, not the project root.

Component Schema Registration

  1. MUST — Emit M24423 when a component schema name conflicts with an existing project type name. (proof citation: rfc0028_b9_grounded; verification pending)
  2. MUST — Normalize schema names that are not valid gnomon identifiers to camelCase, preserving the original name in the type’s meaning field.
  3. MUST — Parse each components/schemas entry into a TypeDefinition registered as ..
  4. MUST — Resolve allOf composition before registration so the TypeDefinition contains the merged field set. (proof citation: rfc0028_b31_grounded; verification pending)
  5. MUST — Resolve nested $ref recursively and detect circular references, producing M28804. (proof citation: rfc0028_b19_grounded; verification pending)

Lockfile

  1. MUST — Compute specHash as the SHA-256 of the fully $ref-resolved and normalized document, not raw file bytes.
  2. MUST — Re-parse the spec only when the computed hash differs from the lockfile entry. (proof citation: rfc0028_b7_grounded; verification pending)
  3. MUST — Use the cached operation set and emit M24421 when the spec is unreachable but a valid lockfile entry exists. (proof citation: rfc0028_b4_grounded; verification pending)

OpenAPI Version Support

  1. MUST — Emit M28801 and halt if the openapi field is absent or does not begin with ‘3.’. (proof citation: rfc0028_b45_grounded; verification pending)
  2. MUST — Normalize OpenAPI 3.1 JSON Schema 2020-12 differences (unevaluatedProperties, prefixItems, null type union) before type mapping.

Operation Generation

  1. MUST — Add non-2xx responses to the operation’s errors block using the default status-code-to-class mapping. (proof citation: rfc0028_b23_grounded; verification pending)
  2. MUST_NOT — Allow later input-source merges to shadow earlier ones; shadowing emits M28803. (proof citation: rfc0028_b38_grounded; verification pending)
  3. MUST — Convert header and cookie parameters into input fields with an internal annotation routing them to the correct request location rather than the body. (proof citation: rfc0028_b25_grounded; verification pending)
  4. MUST — Create a single input field named ‘body’ resolved from content[application/json].schema when requestBody is declared. (proof citation: rfc0028_b29_grounded; verification pending)
  5. MUST — Generate one input field per path/query parameter, named after the parameter and required iff the parameter is required. (proof citation: rfc0028_b27_grounded; verification pending)
  6. MUST — Map the primary return type from responses 200 (priority) or 201; union additional 2xx schemas, treating 204 No Content as a void arm (optional return). (proof citation: rfc0028_b41_grounded; verification pending)
  7. MUST — Produce one gnomon operation per (path, HTTP method) entry in the OpenAPI paths object. (proof citation: rfc0028_b2_grounded; verification pending)
  8. MUST — Synthesize the operation name from lowercased method plus camelCased path segments (with parameter braces stripped) when operationId is absent. (proof citation: rfc0028_b14_grounded; verification pending)
  9. MUST — Use operationId verbatim as the operation name when present; emit M28803 on duplicates and use the first occurrence. (proof citation: rfc0028_b33_grounded; verification pending)

Security Scheme Mapping

  1. MUST — Emit an informational note and use the first scheme when multiple schemes or per-operation security overrides are present.
  2. MUST — Infer auth: from the spec’s single security scheme when no auth: is declared on the client.
  3. MUST — Map components/securitySchemes entries to gnomon auth scheme values per the defined table.
  4. MUST_NOT — Override an auth: value already declared explicitly on the client. (proof citation: rfc0028_b0_grounded; verification pending)

Type Mapping

  1. SHOULD — Authors who want a shared type use $ref to a named schema in components/schemas.
  2. MUST — Inline each occurrence of an anonymous object schema independently with no deduplication.
  3. MUST_NOT — Invent a TypeDefinition name for inline anonymous object schemas; expand properties as flat fields into the surrounding schema. (proof citation: rfc0028_b36_grounded; verification pending)
  4. MUST — Map every OpenAPI schema field to an gnomon Value type, applying mapping rules in order with first match winning. (proof citation: rfc0028_b12_grounded; verification pending)
  5. MUST — Recurse into nested array items to any depth, but emit M28802 and fall back to List when depth exceeds 8. (proof citation: rfc0028_b43_grounded; verification pending)

Linked References

DirectionTarget
Depends onRFC-0001
Depends onRFC-0006
Depends onRFC-0008
Depends onRFC-0024
Depends onRFC-0025