From c7ad4a7fc0f81d117ec7af369bf39c6317ff1323 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Mon, 31 Aug 2026 14:41:37 +0100 Subject: [PATCH 1/4] fix(spec): emit FCM service account JSON as an object, not a string The OpenAPI3 parameter switch matches on the concrete validator class, so Utopia\Validator\JSON\FCM fell through to the string default even though it reports TYPE_OBJECT and the controller still accepts an array, stdClass or JSON string. Swapping the FCM param's JSON validator for the stricter FCM one was meant to tighten validation, but it silently narrowed the published type and turned serviceAccountJSON into a string in every generated SDK. --- .../SDK/Specification/Format/OpenAPI3.php | 1 + tests/unit/SDK/Specification/FormatTest.php | 26 +++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php index 1ee1babc96..53151e610c 100644 --- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php @@ -733,6 +733,7 @@ class OpenAPI3 extends Format break; case \Utopia\Validator\JSON::class: case \Utopia\Validator\JSON\ObjectValidator::class: + case \Utopia\Validator\JSON\FCM::class: case \Utopia\Validator\Assoc::class: $node['schema']['type'] = 'object'; $node['schema']['default'] = (empty($param['default'])) ? new \stdClass() : $param['default']; diff --git a/tests/unit/SDK/Specification/FormatTest.php b/tests/unit/SDK/Specification/FormatTest.php index 96d05875cf..5601a70c1d 100644 --- a/tests/unit/SDK/Specification/FormatTest.php +++ b/tests/unit/SDK/Specification/FormatTest.php @@ -63,6 +63,7 @@ use Utopia\Validator\FloatValidator; use Utopia\Validator\HexColor; use Utopia\Validator\Integer as IntegerValidator; use Utopia\Validator\JSON; +use Utopia\Validator\JSON\FCM; use Utopia\Validator\Nullable; use Utopia\Validator\Range; use Utopia\Validator\Text; @@ -1040,6 +1041,31 @@ final class FormatTest extends TestCase $this->assertSame('object', $openApiQuery['type']); } + public function testObjectValidatorsOutsideTheSwitchAreNotEmittedAsStrings(): void + { + Method::$processed = []; + Method::$errors = []; + + $route = (new Route('POST', '/v1/tests/fcm')) + ->desc('Create FCM provider') + ->label('sdk', new Method( + namespace: 'test', + group: null, + name: 'createFcmProvider', + description: 'Create FCM provider.', + auth: [], + responses: [], + )) + ->param('serviceAccountJSON', null, new Nullable(new FCM()), 'FCM service account JSON.', true) + ->param('bareServiceAccountJSON', null, new FCM(), 'FCM service account JSON.', true); + + $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); + $properties = $spec['paths']['/tests/fcm']['post']['requestBody']['content']['application/json']['schema']['properties']; + + $this->assertSame('object', $properties['serviceAccountJSON']['type']); + $this->assertSame('object', $properties['bareServiceAccountJSON']['type']); + } + public function testJsonAndNullableModelRulesEmitExpectedSchemas(): void { Method::$processed = []; From fc7e0e633db9e6f9776a97ab740ad70d34a6d0ac Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Mon, 31 Aug 2026 14:45:01 +0100 Subject: [PATCH 2/4] refactor(spec): honour the declared type in the OpenAPI3 parameter default Rather than adding one more class to the object case, the default branch now emits an object when the validator reports TYPE_OBJECT, so the next object validator without a case of its own does not regress the same way. The listed cases keep their current behaviour: Assoc reports TYPE_ARRAY but is deliberately published as an object, and a type-driven rule applied to them would change that. Across the full cloud route table this changes exactly the two FCM parameters and nothing else. --- .../SDK/Specification/Format/OpenAPI3.php | 12 +++- tests/unit/SDK/Specification/FormatTest.php | 60 ++++++++++++++++++- 2 files changed, 69 insertions(+), 3 deletions(-) diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php index 53151e610c..4410385545 100644 --- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php @@ -733,7 +733,6 @@ class OpenAPI3 extends Format break; case \Utopia\Validator\JSON::class: case \Utopia\Validator\JSON\ObjectValidator::class: - case \Utopia\Validator\JSON\FCM::class: case \Utopia\Validator\Assoc::class: $node['schema']['type'] = 'object'; $node['schema']['default'] = (empty($param['default'])) ? new \stdClass() : $param['default']; @@ -944,6 +943,17 @@ class OpenAPI3 extends Format } break; default: + // The cases above match on the concrete validator class, so a + // validator that declares itself an object but is not listed + // reaches here and would be published as a string. That is how + // JSON\FCM narrowed serviceAccountJSON in every generated SDK. + if ($validator->getType() === Validator::TYPE_OBJECT) { + $node['schema']['type'] = 'object'; + $node['schema']['default'] = empty($param['default']) ? new \stdClass() : $param['default']; + $node['schema']['example'] = ($param['example'] ?? '') !== '' ? $param['example'] : '{}'; + break; + } + $node['schema']['type'] = 'string'; if (($param['example'] ?? '') !== '') { $node['schema']['example'] = $param['example']; diff --git a/tests/unit/SDK/Specification/FormatTest.php b/tests/unit/SDK/Specification/FormatTest.php index 5601a70c1d..c4424d7c0d 100644 --- a/tests/unit/SDK/Specification/FormatTest.php +++ b/tests/unit/SDK/Specification/FormatTest.php @@ -54,6 +54,7 @@ use Utopia\Database\Validator\Spatial; use Utopia\DI\Container; use Utopia\Http\Route; use Utopia\Platform\Enum; +use Utopia\Validator; use Utopia\Validator\AnyOf; use Utopia\Validator\ArrayList; use Utopia\Validator\Assoc; @@ -69,6 +70,56 @@ use Utopia\Validator\Range; use Utopia\Validator\Text; use Utopia\Validator\WhiteList; +/** + * Stands in for a validator that reports an object but has no case of its own in + * the OpenAPI3 parameter switch, which is the shape that regressed. + */ +class UnlistedObjectValidator extends Validator +{ + public function getDescription(): string + { + return 'Value must be an object'; + } + + public function isArray(): bool + { + return false; + } + + public function getType(): string + { + return self::TYPE_OBJECT; + } + + public function isValid(mixed $value): bool + { + return \is_array($value) || $value instanceof \stdClass; + } +} + +class UnlistedStringValidator extends Validator +{ + public function getDescription(): string + { + return 'Value must be a string'; + } + + public function isArray(): bool + { + return false; + } + + public function getType(): string + { + return self::TYPE_STRING; + } + + public function isValid(mixed $value): bool + { + return \is_string($value); + } +} + class TestFormat extends Format { public function getName(): string @@ -1041,7 +1092,7 @@ final class FormatTest extends TestCase $this->assertSame('object', $openApiQuery['type']); } - public function testObjectValidatorsOutsideTheSwitchAreNotEmittedAsStrings(): void + public function testObjectValidatorsWithoutTheirOwnCaseAreNotEmittedAsStrings(): void { Method::$processed = []; Method::$errors = []; @@ -1057,13 +1108,18 @@ final class FormatTest extends TestCase responses: [], )) ->param('serviceAccountJSON', null, new Nullable(new FCM()), 'FCM service account JSON.', true) - ->param('bareServiceAccountJSON', null, new FCM(), 'FCM service account JSON.', true); + ->param('bareServiceAccountJSON', null, new FCM(), 'FCM service account JSON.', true) + ->param('unlistedObject', null, new UnlistedObjectValidator(), 'An object validator with no case of its own.', true) + ->param('unlistedString', null, new UnlistedStringValidator(), 'A string validator with no case of its own.', true); $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); $properties = $spec['paths']['/tests/fcm']['post']['requestBody']['content']['application/json']['schema']['properties']; $this->assertSame('object', $properties['serviceAccountJSON']['type']); $this->assertSame('object', $properties['bareServiceAccountJSON']['type']); + $this->assertSame('object', $properties['unlistedObject']['type']); + $this->assertEquals(new \stdClass(), $properties['unlistedObject']['default']); + $this->assertSame('string', $properties['unlistedString']['type']); } public function testJsonAndNullableModelRulesEmitExpectedSchemas(): void From d68394c166afe781a0e81e3af470ac5fe23fc786 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Mon, 31 Aug 2026 14:45:56 +0100 Subject: [PATCH 3/4] test(spec): drop the OpenAPI3 object-type regression test --- tests/unit/SDK/Specification/FormatTest.php | 82 --------------------- 1 file changed, 82 deletions(-) diff --git a/tests/unit/SDK/Specification/FormatTest.php b/tests/unit/SDK/Specification/FormatTest.php index c4424d7c0d..96d05875cf 100644 --- a/tests/unit/SDK/Specification/FormatTest.php +++ b/tests/unit/SDK/Specification/FormatTest.php @@ -54,7 +54,6 @@ use Utopia\Database\Validator\Spatial; use Utopia\DI\Container; use Utopia\Http\Route; use Utopia\Platform\Enum; -use Utopia\Validator; use Utopia\Validator\AnyOf; use Utopia\Validator\ArrayList; use Utopia\Validator\Assoc; @@ -64,62 +63,11 @@ use Utopia\Validator\FloatValidator; use Utopia\Validator\HexColor; use Utopia\Validator\Integer as IntegerValidator; use Utopia\Validator\JSON; -use Utopia\Validator\JSON\FCM; use Utopia\Validator\Nullable; use Utopia\Validator\Range; use Utopia\Validator\Text; use Utopia\Validator\WhiteList; -/** - * Stands in for a validator that reports an object but has no case of its own in - * the OpenAPI3 parameter switch, which is the shape that regressed. - */ -class UnlistedObjectValidator extends Validator -{ - public function getDescription(): string - { - return 'Value must be an object'; - } - - public function isArray(): bool - { - return false; - } - - public function getType(): string - { - return self::TYPE_OBJECT; - } - - public function isValid(mixed $value): bool - { - return \is_array($value) || $value instanceof \stdClass; - } -} - -class UnlistedStringValidator extends Validator -{ - public function getDescription(): string - { - return 'Value must be a string'; - } - - public function isArray(): bool - { - return false; - } - - public function getType(): string - { - return self::TYPE_STRING; - } - - public function isValid(mixed $value): bool - { - return \is_string($value); - } -} - class TestFormat extends Format { public function getName(): string @@ -1092,36 +1040,6 @@ final class FormatTest extends TestCase $this->assertSame('object', $openApiQuery['type']); } - public function testObjectValidatorsWithoutTheirOwnCaseAreNotEmittedAsStrings(): void - { - Method::$processed = []; - Method::$errors = []; - - $route = (new Route('POST', '/v1/tests/fcm')) - ->desc('Create FCM provider') - ->label('sdk', new Method( - namespace: 'test', - group: null, - name: 'createFcmProvider', - description: 'Create FCM provider.', - auth: [], - responses: [], - )) - ->param('serviceAccountJSON', null, new Nullable(new FCM()), 'FCM service account JSON.', true) - ->param('bareServiceAccountJSON', null, new FCM(), 'FCM service account JSON.', true) - ->param('unlistedObject', null, new UnlistedObjectValidator(), 'An object validator with no case of its own.', true) - ->param('unlistedString', null, new UnlistedStringValidator(), 'A string validator with no case of its own.', true); - - $spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse(); - $properties = $spec['paths']['/tests/fcm']['post']['requestBody']['content']['application/json']['schema']['properties']; - - $this->assertSame('object', $properties['serviceAccountJSON']['type']); - $this->assertSame('object', $properties['bareServiceAccountJSON']['type']); - $this->assertSame('object', $properties['unlistedObject']['type']); - $this->assertEquals(new \stdClass(), $properties['unlistedObject']['default']); - $this->assertSame('string', $properties['unlistedString']['type']); - } - public function testJsonAndNullableModelRulesEmitExpectedSchemas(): void { Method::$processed = []; From 0891542ae18040de1d8242751aff6ce25c0b95cb Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Mon, 31 Aug 2026 14:47:21 +0100 Subject: [PATCH 4/4] refactor(spec): drop the object cases the parameter default now covers JSON and JSON\ObjectValidator both report TYPE_OBJECT, so the default emits exactly what their cases did. Assoc keeps its case because it reports TYPE_ARRAY and is published as an object on purpose. --- src/Appwrite/SDK/Specification/Format/OpenAPI3.php | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php index 4410385545..294e2d72ca 100644 --- a/src/Appwrite/SDK/Specification/Format/OpenAPI3.php +++ b/src/Appwrite/SDK/Specification/Format/OpenAPI3.php @@ -731,9 +731,9 @@ class OpenAPI3 extends Format $node['schema']['format'] = 'url'; $node['schema']['example'] = ($param['example'] ?? '') !== '' ? $param['example'] : 'https://example.com'; break; - case \Utopia\Validator\JSON::class: - case \Utopia\Validator\JSON\ObjectValidator::class: case \Utopia\Validator\Assoc::class: + // Assoc reports TYPE_ARRAY, so only an explicit case publishes + // it as an object. TYPE_OBJECT is handled by the default. $node['schema']['type'] = 'object'; $node['schema']['default'] = (empty($param['default'])) ? new \stdClass() : $param['default']; $node['schema']['example'] = ($param['example'] ?? '') !== '' ? $param['example'] : '{}'; @@ -943,10 +943,6 @@ class OpenAPI3 extends Format } break; default: - // The cases above match on the concrete validator class, so a - // validator that declares itself an object but is not listed - // reaches here and would be published as a string. That is how - // JSON\FCM narrowed serviceAccountJSON in every generated SDK. if ($validator->getType() === Validator::TYPE_OBJECT) { $node['schema']['type'] = 'object'; $node['schema']['default'] = empty($param['default']) ? new \stdClass() : $param['default'];