bug(openapi): report or normalize misplaced OpenAPI `required` booleans

[the-ult]

Acknowledgement

• I acknowledge that issues using this template may be closed without further explanation at the maintainers' discretion.

Comment

Orval: report or normalize misplaced OpenAPI required booleans

Type

Bug report / robustness improvement

Existing upstream references

No exact existing issue for required: true placed beside a request-body
schema $ref was found.

Possible matches:

• #3714 — current OpenAPI
  normalization work for invalid nullable $ref siblings
• #2933 — historical Zod
  split-generation robustness work, closed by #2964

This report is distinct from #3714: it concerns an invalid required boolean
placement and the required is not iterable generation failure.

Summary

Some OpenAPI documents produced by generators place required: true on a
schema node referenced from a request body. OpenAPI uses a boolean on the
request-body object, while schema-object required is normally an array of
property names.

Orval can fail with an error similar to:

(schema.required ?? []) is not iterable

This prevents generation of otherwise usable schemas and clients.

Minimal example

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /items:
    post:
      operationId: createItem
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Item'
              required: true
      responses:
        '204':
          description: Created
components:
  schemas:
    Item:
      type: object
      required: [name]
      properties:
        name:
          type: string

Expected behavior

Orval should either:

1. normalize the misplaced boolean to requestBody.required: true; or
2. emit a clear validation diagnostic identifying the invalid source location
   and expected OpenAPI shape.

It should not fail with an internal required is not iterable error.

Downstream workaround

A consumer-side OpenAPI preparation step currently moves a boolean from the
request-body media-type schema to the containing request body before invoking
Orval. This keeps generation deterministic for affected specifications.

Acceptance criteria

• Valid request-body required booleans continue to work.
• Invalid schema-level boolean placement produces a useful diagnostic or is
  normalized safely.
• Property-level legacy boolean annotations remain distinguishable from the
  request-body required flag.
• Add a regression fixture and generation test.

[snebjorn]

I vote for 2.

emit a clear validation diagnostic identifying the invalid source location and expected OpenAPI shape.

Trying to modify an invalid spec will lead to ambiguity.

OpenAPI validation is currently handled by @scalar/openapi-parser so best course of action is to open an upstream issue.

[melloware]

Agree with @snebjorn