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 subjects | Authored contract | Current projection issue |
|---|---|---|
capability/api-key, capability/basic, capability/bearer-token | RFC-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/client | RFC-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.call | RFC-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.http | RFC-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/openapi | RFC-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 subjects | Source conflict |
|---|---|
field/client/auth, field/client/baseUrl | RFC-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/Binary | RFC-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/variant | These 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/TypeDefinition | RFC-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
| Code | Catalog in RFC-0028 §9 | Other authored use |
|---|---|---|
| M28802 | Unmappable 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. |
| M28803 | Duplicate 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. |
| M28804 | Unresolved $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.
Recommended first-release model
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
- 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.
- 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.
- Decide the
Binarymapping and the canonical subject/FQN for shared value types. Specify compiler interchange schemas separately from the Value hierarchy and make theclientslot owner unambiguous. - 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.
- 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.