Skip to content

fix: normalize empty tool schema properties #411

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Hanshuk wants to merge 4 commits into
base: main
Choose a base branch
from
+163 −7
Open

fix: normalize empty tool schema properties #411

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2bef772
fix: normalize empty tool schema properties
Aug 10, 2026
039584e
test: fix tool schema regression test QA
Aug 10, 2026
cf8f194
style: fix schema normalization condition
Aug 10, 2026
1c89b18
fix: align tool input schema type
Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions src/Schema/Tool.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@
*
* @phpstan-type ToolInputSchema array{
* type: 'object',
* properties: array<string, mixed>,
* required: string[]|null
* properties?: array<string, mixed>,
* required?: string[]|null
* }
* @phpstan-type ToolOutputSchema array{
* type: 'object',
Expand Down Expand Up @@ -127,7 +127,7 @@ public function jsonSerialize(): array
if (null !== $this->title) {
$data['title'] = $this->title;
}
$data['inputSchema'] = $this->inputSchema;
$data['inputSchema'] = self::normalizeSchemaProperties($this->inputSchema);
if (null !== $this->description) {
$data['description'] = $this->description;
}
Expand All @@ -141,23 +141,37 @@ public function jsonSerialize(): array
$data['_meta'] = $this->meta;
}
if (null !== $this->outputSchema) {
$data['outputSchema'] = $this->outputSchema;
$data['outputSchema'] = self::normalizeSchemaProperties($this->outputSchema);
}

return $data;
}

/**
* Normalize schema properties: convert an empty properties array to stdClass.
* Normalize schema properties: convert an empty properties array to stdClass recursively.
*
* @param array<string, mixed> $schema
*
* @return array<string, mixed>
*/
private static function normalizeSchemaProperties(array $schema): array
{
if (isset($schema['properties']) && \is_array($schema['properties']) && empty($schema['properties'])) {
$schema['properties'] = new \stdClass();
if (isset($schema['properties']) && \is_array($schema['properties'])) {
if (empty($schema['properties'])) {
$schema['properties'] = new \stdClass();
} else {
foreach ($schema['properties'] as $key => $propSchema) {
if (\is_array($propSchema)) {
$schema['properties'][$key] = self::normalizeSchemaProperties($propSchema);
}
}
}
}

foreach ($schema as $key => $value) {
if ('properties' !== $key && \is_array($value)) {
$schema[$key] = self::normalizeSchemaProperties($value);
}
}

return $schema;
Expand Down
142 changes: 142 additions & 0 deletions tests/Unit/Schema/ToolTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,4 +97,146 @@ public function testRoundTripPreservesTitle(): void
$this->assertSame($original->name, $restored->name);
$this->assertSame($original->description, $restored->description);
}

public function testEmptyPropertiesNormalizationOnDirectConstruction(): void
{
$tool = new Tool(
name: 'test',
title: null,
inputSchema: [
'type' => 'object',
'properties' => [],
],
description: null,
annotations: null,
);
$serialized = $tool->jsonSerialize();
$this->assertInstanceOf(\stdClass::class, $serialized['inputSchema']['properties']);
$this->assertSame('{"name":"test","inputSchema":{"type":"object","properties":{}}}', json_encode($serialized));
}

public function testEmptyPropertiesNormalizationOnFromArray(): void
{
$tool = Tool::fromArray([
'name' => 'test',
'inputSchema' => [
'type' => 'object',
'properties' => [],
],
]);
$serialized = $tool->jsonSerialize();
$this->assertInstanceOf(\stdClass::class, $serialized['inputSchema']['properties']);
$this->assertSame('{"name":"test","inputSchema":{"type":"object","properties":{}}}', json_encode($serialized));
}

public function testJsonRoundTripPreservesEmptyPropertiesObject(): void
{
$json = '{"type":"object","properties":{}}';
$schema = (array) json_decode($json, true);
$tool = new Tool('test', null, $schema, null, null);
$serialized = $tool->jsonSerialize();

$this->assertInstanceOf(\stdClass::class, $serialized['inputSchema']['properties']);
$this->assertSame('{"name":"test","inputSchema":{"type":"object","properties":{}}}', json_encode($serialized));
}

public function testNestedObjectEmptyPropertiesNormalization(): void
{
$tool = new Tool(
name: 'test',
title: null,
inputSchema: [
'type' => 'object',
'properties' => [
'filter' => [
'type' => 'object',
'properties' => [],
],
],
],
description: null,
annotations: null,
);
$serialized = $tool->jsonSerialize();
$this->assertInstanceOf(\stdClass::class, $serialized['inputSchema']['properties']['filter']['properties']);
$this->assertSame('{"name":"test","inputSchema":{"type":"object","properties":{"filter":{"type":"object","properties":{}}}}}', json_encode($serialized));
}

public function testExistingNonEmptyPropertiesUnchanged(): void
{
$tool = new Tool(
name: 'test',
title: null,
inputSchema: [
'type' => 'object',
'properties' => [
'name' => [
'type' => 'string',
],
],
],
description: null,
annotations: null,
);
$serialized = $tool->jsonSerialize();
$this->assertIsArray($serialized['inputSchema']['properties']);
$this->assertArrayHasKey('name', $serialized['inputSchema']['properties']);
$this->assertSame('{"name":"test","inputSchema":{"type":"object","properties":{"name":{"type":"string"}}}}', json_encode($serialized));
}

public function testValidArraysAreNotTransformed(): void
{
$tool = new Tool(
name: 'test',
title: null,
inputSchema: [
'type' => 'object',
'properties' => [
'tags' => [
'type' => 'array',
'items' => [
'type' => 'string',
],
],
'status' => [
'type' => 'string',
'enum' => [],
],
],
'required' => [],
],
description: null,
annotations: null,
);
$serialized = $tool->jsonSerialize();
$this->assertIsArray($serialized['inputSchema']['required']);
$this->assertEmpty($serialized['inputSchema']['required']);
$this->assertIsArray($serialized['inputSchema']['properties']['tags']);
$this->assertIsArray($serialized['inputSchema']['properties']['status']['enum']);
$this->assertEmpty($serialized['inputSchema']['properties']['status']['enum']);
$this->assertSame('{"name":"test","inputSchema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":[]}},"required":[]}}', json_encode($serialized));
}

public function testOutputSchemaEmptyPropertiesNormalization(): void
{
$tool = new Tool(
name: 'test',
title: null,
inputSchema: [
'type' => 'object',
'properties' => ['q' => ['type' => 'string']],
],
description: null,
annotations: null,
icons: null,
meta: null,
outputSchema: [
'type' => 'object',
'properties' => [],
],
);
$serialized = $tool->jsonSerialize();
$this->assertInstanceOf(\stdClass::class, $serialized['outputSchema']['properties']);
$this->assertSame('{"name":"test","inputSchema":{"type":"object","properties":{"q":{"type":"string"}}},"outputSchema":{"type":"object","properties":{}}}', json_encode($serialized));
}
}