Schema for errors contains invalid `type`, array given instead of string

[martijncalker]

API Platform version(s) affected: 4.1.1

# php -v
PHP 8.4.4 (cli) (built: Feb 25 2025 02:19:56) (NTS)
Copyright (c) The PHP Group
Built by https://github.com/docker-library/php
Zend Engine v4.4.4, Copyright (c) Zend Technologies
    with Xdebug v3.4.2, Copyright (c) 2002-2025, by Derick Rethans

Description

I noticed (in my own project, and validated in a clean project), that the types returned in an exception or validation are not always a string (expected), but an array (null + string).

    "components": {
        "schemas": {
            "ConstraintViolation-json": {
                "type": "object",
                "description": "Unprocessable entity",
                "deprecated": false,
                "properties": {
                    "status": {
                        "default": 422,
                        "example": 422,
                        "type": "integer"
                    },
                    "violations": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "propertyPath": {
                                    "type": "string",
                                    "description": "The property path of the violation"
                                },
                                "message": {
                                    "type": "string",
                                    "description": "The message associated with the violation"
                                }
                            }
                        }
                    },
                    "detail": {
                        "readOnly": true,
                        "type": "string"
                    },
                    "type": {
                        "readOnly": true,
                        "type": "string"
                    },
                    "title": {
                        "readOnly": true,
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "instance": {
                        "readOnly": true,
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            },

See both title.type and instance.type.

How to reproduce

# symfony version  
Symfony CLI version 5.11.0 (c) 2021-2025 Fabien Potencier (2025-02-17T09:11:09Z - stable)
# symfony local:new --api symfony-api-platform

Created a single ApiResource, and then run:

# bin/console api:openapi:export

Possible Solution

For me, it worked when I removed some of the nullable return type from the fields in the following classes (should probably be double checked):

./src/Validator/Exception/ValidationException.php
./src/State/ApiResource/Error.php
./src/Laravel/ApiResource/Error.php

If this is the case, I'm happy to create PR for it. Please let me know what you think of it or when I'm wrong / overlooked something (i've not much experience using api-platform).

Additional Context

none

[asmadallaji]

Hi, I would like to work on this issue. Could you please assign it to me?

[soyuka]

Hi @martijncalker, thanks for the report.

The type: ["string", "null"] form you see is the OpenAPI 3.1.0 idiomatic way to express a nullable string. The default bin/console api:openapi:export emits OpenAPI 3.1.0 (the document declares "openapi": "3.1.0" at the top), and arrays of types are valid for nullable schemas in 3.1.0.

If you need OpenAPI 3.0 output (e.g. for tooling that doesn't support 3.1 yet, like Swagger UI or zircote/swagger-php), use:

bin/console api:openapi:export --spec-version=3.0.0

This produces the 3.0-idiomatic type: "string", nullable: true form. PR #8225 (merged in 4.3) made this downgrade recursive and complete, including the ConstraintViolation-json / Error schemas you cited.

Closing as not-a-bug. Re-open if you can show a concrete invalid-against-3.1 output, or --spec-version=3.0.0 still emits an array type for a specific field.