[dylan-rumble]

Q	A
Branch?	main
Tickets	Closes #2931, supersedes #7815
License	MIT
Doc PR	api-platform/docs#...

A resource can now declare its subtypes with Symfony's #[DiscriminatorMap]. This works for every operation (GET, GetCollection, POST, PUT, PATCH, DELETE), in JSON-LD, JSON, JSON:API and HAL, and in the generated JSON Schema / OpenAPI.

The map is the opt-in. #2931 was closed because exposing subclass properties leaks data. Here, only classes listed in a serializer map are exposed. An unmapped subclass is still serialized as its closest mapped parent, and resources without a map behave exactly as before. Deriving the map from Doctrine inheritance is a separate opt-in (discriminator_map, disabled by default), see below.

#[ApiResource(operations: [new Get(), new GetCollection(), new Post(), new Put(), new Patch(), new Delete()])]
#[DiscriminatorMap(typeProperty: 'kind', mapping: [
    'fiction' => DiscriminatedFictionBook::class,
    'technical' => DiscriminatedTechnicalBook::class,
])]
abstract class DiscriminatedBook { /* ... */ }

// tests/Functional/DiscriminatedResourceTest.php
public function testPostCreatesTheMappedSubtype(): void
{
    $response = self::createClient()->request('POST', '/discriminated_books', [
        'headers' => ['Content-Type' => 'application/ld+json'],
        'json' => [
            'kind' => 'technical',
            'title' => 'Refactoring',
            'programmingLanguage' => 'Java',
            'internalNote' => 'cannot be written anonymously', // subtype property with `security`
        ],
    ]);

    $this->assertResponseStatusCodeSame(201);
    $this->assertEquals([
        '@context' => '/contexts/DiscriminatedBook',
        '@id' => '/discriminated_books/4',
        '@type' => 'DiscriminatedBook',
        'kind' => 'technical',
        'id' => 4,
        'title' => 'Refactoring',
        'programmingLanguage' => 'Java',
    ], $response->toArray());
    $this->assertInstanceOf(DiscriminatedTechnicalBook::class, DiscriminatedBookStore::$books[4]);
    $this->assertNull(DiscriminatedBookStore::$books[4]->internalNote);
}

public function testPatchCannotChangeTheType(): void
{
    self::createClient()->request('PATCH', '/discriminated_books/1', [
        'headers' => ['Content-Type' => 'application/merge-patch+json'],
        'json' => ['kind' => 'technical', 'programmingLanguage' => 'Rust'],
    ]);

    $this->assertResponseStatusCodeSame(400);
    $this->assertInstanceOf(DiscriminatedFictionBook::class, DiscriminatedBookStore::$books[1]);
}

Tests

File	Covers
DiscriminatedResourceTest	All operations and formats, subtype security, unmapped subclasses, resources without a map, attribute cache across users, OpenAPI
DiscriminatedResourceOverrideTest	Overridden ApiProperty and constraints, narrowed relations, covariant getters
DiscriminatedNestedResourceTest	A subtype with its own map (kind + breed), allow_extra_attributes: false, schema validated against real payloads
DiscriminatedSelfMappedResourceTest	A class listing itself in its own map
DoctrineDiscriminatedResourceTest	Subtypes from ORM\DiscriminatorMap only (discriminator_map enabled through DoctrineDiscriminatorMapAppKernel): all operations, JSON:API/HAL, subtype security, a non-resource subtype, POST of a grandchild through a mid-hierarchy resource, JOINED with integer keys, serializer map precedence, OpenAPI
DoctrineDiscriminatedDocumentTest	The same for MongoDB ODM (runs in the MongoDB job)

Unit tests: DoctrineDiscriminatorMappingLoaderTest, SerializerMappingLoaderPassTest, extension/configuration tests for the flag, ClassDiscriminatorHelperTest (including a cyclic map), and SchemaFactoryTest in JsonSchema and JsonApi.

How it works

• AbstractItemNormalizer
  • The allowed attributes and metadata come from the mapped subtype, and the type property is added to the output.
  • Nested maps resolve to the most specific class.
  • A PATCH that changes the type returns a 400.
  • isCacheKeySafe() also checks the subtypes' properties.
• JsonSchema\SchemaFactory / JsonApi\JsonSchema\SchemaFactory
  • Each subtype gets its own complete definition (inherited properties included). The base only holds oneOf and an OpenAPI discriminator: the common properties are not repeated next to oneOf, so Swagger UI doesn't show them twice. Subtypes never reference the base, so there are no circular refs.
  • A concrete class listed in its own map gets an inline oneOf branch describing its own instances.
  • Each subtype definition keeps its own additionalProperties.
  • JSON:API: the type property is an attribute, so no OpenAPI discriminator is used. The base <Resource>.jsonapi.resource definition holds a oneOf of one <Resource>.jsonapi.<Subtype>.resource definition per subtype.
• ClassDiscriminatorHelper (@internal) is the single walker over the maps. It only goes down to strict subclasses, so it always terminates.
• Constructors of both schema factories take a new optional last argument, ?ClassDiscriminatorResolverInterface. It is wired for Symfony and Laravel.
• Dependencies: api-platform/json-schema, api-platform/serializer and api-platform/json-api now require api-platform/metadata ^5.1 (for ClassDiscriminatorHelper). Like doctrine-orm/doctrine-odm on main, their "lowest"/"minimal-changes" jobs can't resolve until 5.1 is released.

Doctrine discriminator maps (second commit)

Doctrine inheritance already declares the subtypes, so declaring them again for the serializer shouldn't be required. DoctrineDiscriminatorMappingLoader is a serializer mapping loader that exposes the ORM/ODM discriminator map as a serializer ClassDiscriminatorMapping:

#[ApiResource]
#[ORM\Entity]
#[ORM\InheritanceType('SINGLE_TABLE')]
#[ORM\DiscriminatorColumn(name: 'kind')]
#[ORM\DiscriminatorMap(['car' => Car::class, 'sportsCar' => SportsCar::class, 'truck' => Truck::class])]
abstract class Vehicle { /* ... */ }

• Only API resource hierarchies are affected; plain entities serialized elsewhere are left alone.
• An explicit serializer #[DiscriminatorMap] anywhere in the hierarchy wins, so you can still expose a subset.
• Every non-leaf class gets a map of itself and its subclasses, so a mid-hierarchy resource (POST /cars creating a SportsCar) resolves too.
• The type property is the discriminator column (ORM) or field (ODM); integer values are exposed as strings.
• The loader is appended to serializer.mapping.chain_loader and the cache warmer by SerializerMappingLoaderPass.
• Off by default, so existing Doctrine inheritance resources don't start exposing (and accepting) subclass properties on upgrade. Enable it with:

api_platform:
    doctrine:
        discriminator_map: true
    doctrine_mongodb_odm:
        discriminator_map: true

DoctrineDiscriminatorSerializerPropertyMetadataFactory (#8283) is untouched; part of it may become redundant, which could be a follow-up.

Behavior changes for existing #[DiscriminatorMap] resources

No public API breaks. Resources that already carry a serializer map will see:

• Subtype properties and the type property in responses (previously trimmed to the base class).
• Subtype properties accepted on write.
• oneOf and discriminator in schemas. The base definition only lists its subtypes: no properties, required or additionalProperties of its own.
• JSON:API relations typed with a subtype resolving to their resource.
• IRIs to discriminated abstract relations no longer throwing.

Behavior changes for existing Doctrine inheritance resources

None by default: discriminator_map is disabled, and TableInheritanceTest is unchanged.

Once enabled:

• STI/JOINED resources expose the discriminator property and mapped subclass properties, and accept them on write. POST to a parent resource requires the discriminator unless the class itself is concrete and mapped.
• Doctrine subclasses that are not #[ApiResource] are serialized as their own subtype instead of as the parent.
• A serializer #[DiscriminatorMap] subset still takes precedence, to only expose some subtypes.

If you would rather put the serializer map support behind a configuration flag too, every touch point is listed above and I'm happy to add it.

[dylan-rumble]

I just realised the code as is will not read the ORM\DiscriminatorMap and only respect Symfony\Component\Serializer\Attribute\DiscriminatorMap. Its a bit awkward to double declare this, looking into if I can simplify it.

[dylan-rumble]

@soyuka without going in depth into the code in the PR, what is your opinion on this feature? it would allow both reads and writes to entities using a discriminator column with any sort of InheritanceType. For custom database types that map json to objects for example, the Symfony DiscriminatorMap can be used.

Right now we have to make a seperate api resource for every single subclass in our code that uses doctrine inheritance.

[soyuka]

Yeah its quite interesting I haven't yet looked at the code @Maxcastel has something going on at #7815 I think that with both pr we should be able to get some quite nice new feature.

Not sure how to go forward, I can read the code if you think its close to be mergeable, let me know. Can you also run an agent to check if #7815 could maybe be adapted ?

[dylan-rumble]

I think as is its fairly close to mergable, but I won't have time for a while to spend time into looking into the tests. I will get around to it eventually. I did review #7815 when creating this one, it didn't account for a lot of things. I no longer have the comprehensive list anymore.

I'll let you know when I finish the PR.

[philpichet]

Hi @dylan-rumble, thanks for this PR! I tested it on a small app (Symfony 7.4, PHP 8.4, SQLite) with a Doctrine-only setup, and wanted to share some feedback.

Test case: JOINED inheritance, Doctrine discriminator map only

#[ORM\Entity]
#[ORM\InheritanceType('JOINED')]
#[ORM\DiscriminatorColumn(name: 'type', type: 'string')]
#[ORM\DiscriminatorMap(['car' => Car::class, 'bike' => Bike::class])]
#[ApiResource]
abstract class Vehicle
{
    #[ORM\Id, ORM\GeneratedValue, ORM\Column]
    public ?int $id = null;

    #[ORM\Column]
    public string $brand = '';
}

#[ORM\Entity]
class Car extends Vehicle
{
    #[ORM\Column]
    public int $doors = 4;
}

#[ORM\Entity]
class Bike extends Vehicle
{
    #[ORM\Column]
    public bool $electric = false;
}

No Symfony #[DiscriminatorMap] and no #[ApiResource] on the subclasses. Everything works:

• GET /vehicles returns {"type":"car","doors":5,...} and {"type":"bike","electric":true,...}; on 4.4 only id and brand were returned
• POST /vehicles with {"type":"bike",...} creates a Bike
• PATCH changing type is rejected with a 400
• OpenAPI documents oneOf + discriminator with a Vehicle.Car / Vehicle.Bike schema per format

The related tests (Discriminated*Test, DoctrineDiscriminatedResourceTest, TableInheritanceTest, the SchemaFactoryTests) pass locally, except DoctrineDiscriminatorMappingLoaderTest::testMongoDbOdmDiscriminatorField, which only failed because the ODM isn't installed in my environment.

Suggestion: only oneOf on the parent schema

The parent schema currently keeps the common properties next to oneOf:

"Vehicle": {
  "type": "object",
  "properties": { "id": {...}, "brand": {...} },
  "required": ["brand"],
  "oneOf": [{ "$ref": "#/components/schemas/Vehicle.Car" }, { "$ref": "#/components/schemas/Vehicle.Bike" }],
  "discriminator": {...}
}

Each branch already contains all of its properties (Vehicle.Bike = id, brand, electric, type), so Swagger UI shows id and brand twice: once at the top level and again in each oneOf branch. Keeping only oneOf + discriminator on the parent makes it much easier to read, and each branch stays a complete description of one subtype:

+            // Every branch carries the common properties: they are not repeated next to "oneOf"
             // "additionalProperties" ignores the properties declared in the "oneOf" branches, they are restricted by the branches instead
-            unset($definition['additionalProperties']);
+            unset($definition['properties'], $definition['required'], $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));
-            }
+        if ($ownTypeValues && !$oneOf && !isset($definition['properties'][$typeProperty])) {
+            $this->addTypeProperties($definition, [$typeProperty => ['type' => 'string', 'enum' => $ownTypeValues]], $isPartialUpdate || \in_array($mapping->getDefaultType(), $ownTypeValues, true));
         }

A concrete parent declared in its own map is still covered by the branch you already add in front of oneOf. With this change, 5 schema assertions read properties on the parent and would need to read the branches instead (SchemaFactoryTest ×2, DiscriminatedResourceTest::testOpenApiDocumentsSubtypes, DiscriminatedResourceOverrideTest ×2); the serialization tests are unaffected. Of course, it's your call.

Question: discriminator_map enabled by default

The description says the map is the opt-in and resources without one behave as before. But with doctrine.discriminator_map / doctrine_mongodb_odm.discriminator_map defaulting to true, an existing resource with Doctrine inheritance (like the one above) starts exposing its subclass properties after the upgrade, which is the data-leak concern that closed #2931. Would defaulting to false (or at least an UPGRADE note) make sense?

Help

The branch is currently 106 commits behind main. If it helps, I'd be happy to take care of the rebase and/or the test updates and open a PR against your branch, so you stay in control of what gets in. Just let me know.

[dylan-rumble]

Thanks a lot for testing this and for the detailed feedback @philpichet!

• Rebase: the branch is now rebased on main. This needed some conflict resolution in the JSON:API schema factory: it now follows the new .resource definitions and strict_member_names.
• Only oneOf on the parent schema: applied your suggestion (05f1643). The parent definition only holds oneOf + discriminator, each branch is a complete description of its subtype. I applied the same to JSON:API: the parent .resource definition only holds the oneOf of the subtype resource objects, and a concrete class in its own map keeps an inline branch for its own instances. The 5 assertions you mentioned are updated, and DiscriminatedResourceTest::testOpenApiParentSchemaOnlyListsItsSubtypes checks this for JSON, JSON-LD, input, merge-patch and JSON:API.
• CI: json-schema, serializer and json-api now require api-platform/metadata ^5.1 since they use the new ClassDiscriminatorHelper (345e28d). The remaining "lowest"/"minimal-changes" failures (doctrine, openapi, symfony) also fail on main.

I've updated the PR description accordingly.

[dylan-rumble]

Following up on the question about #7815 and whether this is close to mergeable.

Comparison with #7815

I compared both PRs. This one covers what #7815 does, and also:

• Reads the map through Symfony's ClassDiscriminatorResolverInterface instead of reflecting on the attribute directly, so YAML/XML serializer mappings work too.
• Avoids a circular allOf. The parent schema is a oneOf of its subtypes only (see philpichet's review).
• Supports writes (POST/PUT/PATCH with the discriminator), not only reads.
• Doesn't leak subtype required fields into the parent schema.
• Covers JSON-LD/Hydra, JSON:API, HAL, plain JSON and the OpenAPI docs.

Adapting #7815 would mean re-implementing most of this, so I think it's simpler to continue here. Thanks to Maxcastel for the groundwork, which helped shape this.

What I think is mergeable

1. Serializer #[DiscriminatorMap] support (first commit). This is the core feature and is opt-in by design: nothing changes unless a resource declares a map, and only classes listed in the map are exposed. This addresses the data-leak concern from Entity inheritance normalises based on parent class #2931. I consider this part ready.
2. Schema fix (philpichet's review) and the api-platform/metadata ^5.1 constraint bump go with (1).
3. Deriving the map from Doctrine inheritance (Doctrine commit). This was the part with real BC/exposure risk, because it changed the output of existing STI/JOINED resources. I've changed discriminator_map to be disabled by default, so upgrading changes nothing. You enable it explicitly under api_platform.doctrine / api_platform.doctrine_mongodb_odm. If you'd prefer to review it separately, I can split it into its own PR.

The remaining CI failures also happen on main (doctrine ^5.1 not yet released, getResponseHeaders, STRICT_RESOURCE_TYPE). The only failures caused by this PR were the ones needing metadata ^5.1, which is now required explicitly.

Next steps

Before asking for a review, I'll test this in our production application, including the Doctrine opt-in. I'll post here when it's ready for review.

[dylan-rumble]

@soyuka I extensively tested all API operations and everything works:

• You can now read and write properties of subtypes of an API resource (subclasses declared in the resource's discriminator map, without them having to be resources themselves).
• A Symfony serializer DiscriminatorMap now properly shows up in the OpenAPI spec too, e.g. when a property holds a polymorphic object persisted as JSON through a custom Doctrine type.

Could you review the PR when you have a moment? Thanks!