## Problem/Motivation A required list output advertises a plain array: ```php new OutputDefinition('string', 'Problems', 'What the check found.', required: TRUE, multiple: TRUE); ``` ```json {"type": "array", "items": {"type": "string"}} ``` `[]` satisfies that schema. Validation rejects it: ```php (new Context($definition, []))->validate(); // "This value should not be null." ``` The cause is core's `NotNullConstraintValidator`, which Tool API gets as a default constraint on every required definition: ```php if (($typed_data instanceof ListInterface || $typed_data instanceof ComplexDataInterface) && !$typed_data instanceof ArrayElement && $typed_data->isEmpty()) { $value = NULL; } ``` Typed data reads "required" as "not empty". JSON Schema reads `required` as "the key is present", and an array's length is a separate keyword, `minItems`. The published schema follows JSON Schema and validation follows typed data, so they disagree. Reproduced on 1.0.x, through the paths a tool uses (`validateOutputs()` and `validateInputValue()`): | Definition, `required: TRUE` | Value | Schema allows it | Validation | |---|---|---|---| | `OutputDefinition`, `multiple: TRUE` | `[]` | Yes | "should not be null" | | `ListOutputDefinition` | `[]` | Yes | "should not be null" | | `MapOutputDefinition` with a required list property | `['problems' => []]` | Yes | "problems: should not be null" | | `MapOutputDefinition`, no properties | `[]` | Yes | "should not be null" | | `MapInputDefinition`, no properties | `[]` | Yes | "should not be null" | List inputs are not affected: `validateInputValue()` validates their items and never runs the list-level `NotNull`, so `[]` already passes and `NULL` is rejected. An optional list accepts `[]`, but it is published as `"type": ["array", "null"]`, which tells a client the value may be `null`. So a tool cannot say "this list is always present and may be empty", which is the most common shape for a list output: search results, validation problems, changed IDs. A tool that returns `[]` for one of these fails `validateOutputs()`, and a client that sends `{}` for a required free-form map input gets an error it could not have predicted from the schema. ## Proposed resolution Make validation mean what the schema says. For list and map definitions, "required" rejects `NULL` only. A tool that needs at least one item says so with a `Count` constraint, which the normalizer already publishes as `minItems`: ```php new InputDefinition('entity:node', 'Nodes', 'The nodes to export.', required: TRUE, multiple: TRUE, constraints: ['Count' => ['min' => 1]]); // {"type": "array", "minItems": 1, ...} ``` Tool API already controls which default constraints reach validation (`ContextDefinitionBridgeTrait::getDataDefinition()`), so it can replace core's `NotNull` on list and map definitions with a check that only rejects `NULL`, without changing core. The alternative is to publish `minItems: 1` for every required list and `minProperties: 1` for every required map. That keeps today's behavior and makes the schema honest. But it leaves no way to declare a list that is always present and may be empty, short of making it nullable. ## API changes Behavior change: a required map input with no declared properties accepts `{}`. List inputs already accepted `[]`. ## Remaining tasks - Review !176, which takes the first resolution. - Check `tool_ai_connector` and the MCP bridge for their own "required means non-empty" assumptions.