fix(specs): keep open enums open in the generated spec (#13295)

* fix(specs): keep open enums open in the generated spec

A param declared as `AnyOf([WhiteList(...), Text(...)])` accepts any string
at runtime — the whitelist names the values callers usually want and the text
branch keeps everything else valid. The formatter resolved such a union by
taking `getValidators()[0]` and discarding the rest, so the text branch never
reached the spec. Paired with an `enum:` declaration the result advertises a
closed set for a param that is deliberately open, and generated SDKs then
reject values the endpoint would have accepted.

Emit the union the way OpenAPI already expresses it, with `anyOf` over the
enum branch and a plain string branch. That mirrors the validator exactly, so
a generator can widen the parameter type while still offering the enum for
discovery, and it needs no new vendor extension — the enum branch carries the
same `x-enum-name` / `x-enum-keys` it does today.

Strictness is derived from the validator rather than declared separately, so
it cannot drift from what the endpoint actually accepts — that drift is what
produced the wrong spec in the first place.

No committed spec changes: the union is only emitted when an open union also
declares an enum, and no param in this repository does both.

* refactor(specs): simplify open enum handling

* test(specs): focus open enum coverage
This commit is contained in:
Chirag Aggarwal authored and GitHub committed 2026-08-20 18:15:17 +05:30
1 parent eeeaba89cc
commit 46e8cc7bba
2 files changed
+84 -1

No files matched your search

@@ -23,6 +23,7 @@ use Utopia\Validator;
use Utopia\Validator\ArrayList;
use Utopia\Validator\Nullable;
use Utopia\Validator\Range;
use Utopia\Validator\WhiteList;
class OpenAPI3 extends Format
{
@@ -533,9 +534,22 @@ class OpenAPI3 extends Format
$class = Queries::class;
}
$openEnum = false;
if ($class === \Utopia\Validator\AnyOf::class) {
$validator = $param['validator']->getValidators()[0];
$validators = $param['validator']->getValidators();
$validator = $validators[0];
$class = \get_class($validator);
foreach ($validators as $unionValidator) {
while ($unionValidator instanceof ArrayList || $unionValidator instanceof Nullable) {
$unionValidator = $unionValidator->getValidator();
}
if (!$unionValidator instanceof WhiteList && $unionValidator->getType() === Validator::TYPE_STRING) {
$openEnum = true;
break;
}
}
}
$array = false;
@@ -754,6 +768,15 @@ class OpenAPI3 extends Format
$node['schema']['items']['x-enum-name'] = $enum->name;
}
$node['schema']['items']['x-enum-keys'] = $enumKeys;
if ($openEnum) {
$node['schema']['items'] = [
'anyOf' => [
$node['schema']['items'],
['type' => Validator::TYPE_STRING],
],
];
}
}
}
if ($validator->getType() === 'integer') {
@@ -791,6 +814,26 @@ class OpenAPI3 extends Format
$node['schema']['x-enum-name'] = $enum->name;
}
$node['schema']['x-enum-keys'] = $enumKeys;
if ($openEnum) {
$enumBranch = ['type' => $node['schema']['type'], 'enum' => $enumValues];
if (!empty($enum->name)) {
$enumBranch['x-enum-name'] = $enum->name;
}
$enumBranch['x-enum-keys'] = $enumKeys;
unset(
$node['schema']['type'],
$node['schema']['enum'],
$node['schema']['x-enum-name'],
$node['schema']['x-enum-keys'],
);
$node['schema']['anyOf'] = [
$enumBranch,
['type' => Validator::TYPE_STRING],
];
}
}
}
if ($validator->getType() === 'integer') {
@@ -937,6 +980,13 @@ class OpenAPI3 extends Format
$body['content'][$consumes[0]]['schema']['properties'][$name]['format'] = $node['schema']['format'];
}
if (isset($node['schema']['anyOf'])) {
// Open enum: the known values and the free-form branch
// both live under anyOf, so copy the union wholesale.
$body['content'][$consumes[0]]['schema']['properties'][$name]['anyOf'] = $node['schema']['anyOf'];
unset($body['content'][$consumes[0]]['schema']['properties'][$name]['type']);
}
if (isset($node['schema']['enum'])) {
/// If the enum flag is Set, add the enum values to the body
$body['content'][$consumes[0]]['schema']['properties'][$name]['enum'] = $node['schema']['enum'];
@@ -47,6 +47,8 @@ use Utopia\Database\Validator\Query\Offset;
use Utopia\Database\Validator\Spatial;
use Utopia\DI\Container;
use Utopia\Http\Route;
use Utopia\Platform\Enum;
use Utopia\Validator\AnyOf;
use Utopia\Validator\ArrayList;
use Utopia\Validator\Assoc;
use Utopia\Validator\Boolean as BooleanValidator;
@@ -54,6 +56,7 @@ use Utopia\Validator\JSON;
use Utopia\Validator\Nullable;
use Utopia\Validator\Range;
use Utopia\Validator\Text;
use Utopia\Validator\WhiteList;
class TestFormat extends Format
{
@@ -124,6 +127,36 @@ final class FormatTest extends TestCase
$this->assertSame('HealthCheckStatus', (new HealthStatus())->getRules()['status']['enumSDKName']);
}
public function testUnionWithAFreeStringBranchEmitsAnyOf(): void
{
Method::$processed = [];
Method::$errors = [];
$route = (new Route('GET', '/v1/tests'))
->desc('List tests')
->label('sdk', new Method(
namespace: 'test',
group: null,
name: 'listTests',
description: 'List tests.',
auth: [],
responses: [],
))
->param('metrics', [], new AnyOf([
new ArrayList(new WhiteList(['alpha', 'beta'], true), 10),
new ArrayList(new Text(255), 10),
]), 'Metric names.', false, enum: new Enum(name: 'TestMetric'));
$spec = (new OpenAPI3(new Container(), [], [$route], [], [], 0, 'console'))->parse();
$this->assertSame([
'anyOf' => [
['type' => 'string', 'enum' => ['alpha', 'beta'], 'x-enum-name' => 'TestMetric', 'x-enum-keys' => ['alpha', 'beta']],
['type' => 'string'],
],
], $spec['paths']['/tests']['get']['parameters'][0]['schema']['items']);
}
public function testOpenApiCustomIdBodyFieldIncludesIdGeneratorMetadata(): void
{
Method::$processed = [];