feat(discriminator): add support for nested discriminator maps in JSON schema

Author: dylan-rumble

src/JsonApi/JsonSchema/SchemaFactory.php

@@ -27,7 +27,9 @@
 use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
 use ApiPlatform\Metadata\ResourceClassResolverInterface;
+use ApiPlatform\Metadata\Util\ClassDiscriminatorHelper;
 use ApiPlatform\State\ApiResource\Error;
+use Symfony\Component\Serializer\Mapping\ClassDiscriminatorResolverInterface;
 
 /**
  * Decorator factory which adds JSON:API properties to the JSON Schema document.
@@ -82,7 +84,7 @@ final class SchemaFactory implements SchemaFactoryInterface, SchemaFactoryAwareI
 
     private readonly ResourceLinkageResolver $resourceLinkageResolver;
 
-    public function __construct(private readonly SchemaFactoryInterface $schemaFactory, private readonly PropertyMetadataFactoryInterface $propertyMetadataFactory, ResourceClassResolverInterface $resourceClassResolver, ?ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory = null, private ?DefinitionNameFactoryInterface $definitionNameFactory = null, ?ResourceLinkageResolver $resourceLinkageResolver = null)
+    public function __construct(private readonly SchemaFactoryInterface $schemaFactory, private readonly PropertyMetadataFactoryInterface $propertyMetadataFactory, ResourceClassResolverInterface $resourceClassResolver, ?ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory = null, private ?DefinitionNameFactoryInterface $definitionNameFactory = null, ?ResourceLinkageResolver $resourceLinkageResolver = null, private readonly ?ClassDiscriminatorResolverInterface $classDiscriminatorResolver = null)
     {
         if (!$definitionNameFactory) {
             $this->definitionNameFactory = new DefinitionNameFactory();
@@ -377,15 +379,90 @@ private function buildDefinitionPropertiesSchema(string $key, string $className,
         // Only relax the requirement on the input schema; responses still always carry an `id`.
         $required = Schema::TYPE_INPUT === $type && $resourceOperation instanceof HttpOperation && 'POST' === $resourceOperation->getMethod() ? ['type'] : ['type', 'id'];
 
+        $data = [
+            'type' => 'object',
+            'properties' => $replacement,
+            'required' => $required,
+        ];
+
+        // Subtypes declared in a serializer discriminator map: the type property lives in "attributes" so an OpenAPI discriminator cannot be used
+        $typeProperty = null;
+        foreach ($this->getDiscriminatedSubtypes($key, $className, $definitions, $schema->getVersion()) as [$subKey, $subClass, $typeProperty]) {
+            $subSchema = $this->buildDefinitionPropertiesSchema($subKey, $subClass, $format, $type, $resourceOperation, $schema, $serializerContext);
+            $definitions = $schema->getDefinitions();
+            $subData = $subSchema['data'];
+            if (\in_array($typeProperty, $definitions[$subKey]['required'] ?? [], true)) {
+                $subData['properties']['attributes']['required'] = [ReservedAttributeNameConverter::JSON_API_RESERVED_ATTRIBUTES[$typeProperty] ?? $typeProperty];
+            }
+            $data['oneOf'][] = $subData;
+
+            foreach ($subSchema['included']['items']['anyOf'] ?? [] as $relatedDefinition) {
+                $relatedDefinitions[$relatedDefinition['$ref']] = $relatedDefinition;
+            }
+        }
+
+        // The inline "oneOf" branch of a class declared in its own discriminator map describes the instances of the class itself
+        foreach (null !== $typeProperty ? $definitions[$key]['oneOf'] : [] as $branch) {
+            if (isset($branch['$ref']) || !isset($branch['properties'][$typeProperty])) {
+                continue;
+            }
+
+            $attributeName = ReservedAttributeNameConverter::JSON_API_RESERVED_ATTRIBUTES[$typeProperty] ?? $typeProperty;
+            $ownData = $data;
+            unset($ownData['oneOf']);
+            $ownData['properties']['attributes']['properties'][$attributeName] = $branch['properties'][$typeProperty];
+            if (\in_array($typeProperty, $branch['required'] ?? [], true)) {
+                $ownData['properties']['attributes']['required'] = [$attributeName];
+            }
+            array_unshift($data['oneOf'], $ownData);
+        }
+
+        if ($relatedDefinitions && !$included) {
+            $included = [
+                'included' => [
+                    'description' => 'Related resources requested via the "include" query parameter.',
+                    'type' => 'array',
+                    'items' => [],
+                    'readOnly' => true,
+                    'externalDocs' => [
+                        'url' => 'https://jsonapi.org/format/#fetching-includes',
+                    ],
+                ],
+            ];
+        }
+
+        if ($included) {
+            $included['included']['items'] = ['anyOf' => array_values($relatedDefinitions)];
+        }
+
         return [
-            'data' => [
-                'type' => 'object',
-                'properties' => $replacement,
-                'required' => $required,
-            ],
+            'data' => $data,
         ] + $included;
     }
 
+    /**
+     * @return iterable<array{string, class-string, string}>
+     */
+    private function getDiscriminatedSubtypes(string $key, string $className, \ArrayObject $definitions, string $version): iterable
+    {
+        $discriminator = $definitions[$key]['discriminator'] ?? null;
+        if (null === $this->classDiscriminatorResolver || !isset($definitions[$key]['oneOf'], $discriminator['mapping']) || null === $mapping = $this->classDiscriminatorResolver->getMappingForClass($className)) {
+            return;
+        }
+
+        $prefix = $this->getSchemaUriPrefix($version);
+        foreach (ClassDiscriminatorHelper::getDirectSubtypes($mapping, $className) as $typeValue => $subClass) {
+            if (null === $ref = $discriminator['mapping'][$typeValue] ?? null) {
+                continue;
+            }
+
+            $subKey = substr($ref, \strlen($prefix));
+            if (isset($definitions[$subKey])) {
+                yield [$subKey, $subClass, $mapping->getTypeProperty()];
+            }
+        }
+    }
+
     private function getRelationship(string $resourceClass, string $property, ?array $serializerContext): ?array
     {
         $propertyMetadata = $this->propertyMetadataFactory->create($resourceClass, $property, $serializerContext ?? []);
@@ -400,6 +477,8 @@ private function getRelationship(string $resourceClass, string $property, ?array
         $relatedClasses = [];
         foreach ($relationships as [$className, $isCollection]) {
             $isOne = $isOne || !$isCollection;
+            // A relation narrowed to a subtype of a resource (e.g. declared in a discriminator map) targets the resource itself
+            $className = $this->resourceClassResolver->getResourceClass(null, $className);
             // @see https://github.com/api-platform/core/issues/5501
             // @see https://github.com/api-platform/core/pull/5722
             $relatedClasses[$className] = $this->resourceMetadataFactory->create($className)->getOperation()->canRead();

src/JsonApi/Tests/JsonSchema/SchemaFactoryTest.php

@@ -69,6 +69,7 @@ protected function setUp(): void
         );
 
         $resourceClassResolver = $this->prophesize(ResourceClassResolverInterface::class);
+        $resourceClassResolver->getResourceClass(null, Argument::type('string'))->willReturnArgument(1);
         $resourceClassResolver->isResourceClass(Dummy::class)->willReturn(true);
 
         $this->schemaFactory = new SchemaFactory(
@@ -312,6 +313,7 @@ private function buildSchemaFactoryWithPolymorphicRelation(): SchemaFactory
         );
 
         $resourceClassResolver = $this->prophesize(ResourceClassResolverInterface::class);
+        $resourceClassResolver->getResourceClass(null, Argument::type('string'))->willReturnArgument(1);
         $resourceClassResolver->isResourceClass(Dummy::class)->willReturn(true);
         $resourceClassResolver->isResourceClass(RelatedDummy::class)->willReturn(true);
         $resourceClassResolver->isResourceClass(OtherRelatedDummy::class)->willReturn(true);
@@ -374,6 +376,7 @@ private function buildSchemaFactoryWithRelation(): SchemaFactory
         );
 
         $resourceClassResolver = $this->prophesize(ResourceClassResolverInterface::class);
+        $resourceClassResolver->getResourceClass(null, Argument::type('string'))->willReturnArgument(1);
         $resourceClassResolver->isResourceClass(Dummy::class)->willReturn(true);
         $resourceClassResolver->isResourceClass(RelatedDummy::class)->willReturn(true);
 

src/JsonSchema/SchemaFactory.php

@@ -22,7 +22,9 @@
 use ApiPlatform\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
 use ApiPlatform\Metadata\ResourceClassResolverInterface;
+use ApiPlatform\Metadata\Util\ClassDiscriminatorHelper;
 use ApiPlatform\Metadata\Util\TypeHelper;
+use Symfony\Component\Serializer\Mapping\ClassDiscriminatorResolverInterface;
 use Symfony\Component\Serializer\NameConverter\NameConverterInterface;
 use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
 use Symfony\Component\TypeInfo\Type\BuiltinType;
@@ -48,7 +50,7 @@ final class SchemaFactory implements SchemaFactoryInterface, SchemaFactoryAwareI
     public const OPENAPI_DEFINITION_NAME = 'openapi_definition_name';
     public const PARTIAL_UPDATE = 'partial_update';
 
-    public function __construct(ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory, private readonly PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, private readonly PropertyMetadataFactoryInterface $propertyMetadataFactory, private readonly ?NameConverterInterface $nameConverter = null, ?ResourceClassResolverInterface $resourceClassResolver = null, private ?DefinitionNameFactoryInterface $definitionNameFactory = null)
+    public function __construct(ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory, private readonly PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, private readonly PropertyMetadataFactoryInterface $propertyMetadataFactory, private readonly ?NameConverterInterface $nameConverter = null, ?ResourceClassResolverInterface $resourceClassResolver = null, private ?DefinitionNameFactoryInterface $definitionNameFactory = null, private readonly ?ClassDiscriminatorResolverInterface $classDiscriminatorResolver = null)
     {
         if (!$definitionNameFactory) {
             $this->definitionNameFactory = new DefinitionNameFactory();
@@ -152,22 +154,140 @@ public function buildSchema(string $className, string $format = 'json', string $
         }
 
         $options = ['schema_type' => $type] + $this->getFactoryOptions($serializerContext, $validationGroups, $operation instanceof HttpOperation ? $operation : null);
-        foreach ($this->propertyNameCollectionFactory->create($inputOrOutputClass, $options) as $propertyName) {
-            $propertyMetadata = $this->propertyMetadataFactory->create($inputOrOutputClass, $propertyName, $options);
+        $this->buildDefinitionProperties($schema, $definition, $definitionName, $inputOrOutputClass, $options, $serializerContext, $format, $type, $isPartialUpdate);
+
+        // Subtypes explicitly declared in a serializer discriminator map are documented using "oneOf" and an OpenAPI "discriminator"
+        $this->buildDiscriminatedDefinitions($schema, $definition, $className, $inputOrOutputClass, $definitionFormat, $operation, $options, $serializerContext, $serializerContext + [
+            'schema_type' => $type,
+            self::PARTIAL_UPDATE => $isPartialUpdate && !$isJsonMergePatch,
+        ], $format, $type, $isPartialUpdate);
+
+        return $schema;
+    }
+
+    /**
+     * @param \ArrayObject<string, mixed> $definition
+     */
+    private function buildDefinitionProperties(Schema $schema, \ArrayObject $definition, string $definitionName, string $class, array $options, array $serializerContext, string $format, string $type, bool $isPartialUpdate): void
+    {
+        foreach ($this->propertyNameCollectionFactory->create($class, $options) as $propertyName) {
+            $propertyMetadata = $this->propertyMetadataFactory->create($class, $propertyName, $options);
 
             if (false === $propertyMetadata->isReadable() && false === $propertyMetadata->isWritable()) {
                 continue;
             }
 
-            $normalizedPropertyName = $this->nameConverter ? $this->nameConverter->normalize($propertyName, $inputOrOutputClass, $format, $serializerContext) : $propertyName;
+            $normalizedPropertyName = $this->nameConverter ? $this->nameConverter->normalize($propertyName, $class, $format, $serializerContext) : $propertyName;
             if ($propertyMetadata->isRequired() && !$isPartialUpdate) {
                 $definition['required'][] = $normalizedPropertyName;
             }
 
             $this->buildPropertySchema($schema, $definitionName, $normalizedPropertyName, $propertyMetadata, $serializerContext, $format, $type);
         }
+    }
 
-        return $schema;
+    /**
+     * @param \ArrayObject<string, mixed>         $definition
+     * @param array<string, array<string, mixed>> $parentTypeProperties type properties of the outer discriminator maps the class belongs to
+     */
+    private function buildDiscriminatedDefinitions(Schema $schema, \ArrayObject $definition, string $className, string $class, string $definitionFormat, ?Operation $operation, array $options, array $serializerContext, array $definitionNameContext, string $format, string $type, bool $isPartialUpdate, array $parentTypeProperties = []): void
+    {
+        if (null === $this->classDiscriminatorResolver || null === $mapping = $this->classDiscriminatorResolver->getMappingForClass($class)) {
+            return;
+        }
+
+        $typeProperty = $mapping->getTypeProperty();
+        $definitions = $schema->getDefinitions();
+        $prefix = $this->getSchemaUriPrefix($schema->getVersion());
+        $discriminatorMapping = [];
+        $oneOf = [];
+
+        foreach (ClassDiscriminatorHelper::getDirectSubtypes($mapping, $class) as $typeValue => $subClass) {
+            $subDefinitionName = $this->definitionNameFactory->create($className, $definitionFormat, $subClass, $operation, $definitionNameContext);
+            $discriminatorMapping[$typeValue] = $oneOf[]['$ref'] = $prefix.$subDefinitionName;
+
+            if (isset($definitions[$subDefinitionName])) {
+                continue;
+            }
+
+            /** @var \ArrayObject<string, mixed> $subDefinition */
+            $subDefinition = new \ArrayObject(['type' => 'object']);
+            $definitions[$subDefinitionName] = $subDefinition;
+            if (isset($definition['additionalProperties'])) {
+                $subDefinition['additionalProperties'] = $definition['additionalProperties'];
+            }
+
+            $this->buildDefinitionProperties($schema, $subDefinition, $subDefinitionName, $subClass, $options, $serializerContext, $format, $type, $isPartialUpdate);
+
+            // The type properties of the outer maps are part of the payload of a nested subtype too
+            $typeProperties = $parentTypeProperties + [$typeProperty => ['type' => 'string', 'enum' => [(string) $typeValue]]];
+            $this->addTypeProperties($subDefinition, $typeProperties, $isPartialUpdate);
+
+            $this->buildDiscriminatedDefinitions($schema, $subDefinition, $className, $subClass, $definitionFormat, $operation, $options, $serializerContext, $definitionNameContext, $format, $type, $isPartialUpdate, $typeProperties);
+        }
+
+        $ownTypeValues = ClassDiscriminatorHelper::getOwnTypes($mapping, $class);
+        foreach ($ownTypeValues as $typeValue) {
+            $discriminatorMapping[$typeValue] = $prefix.$this->definitionNameFactory->create($className, $definitionFormat, $class, $operation, $definitionNameContext);
+        }
+
+        if (!$discriminatorMapping) {
+            return;
+        }
+
+        if ($oneOf) {
+            // An instance of the class itself is described by its own branch: it carries its own type and none of the subtype properties
+            if ($ownTypeValues) {
+                $ownBranch = new \ArrayObject(['type' => 'object']);
+                foreach (['properties', 'required', 'additionalProperties'] as $keyword) {
+                    if (isset($definition[$keyword])) {
+                        $ownBranch[$keyword] = $definition[$keyword];
+                    }
+                }
+
+                $this->addTypeProperties($ownBranch, [$typeProperty => ['type' => 'string', 'enum' => $ownTypeValues]], $isPartialUpdate || \in_array($mapping->getDefaultType(), $ownTypeValues, true));
+                array_unshift($oneOf, $ownBranch->getArrayCopy());
+            }
+
+            $definition['oneOf'] = $oneOf;
+
+            // "additionalProperties" ignores the properties declared in the "oneOf" branches, they are restricted by the branches instead
+            unset($definition['additionalProperties']);
+        }
+
+        // An instance of the class itself carries its own type
+        if ($ownTypeValues && !isset($definition['properties'][$typeProperty])) {
+            if ($oneOf) {
+                $properties = $definition['properties'] ?? [];
+                $properties[$typeProperty] = ['type' => 'string', 'enum' => array_map('strval', array_keys($discriminatorMapping))];
+                $definition['properties'] = $properties;
+            } else {
+                $this->addTypeProperties($definition, [$typeProperty => ['type' => 'string', 'enum' => $ownTypeValues]], $isPartialUpdate || \in_array($mapping->getDefaultType(), $ownTypeValues, true));
+            }
+        }
+
+        $definition['discriminator'] = ['propertyName' => $typeProperty, 'mapping' => $discriminatorMapping];
+    }
+
+    /**
+     * @param \ArrayObject<string, mixed>         $definition
+     * @param array<string, array<string, mixed>> $typeProperties
+     */
+    private function addTypeProperties(\ArrayObject $definition, array $typeProperties, bool $optional): void
+    {
+        $properties = $definition['properties'] ?? [];
+        $required = $definition['required'] ?? [];
+        foreach ($typeProperties as $name => $typePropertySchema) {
+            $properties[$name] = $typePropertySchema;
+            if (!$optional && !\in_array($name, $required, true)) {
+                $required[] = $name;
+            }
+        }
+
+        $definition['properties'] = $properties;
+        if ($required) {
+            $definition['required'] = $required;
+        }
     }
 
     private function buildPropertySchema(Schema $schema, string $definitionName, string $normalizedPropertyName, ApiProperty $propertyMetadata, array $serializerContext, string $format, string $parentType): void

src/JsonSchema/Tests/Fixtures/Discriminator/DiscriminatedAnimal.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\JsonSchema\Tests\Fixtures\Discriminator;
+
+use Symfony\Component\Serializer\Attribute\DiscriminatorMap;
+
+#[DiscriminatorMap(typeProperty: 'species', mapping: ['cat' => DiscriminatedCat::class, 'dog' => DiscriminatedDog::class])]
+abstract class DiscriminatedAnimal
+{
+    public string $name = '';
+}

src/JsonSchema/Tests/Fixtures/Discriminator/DiscriminatedCat.php

@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\JsonSchema\Tests\Fixtures\Discriminator;
+
+final class DiscriminatedCat extends DiscriminatedAnimal
+{
+    public int $lives = 9;
+}