Nullable does not work with OpenApi version 3.1.0

[BendeRsay]

Hello. If you specify the property type ['null', 'string'], we get an error. Example:

new OA\Schema(
            schema: 'middleNameProperty',
            description: 'Patronymic of the user',
            type: ['null', 'string'],
            example: 'Ivanovich',
        ),

We get an error:

ByJG\ApiTools\Exception\NotMatchedException: Value of property '#/components/schemas/middleNameProperty' is null, but should be of type 'Array'

[byjg]

Hello, the OpenApi 3.1 Spec wasn't implemented.

I create the PR #90 with this support. To test, change the version from ^6.0 to ^6.0.x-dev.

Please let me know if it worked for you, and don't forget to star the repo :)

[BendeRsay]

Thank you. Verification works in most cases. But it doesn't work in objects if there is a null. Example:

new OA\Property(
                            property: 'manager',
                            description: 'Organization Profile Manager',
                            required: ['phone'],
                            properties: [
                                new OA\Property(property: 'email', ref: '#/components/schemas/emailProperty'),
                                new OA\Property(
                                    property: 'phone',
                                    ref: '#/components/schemas/phoneNumberProperty'
                                ),
                                new OA\Property(property: 'lastName', ref: '#/components/schemas/lastNameProperty'),
                                new OA\Property(
                                    property: 'firstName',
                                    ref: '#/components/schemas/firstNameProperty'
                                ),
                                new OA\Property(
                                    property: 'middleName',
                                    ref: '#/components/schemas/middleNameProperty'
                                ),
                            ],
                            type: 'object',
                            nullable: true
                        ),

In my case, the "manager" object arrives filled in, but the check does not occur.

[byjg]

I implemented a test case based on the example you shared, and everything is working correctly on my side.

There are a few possible reasons why it may not be working in your case:

1) manager is {} instead of null

This is a subtle but very important difference.

In the schema, manager can be:

null

or an object that must contain phone

So this is valid:

{
  "name": "ACME",
  "manager": null
}

But this is not valid:

{
  "name": "ACME",
  "manager": {}
}

An empty object is still an object — and since phone is required, validation will fail.

2) The JSON string may be malformed or contain invalid characters

If the JSON contains binary or invalid characters, json_decode() may fail silently.

For example:

var_dump(json_decode('{"a":"\x13"}'));

This will return NULL because json_decode() cannot parse invalid binary characters.

When this happens, the decoded result is null, which can cause confusing downstream behavior.

It is important to verify:

json_last_error()
json_last_error_msg()

After decoding or add the flags: JSON_THROW_ON_ERROR parameter to the json_decode.

To properly investigate, please share the full JSON payload and the exact validation error you are receiving. That will allow us to reproduce and identify the root cause more precisely.

[BendeRsay]

Thank you so much for your work!

I downloaded your latest changes and everything is working now.