[Platform][VertexAi] Normalize nullable fields in structured output schema

[ousamabenyounes]

Q	A
Bug fix?	yes
New feature?	no
Docs?	no
Issues	Fix #1999
License	MIT

Problem

Using structured output with the Vertex/Gemini bridge throws as soon as a DTO property is nullable:

Error from Gemini API: "Invalid JSON payload received. Unknown name "type" at
'generation_config.response_schema.properties[0].value.items.properties[5].value':
Proto field is not repeating, cannot start list."

The JSON Schema factory represents a nullable field with an array-style type ("type": ["string", "null"]). VertexAI's OpenAPI-flavored schema parser does not accept an array there — it requires a single type plus "nullable": true.

Contract\ToolNormalizer already performed this conversion for tool parameter schemas, but the structured-output responseSchema in Gemini\ModelClient was assigned straight from the response_format payload without any normalization, so nullable fields broke.

Fix

• Extract the nullable-array → nullable: true conversion (and the additionalProperties stripping) from ToolNormalizer into a shared SchemaNormalizer.
• ToolNormalizer now delegates to it (identical behavior, no duplicated logic).
• Gemini\ModelClient runs the structured-output responseSchema through the same normalizer, so tool and response schemas stay in sync.

Test verification (RED → GREEN)

New test testItNormalizesNullableFieldsInStructuredOutputResponseSchema asserts the wire responseSchema has a single type + nullable: true (top-level and nested items) and no additionalProperties.

On the unmodified branch (RED):

1) ...VertexAi\Tests\Gemini\ModelClientTest::testItNormalizesNullableFieldsInStructuredOutputResponseSchema
Failed asserting that Array &0 [
    0 => 'string',
    1 => 'null',
] is identical to 'string'.
FAILURES! Tests: 1, Assertions: 2, Failures: 1.

With the fix (GREEN), the whole VertexAi bridge suite (including the existing ToolNormalizer nullable tests, proving behavior parity after the extraction):

OK (109 tests, 457 assertions)

PHPStan and PHP-CS-Fixer are clean on the changed files.

[chr-hertel]

Reproduced issue and confirmed as fix!

[chr-hertel]

Thank you @ousamabenyounes.