RFC-0033 · Design Q&A
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.
Q: What authentication scheme applies when auth is omitted?
Status: Open
Source: RFC-0033 §6.3; invariants 6 and 8
Issue: Omitting auth defaults to required: true, but no default schemes list is defined. A caller must authenticate, yet the runtime has no accepted scheme. The grammar also permits required: true with schemes [none].
Recommendation: Require at least one concrete scheme whenever authentication is required, define an explicit default only if it is safe across bindings, and reject required: true with none.
Q: Is a draft api externally reachable?
Status: Open
Source: RFC-0033 §§3, 6.1, 7–8
Issue: An api is defined as the external public surface, and only listed operations are externally reachable. The example calls draft api BenefitsAdminAPI “not exposed to external callers” even though it has an exposes block. The runtime and publish treatment of draft APIs is unspecified.
Recommendation: Define whether draft APIs are excluded from published bindings, restricted to a named audience, or reachable with draft status. Align the example and generated routing rules with that choice.
Q: Can errors.common name imported qualified types?
Status: Open
Source: RFC-0033 §5 grammar, §6.4, §7 example
Issue: The grammar accepts only IDENT entries, while the example uses gnomon.errors.NotFound and other qualified names. The compiler needs an unambiguous import-resolution rule for common error types.
Recommendation: Use a qualified type-reference grammar shared with other Gnomon declarations and validate each reference before stub generation.
Q: Is query-parameter API-key authentication permitted for a public API?
Status: Open
Source: RFC-0033 §6.3; RFC-0034 bindings
Issue: The api-key scheme permits ?apiKey=<key> alongside a header. URLs are commonly copied into logs and traces, and the RFC does not define how a server binding controls or disables this form.
Recommendation: Make the header form canonical and disallow query-parameter credentials unless a separate explicit compatibility policy specifies redaction and transport constraints.