## Problem/Motivation An output definition has one flag, `required`, and the JSON Schema normalizer reads it as two things: ```php if (!$object->isRequired()) { // ... $schema['type'] = [$schema['type'], 'null']; } ``` and, on the parent map: ```php if ($property->isRequired()) { $schema['required'][] = $property_name; } ``` So `required: TRUE` means "the key is present and not null", and `required: FALSE` means "the key may be missing and may be null". JSON Schema keeps these apart: `required` is key presence, and `null` in `type` is nullability. The shape that falls between them is common: a key that is always sent and holds null when there is no value. A photo's EXIF date, an entity's optional field, a timestamp that has not happened yet: ```php new MapOutputDefinition('Image', 'A photo.', property_definitions: [ 'date' => new OutputDefinition('timestamp', 'Date', 'When the photo was taken.', required: FALSE), ]); ``` ```json { "type": "object", "properties": {"date": {"type": ["integer", "null"]}} } ``` The tool always sends `date`. The schema says it may be missing. That passes validation, but it promises less than the tool delivers. A client that trusts the schema writes code for a missing key that never goes missing, and a strict structured-output consumer can't rely on the key. Declaring it `required: TRUE` doesn't help. The schema drops the null branch, and core's `NotNull` rejects the null the tool sends. Method tools on #3518120 hit this for every nullable member that isn't marked `omit_when_null`: ```php #[ToolProperty(description: 'When the photo was taken, from its EXIF data.', data_type: 'timestamp')] public function getDate(): ?int ``` ## Proposed resolution Add a `nullable` flag to output definitions, separate from `required`. It is a plain boolean that defaults to `FALSE`; NULL means absence. The four combinations: | `required` | `nullable` | result | schema | | --- | --- | --- | --- | | `TRUE` | `FALSE` (default) | key always present, never null | `T`, listed in `required` | | `TRUE` | `TRUE` | key always present, null when there is no value | `[T, "null"]`, listed in `required` | | `FALSE` | `FALSE` (default) | an output holding NULL is left out of the result | `T`, key may be missing | | `FALSE` | `TRUE` | key sent with `null` when there is no value, may also be missing | `[T, "null"]` | ```php new OutputDefinition('timestamp', 'Date', 'When the photo was taken.', required: TRUE, nullable: TRUE); ``` ```json { "type": "object", "properties": {"date": {"type": ["integer", "null"]}}, "required": ["date"] } ``` The third row changes today's behavior: an optional output that never declared the flag currently advertises `[T, "null"]` and sends the null. That is a change to the published schema of every optional output, so it lands before rc1 rather than after. The normalizer reads `required` for the parent's `required` list and `nullable` for the null branch. Validation leaves out core's `NotNull` for a nullable definition. Lists (#3583040) and maps (#3583069) already work this way: `EffectiveDataDefinition` does not mark them required, so typed data adds no `NotNull`, and the value walkers reject NULL themselves through `validateListNotNull()`. A nullable definition skips that check. On #3518120, the describer then maps a method-tool member like this: | member | `required` | `nullable` | type | | --- | --- | --- | --- | | non-nullable | yes | no | `T` | | nullable | yes | yes | `[T, null]` | | nullable + `omit_when_null` | no | no | `T` | Inputs get the same flag in a follow-up issue. The default keeps today's behavior, an optional input may be sent as null; `nullable: TRUE` means null is a value, so `getInputValue()` returns the NULL instead of the default. ## API changes New `nullable` parameter and `isNullable()` / `setNullable()` on output definitions, default `FALSE`. An optional output that never declared the flag stops advertising `null` and is left out of the result when it holds NULL. ## Remaining tasks - Flip the default to `FALSE` and leave an optional NULL output out of the - Decide the nested rule and apply it at every depth: a null in an optional, non-nullable map property is left out like a top-level one; a null list item cannot be left out without shifting the positions the path contract (#3583065) relies on, so it is a violation unless the item definition is nullable. result; `setOutputValue()` already stores the key, so `array_key_exists()` tells "set to NULL" from "never set" for the required cases. - Teach the normalizers and output validation to read the flag. - Map `omit_when_null` and nullable types to the two flags in the method-tool describer (#3518120 landed first). - Remove the `@todo` on `TypedMethodDescriber::memberIsRequired()`. - File the follow-up for the input flag.