OpenAPI 3.0: spec_version=3.0.0 documents still contain {"type": "null"} members in oneOf/anyOf #8751

API Platform version(s) affected

5.0.4 (same on 4.4.5 and main)

Description

With spec_version=3.0.0, nullable members are still written the 3.1 way. The to-one relationship data of a JSON:API schema:

"parent": {"type": "object", "properties": {"data": {"oneOf": [{"type": "null"}, {"type": "object", "properties": {"type": {"type": "string"}, "id": {"type": "string", "format": "iri-reference"}}, "required": ["type", "id"]}]}}}

null is not a valid type in OpenAPI 3.0, which uses nullable: true (https://spec.openapis.org/oas/v3.0.3#schema-object), so the document does not validate:

$ curl -H 'Accept: application/vnd.openapi+json' 'http://localhost/docs?spec_version=3.0.0' > openapi.json
$ openapi-spec-validator openapi.json

Expected: {"type": "object", "properties": {...}, "required": [...], "nullable": true}.

LegacyOpenApiNormalizer::downgradeSchema() (src/OpenApi/Serializer/LegacyOpenApiNormalizer.php:107) only rewrites type arrays such as ["string", "null"], type: "null" inside oneOf/anyOf is left as is. The JSON:API schema factory emits it at src/JsonApi/JsonSchema/SchemaFactory.php:334, the core JSON Schema factory does too (anyOf with {"type": "null"} in src/JsonSchema/SchemaFactory.php:296, :498 and src/JsonSchema/Metadata/Property/Factory/SchemaPropertyMetadataFactory.php:198, :217), so the downgrade is the place to fix it.

Suggested fix: in the downgrade, drop the {"type": "null"} member of oneOf/anyOf, set nullable: true on the schema, and inline the remaining member when there is a single one and it is not a $ref.

On 5.0 the webhooks root field is also kept in the 3.0 document until #8722 is merged up, that one is separate.

Related: #8690, #6803, #8225.