gnomonlearn
Docs/RFC-0028 OpenAPI adapter RDF model proposal

RFC-0028 OpenAPI adapter RDF model proposal

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.

This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.

Status: proposed RDF repair, 2026-10-03. Owner: spec and compiler. No Gnomon deployment exists, but RDF subject IRIs and classes are public contract candidates and need an owner decision before publication.

Source-bound evidence

All 48 RFC-0028 domain nodes have review verdicts in kg/projection-reviews.textproto. The first eight cover shared identity: gnomon.io.openapi matches the authored RFC and Lean catalog; seven mismatch:

RDF subjectsAuthored contractCurrent projection issue
capability/api-key, capability/basic, capability/bearer-tokenRFC-0028 §7 maps OpenAPI security schemes to client.auth: values; RFC-0024 §4 defines auth-scheme syntax.rdf:type domain:Capability means a permission scope in the domain ontology, not an authentication scheme. The same subjects recur in RFC-0031.
declaration/clientRFC-0024 §1 and RFC-0006 §4.B classify client with Operations. A client may have authored operations or use an adapter.kindClass "Surface" and the adapter-only summary narrow and misclassify the shared declaration identity. This subject recurs in seven RFC projections.
effect/adapter.callRFC-0028 §§1–2 describe a compile-time openapi(path): SpecImport function and state that the adapter owns no runtime behavior.rdf:type domain:EffectKind makes a compiler call look like an executable language effect. The subject recurs in four RFC projections.
module/gnomon.io.httpRFC-0025 §1 defines the HTTP protocol binding, which RFC-0028 imports and uses.The RFC-0028 node says definedIn RFC-0028, giving the shared module two owners.
operation/openapiRFC-0028 §2 defines a compile-time adapter function used in spec:.rdf:type domain:Operation conflates it with a runtime client.operations {} invocation.

The next 22 reviews cover the adapter invariants. Eighteen match the authored and Lean rules. Four mismatch: the array-depth, circular-reference, and input-shadowing invariants cite diagnostic codes with narrower catalog definitions, and the path-resolution invariant points to the misclassified operation/openapi node. Of the last 18 client-slot and type nodes, nine match and nine mismatch:

RDF subjectsSource conflict
field/client/auth, field/client/baseUrlRFC-0024 §4 owns the shared client connection slots, but these nodes say definedIn RFC-0025; their summaries also narrow the slots to generated HTTP operations.
type/BinaryRFC-0028 §4 and RFC-0030 map external binary formats to Binary, while RFC-0006 §4.A calls its Value hierarchy complete and has no Binary member. The RDF claim that RFC-0006 defines it is unsupported.
type/JSON, type/List, type/variantThese are RFC-0006 Value concepts. The JSON and variant nodes assign later RFC ownership; the List node shares an IRI with RFC-0006 but changes canonical fqn from List to List<T>.
type/OperationDefinition, type/SpecImport, type/TypeDefinitionRFC-0024 §6 defines compiler adapter interchange structures and an opaque token; the domain projection types them as author-facing Gnomon DataType values.

The nine matching nodes are client.meaning, client.spec, Boolean, Date, Decimal, Integer, Text, Timestamp, and abstract Value. Across all 48 nodes, 28 match and 20 mismatch. These verdicts evaluate source meaning; they do not establish adapter runtime behavior or approve an RDF migration.

Diagnostic code conflicts

CodeCatalog in RFC-0028 §9Other authored use
M28802Unmappable schema type, warning, JSON fallback.§4.2 uses it for nested array depth over eight with List<JSON> fallback; the same paragraph also says recursion works to any depth.
M28803Duplicate operationId, error, first occurrence retained.§5.2 uses it when later input sources shadow earlier fields; first-occurrence operation naming does not describe field merging.
M28804Unresolved $ref target, error, JSON fallback.§6 uses it for circular $ref references, without defining whether a fallback is produced or compilation stops.

Recommend: reserve M28802/03/04 for their current §9 catalog meanings and assign distinct provisional codes M28805/06/07 to array-depth overflow, input-field shadowing, and circular references, respectively; those three codes have no occurrences in the current spec corpus. State explicitly that array mapping is recursive up to depth eight and emits a warning plus List<JSON> fallback beyond that limit. Keep shadowing and circular references as errors, with an explicit halt or recovery rule for each. The alternative is to expand the three existing code definitions to multiple trigger types and define a trigger discriminator in the structured diagnostic payload. Either choice changes a public diagnostic contract and requires the owner’s decision before editing RFCs, Lean, RDF, and fixtures.

Define an AuthScheme concept in the domain ontology (or a typed enum-value model if the schema design requires it), and give the three auth values subjects under that category. Keep an explicit old-to-new IRI mapping in the publication notes because simply changing rdf:type on the existing capability/* subjects would preserve misleading identities. Align the same model in RFC-0031.

Keep one shared declaration/client subject with RFC-0024 ownership, the Operations class, and a summary that covers both authored and adapter-produced operations. Model compile-time adapter invocation as a function or compiler step with an IRI distinct from runtime effects, and model openapi(path) as that adapter function, not a client operation. Make gnomon.io.http retain RFC-0025 ownership in every projection; use a separate usedBy or dependency edge from RFC-0028 rather than duplicating definedIn ownership. Preserve the gnomon.io.openapi module identity.

Give shared client.auth and client.baseUrl slots RFC-0024 ownership and descriptions that cover both authored and adapter-generated operations. Resolve Binary as a core scalar in RFC-0006 or change the RFC-0028/0030 mapping to an existing Value type; this is an author-facing type decision. Use one RFC-0006 owner and canonical FQN for JSON, List, and variant across their shared subjects. Represent OperationDefinition, TypeDefinition, and SpecImport as versioned compiler interchange messages and an opaque token, with protobuf messages for any value that crosses process or file boundaries; keep them distinct from author-writable Value types.

Acceptance before normative RDF release

  1. Decide the auth-scheme class and the distinct function/compiler-step identity. Inventory every shared occurrence of these eight subjects in claim and domain projections, query templates, generated TTL, and known consumers before changing an IRI or class.
  2. Decide whether to split or broaden M28802/03/04. Define severity, fallback or halt behavior, structured fields, and precedence for each trigger, including the array-depth limit. Add fixtures for each trigger and verify the diagnostic catalog has one complete definition per code.
  3. Decide the Binary mapping and the canonical subject/FQN for shared value types. Specify compiler interchange schemas separately from the Value hierarchy and make the client slot owner unambiguous.
  4. Apply the chosen model to RFC-0006, RFC-0008, RFC-0024/0025/0028/0029, RFC-0031/0034/0043 as applicable. Preserve authored provenance and regenerate Turtle from protobuf sources. Update Lean summaries only where the authored meaning itself changes.
  5. Re-review every affected source-bound node and test SPARQL result changes with the checked-in query suite. Verify domain identity, link, projection, corpus, and site gates. External RDF consumers still need a publication review; no production migration is needed because nothing is deployed.