gnomonlearn
Docs/RFC-0028/Design Q&A

RFC-0028 · 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.

← Read the authored RFC

Q: How are nullable values distinguished from optional fields?

Status: Open

Source: RFC-0028 §4; RFC-0024 §6.1 FieldDef Issue: The type map converts OpenAPI nullable: true or a null union into required: false. This collapses a present null value into an absent field, although OpenAPI requiredness and nullability are independent. Recommendation: Model required and nullable separately in the adapter result schema and preserve both when mapping fields and return types.

Q: Which type rule wins for formatted strings?

Status: Answered by current source; implementation verification pending

Source: RFC-0028 §4

A: The generic string row explicitly applies only when there is no format. The date, date-time, and binary rows therefore remain reachable under first-match ordering. The prior issue description omitted that qualifier. Test each format against 3.0 and 3.1 schemas; this source clarification does not resolve the separate nullable/requiredness issue above.

Q: What is the return type when both 200 and 201 responses are declared?

Status: Open

Source: RFC-0028 §5.3 Issue: The first rule selects 200 over 201 when both exist, while the final rule says both schemas MUST be unioned. Those instructions produce different return types. Recommendation: Generate a discriminated response variant for each success status, including a void arm for 204, or specify a stable union rule that preserves status information.

Status: Open

Source: RFC-0028 §5.2; RFC-0025 §§2.2, 4 Issue: The adapter generates cookie input fields with an internal routing annotation, but the HTTP binding defines only path, query, body, and header locations. The compiler cannot map a generated cookie parameter to a specified request location. Recommendation: Extend the HTTP binding with cookie routing and encoding rules, or reject cookie parameters with a dedicated diagnostic until supported.

Q: How are multiple or per-operation security requirements preserved?

Status: Open

Source: RFC-0028 §7; RFC-0024 §4 Issue: OpenAPI security arrays can express alternatives and combined schemes, and operations may override root security. This RFC chooses the first scheme and ignores per-operation overrides, potentially publishing a client contract that sends the wrong credentials. Recommendation: Model per-operation security requirements with explicit alternatives and combinations, or reject unsupported documents instead of silently selecting the first scheme.