OpenAPI 3.1 bidirectional fidelity — full import coverage + proper export (epic)

[tonydspaniard]

Context

Importing the real Swagger Petstore exposed that openapi:import (and its mirror, spec:emit-openapi) covers a useful subset of OpenAPI 3.1 and silently drops the rest. "The Petstore imports" was never proof of coverage — it imports ok=true while dropping every query parameter, every non-JSON body, all validation constraints, and all security. This epic tracks getting to bidirectional fidelity.

The standard (what "covered" means)

Literal 100% fidelity into generated code isn't achievable for a spec→code generator (callbacks, links, oneOf polymorphism, free-form additionalProperties have no clean Altair representation). The non-failing standard is:

Map everything representable; surface (warn/error) everything else — never silently drop. Emit spec-compliant OpenAPI on the way out. Round-trip stays stable.

Import coverage matrix (evidence-based, verified)

Mapped: objects (+nested), arrays, arrays-of-objects, top-level array bodies, scalars, enums→in:, internal $ref, properties/required, application/json bodies + responses, operationId/summary, x-altair-*.

Silently dropped (ok=true, no warning): query/header/cookie parameters (the parameters: array is never read); path-param schemas (always coerced to string); non-JSON bodies (multipart/form/xml/octet-stream); requestBody $ref and required; all validation constraints (format, min/maxLength, pattern, minimum/maximum, multipleOf, min/maxItems); additionalProperties, const, discriminator, not, prefixItems, nullable; security (schemes + requirements); servers, doc/op tags, deprecated, description, response headers/links, callbacks, webhooks (3.1), non-JSON responses.

Surfaced (errors/skips — not silent): external/file $ref, oneOf/anyOf/allOf in a request body, recursive $ref, bare scalar body.

Export gaps (spec:emit-openapi / OpenApiEmitter)

Mirror problems: all inputs emit into a single application/json request body (path/query/header distinction lost), validation rules are not emitted as schema constraints (email→format, min:3→minLength, in:→enum, regex→pattern), no security, no servers, path params not emitted as parameters.

Phased plan (each phase covers BOTH directions, own PR)

• Phase 1 — stop silent loss. Import: a CoverageScanner warns on every dropped construct (params, non-JSON bodies, requestBody $ref, security, callbacks, webhooks, servers, composition). Makes the feature honest immediately.
• Phase 2 — parameters. Import query/header params as inputs (tagged via x-altair-input-location, already reserved); give path params real types. Export: inputs whose location is path/query/header emit as OpenAPI parameters.
• Phase 3 — validation fidelity. Import format + min/max/pattern/... → existing Altair\Validation rules (email, min, max, regex, between, in); requestBody required. Export: rules → schema constraints. (Round-trip-symmetric.)
• Phase 4 — content & composition. multipart/form bodies, additionalProperties, oneOf/anyOf representation, external-$ref resolution/bundling.
• Phase 5 — security & misc. security schemes ↔ auth/middleware hints; nullable, deprecated; fix singularize("findByStatus")→findByStatu and action-y resource naming; path-param-type bug.

Acceptance

• No import silently drops a construct — everything is mapped or warned/errored.
• A richer real-world spec (Petstore + one with params/constraints/security) round-trips (openapi:roundtrip --check) with no silent loss.
• docs/guides/openapi/coverage.md documents the matrix and is kept current per phase.

[tonydspaniard]

Phase 1 done — PR #215 (merged).

CoverageScanner makes the importer honest: every dropped construct now surfaces as a receipt warning instead of being silently lost. On the real Swagger Petstore that's 25 warnings (query/header params, non-JSON bodies, requestBody $ref, per-op + global security, securitySchemes, servers) alongside the 19 mappable operations. Added docs/guides/openapi/coverage.md (the evidence-based matrix).

Next: Phase 2 — parameters (import query/header params as inputs via x-altair-input-location; export inputs whose location is path/query/header as OpenAPI parameters).

[tonydspaniard]

Phase 2 done — PR #216 (merged). Query/header/cookie/path parameters now round-trip: imported as inputs tagged with their in: location (type + required + enum rule), exported as OpenAPI parameters. On the real Petstore the warning count dropped 25 → 17 and findByStatus now imports its status query param. Next: Phase 3 — validation constraints ↔ rules.

[tonydspaniard]

Phase 3 done — PR #217 (merged). Validation constraints now round-trip with Altair rules: import maps format/minLength/maxLength/minimum/maximum/pattern → email/url/ip/datetime/min/max/regex; export writes the inverse (rules → format/minLength/pattern/enum). Remaining: Phase 4 (content types, additionalProperties, oneOf, external refs) and Phase 5 (security + naming bugs).

[tonydspaniard]

Phase 4a done — PR #218 (merged). Non-JSON bodies & responses now map instead of being dropped: a request body with no application/json reads the first content type carrying an object/array schema (multipart/form-data, x-www-form-urlencoded), and responses fall back to the first content type with any schema. application/json still wins when present; a binary/scalar body (application/octet-stream) stays unmapped (no named-field representation) rather than producing a nameless field. The schema re-emits as application/json on export, so the wire content type is normalized while the body structure round-trips.

To keep the "never silently" standard, the CoverageScanner now reports a normalized body/response as "schema is read from X (normalized)" (new scanResponses covers responses, closing the silent-response gap the parser change would otherwise open). Real Swagger Petstore still imports 19 specs / 17 warnings / 0 unmapped and openapi:roundtrip --check stays clean (its bodies all co-exist with application/json; uploadImage's octet-stream body stays unmapped).

Remaining Phase 4: allOf merge, oneOf/anyOf, additionalProperties, external-$ref bundling. Then Phase 5 (security schemes + naming bugs).

[tonydspaniard]

Phase 4b done — PR #219 (merged). allOf composition now maps instead of being dropped: the parser produces an ALLOF node and SchemaMapper flattens it by resolving every subschema (component $refs included) and merging their properties into one object — a property required in any subschema is required in the merge; a subschema that doesn't resolve to an object is unmappable. Resolution depth is bounded (shared MAX_RESOLUTION_DEPTH for $ref chains and allOf), so a cyclic allOf (Pet: allOf [$ref Pet]) terminates with a clean exception rather than a stack overflow.

Altair has no representation for composition, so it's flattened (data preserved) and normalized to a plain object on export — round-trip stays stable. The CoverageScanner surfaces it: once per named component using allOf, and per inline body/response, with no double-warning for $ref-to-allOf-components.

Known limitation (documented in coverage.md): a bare required sibling on an allOf node with no sibling properties isn't applied yet; required inside a subschema is honored.

Real Petstore unchanged (no allOf): 19/17/0, roundtrip clean. A hand-built allOf doc imports (1 spec, 0 unmapped, composition warned) and round-trips clean.

Remaining Phase 4: oneOf/anyOf, additionalProperties, external-$ref bundling. Then Phase 5 (security schemes + naming bugs).

[tonydspaniard]

Phase 4c+4d done — PR #220 (merged). oneOf/anyOf (unions) and additionalProperties (open maps) are now surfaced instead of silently dropped — they have no clean Altair representation, so this is honest warning, not mapping. The CoverageScanner's allOf detector is generalized into a recursive, $ref-free, depth-bounded compositionKeywords that warns once per keyword, per component and per inline body/response. On the real Petstore this surfaces GET /store/inventory's additionalProperties map (status->quantity, previously an empty body): warnings 17->18; still 19 specs / 0 unmapped, roundtrip clean. Remaining: 4e (external/relative-file $ref bundling) and Phase 5 (security + naming).

[tonydspaniard]

Phase 4e done — PR #221 (merged). Phase 4 is complete. External relative-file $refs are now bundled: a $ref: './schemas/pet.yaml#/Pet' is inlined into components/schemas (with its nested + same-file internal refs) and rewritten to internal, so multi-file specs import instead of failing. Bounded (file count/size/depth, cycle dedupe) and security-hardened: remote refs are never fetched, and a ref escaping the document directory is rejected — both warned, never silently followed (security-reviewer: 0 CRITICAL/0 HIGH, path-escape/SSRF/symlink/billion-laughs all verified). Real Petstore unchanged (19/18/0, roundtrip clean). Next: Phase 5 (security schemes + naming).