Skip to content

Fix: Move required from array schema to object schema inside items#1068

Merged
shalvah merged 3 commits into
knuckleswtf:v5from
gregmillz:fix/openapi-required-fields-in-array-items
May 1, 2026
Merged

Fix: Move required from array schema to object schema inside items#1068
shalvah merged 3 commits into
knuckleswtf:v5from
gregmillz:fix/openapi-required-fields-in-array-items

Conversation

@gregmillz

@gregmillz gregmillz commented Mar 23, 2026

Copy link
Copy Markdown
Contributor

In the openapi spec, the required array belongs on the object schema inside items, not on the parent array schema (see data types)

  • Fix required field placement in array item schemas. It was being set on the array schema itself instead of inside items, but it should have been in the object schema. The fix for this is in the function generateSchemaForResponseValue.

Example:
Incorrect: required object properties are in the array schema

lineItems:
  type: array
  required:  # `required` is not a valid keyword on type: array
    - productId
    - quantity
  items:
    type: object
    properties:
      productId:
        type: string
      quantity:
        type: integer
      note:
        type: string

Correct: required object properties are in the object schema:

lineItems:
  type: array
  items:
    type: object
    required:
      - productId
      - quantity
    properties:
      productId:
        type: string
      quantity:
        type: integer
      note:
        type: string
  • Add missing required field support for responses that are arrays of objects. For example, when Laravel APIs return a collection, it's wrapped in a data key like { "data": [{"name": "foo"}]} but you can call JsonResource::withoutWrapping() to get an array instead: [{"name": "foo"}]. The fix for this is in generateResponseContentSpec.

…PI spec

Within the OpenAPI spec, the required array belongs on the object schema
inside items, not on the parent array schema. Also adds required field
support for unwrapped array-of-object responses, for example, when Laravel APIs return a collection, it's wrapped in a `data` key like `{ "data": [{"name": "foo"}]}` but you can call `JsonResource::withoutWrapping()` to get an array instead: `[{"name": "foo"}]`. So the bug was that the required field logic existed for the wrapped case, but not the unwrapped branch.
@gregmillz

Copy link
Copy Markdown
Contributor Author

I see this is the same issue as this PR, but I would like to see if the test changes are fixed with this pr

@gregmillz gregmillz changed the title Fix: Required fields on array items must exist at the array level Fix: Move required from array schema to object schema inside items Mar 24, 2026
@gregmillz

Copy link
Copy Markdown
Contributor Author

CI is fixed by separate this other PR: https://github.com/knuckleswtf/scribe/pull/1071/changes

@gregmillz

gregmillz commented Apr 15, 2026

Copy link
Copy Markdown
Contributor Author

Hi @shalvah! Is there a release schedule? No rush. The package is great, so would like to help improve it with this change :)

@shalvah shalvah merged commit c60c27d into knuckleswtf:v5 May 1, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants