api-platform · abderrahimghazali · Apr 26, 2026 · Apr 27, 2026 · Apr 27, 2026 · Apr 27, 2026
diff --git a/src/JsonApi/JsonSchema/SchemaFactory.php b/src/JsonApi/JsonSchema/SchemaFactory.php
@@ -20,6 +20,7 @@
 use ApiPlatform\JsonSchema\SchemaFactoryAwareInterface;
 use ApiPlatform\JsonSchema\SchemaFactoryInterface;
 use ApiPlatform\JsonSchema\SchemaUriPrefixTrait;
+use ApiPlatform\Metadata\HttpOperation;
 use ApiPlatform\Metadata\Operation;
 use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
@@ -282,6 +283,10 @@ public function setSchemaFactory(SchemaFactoryInterface $schemaFactory): void
 
     private function buildDefinitionPropertiesSchema(string $key, string $className, string $format, string $type, ?Operation $operation, Schema $schema, ?array $serializerContext): array
     {
+        // Capture the operation for the resource being built; the loop below
+        // reassigns $operation while resolving relationships.
+        $resourceOperation = $operation;
+
         $definitions = $schema->getDefinitions();
         $properties = $definitions[$key]['properties'] ?? [];
 
@@ -369,11 +374,18 @@ private function buildDefinitionPropertiesSchema(string $key, string $className,
             ];
         }
 
+        // Per JSON:API spec, `id` is optional in the request body of a creation:
+        // https://jsonapi.org/format/#crud-creating
+        $required = ['type', 'id'];
+        if (Schema::TYPE_INPUT === $type && $resourceOperation instanceof HttpOperation && 'POST' === $resourceOperation->getMethod()) {
+            $required = ['type'];
+        }
+
         return [
             'data' => [
                 'type' => 'object',
                 'properties' => $replacement,
-                'required' => ['type', 'id'],
+                'required' => $required,
             ],
         ] + $included;
     }

diff --git a/src/JsonApi/Serializer/ItemNormalizer.php b/src/JsonApi/Serializer/ItemNormalizer.php
@@ -61,6 +61,14 @@ final class ItemNormalizer extends AbstractItemNormalizer
 
     public const FORMAT = 'jsonapi';
 
+    /**
+     * Denormalization context flag enabling client-generated IDs on POST, per
+     * https://jsonapi.org/format/#crud-creating-client-ids
+     * Off by default to prevent ID spoofing on public endpoints. Can be set
+     * globally via the bundle configuration or per-call in the context.
+     */
+    public const ALLOW_CLIENT_GENERATED_ID = 'allow_client_generated_id';
+
     private array $componentsCache = [];
     private bool $useIriAsId;
 
@@ -207,21 +215,27 @@ public function denormalize(mixed $data, string $type, ?string $format = null, a
             return parent::denormalize($data, $type, $format, $context);
         }
 
+        $operation = $context['operation'] ?? null;
+        $isPostOperation = $operation instanceof HttpOperation && 'POST' === $operation->getMethod();
+        $allowClientGeneratedId = true === ($context[self::ALLOW_CLIENT_GENERATED_ID] ?? $this->defaultContext[self::ALLOW_CLIENT_GENERATED_ID] ?? false);
+
         // Avoid issues with proxies if we populated the object
         if (!isset($context[self::OBJECT_TO_POPULATE]) && isset($data['data']['id'])) {
-            if (true !== ($context['api_allow_update'] ?? true)) {
+            if ($isPostOperation) {
+                if (!$allowClientGeneratedId) {
+                    throw new NotNormalizableValueException(\sprintf('Client-generated IDs are not allowed on this operation. Set the "%s" denormalization context flag (or the corresponding bundle configuration) to enable it.', self::ALLOW_CLIENT_GENERATED_ID));
+                }
+                // Fall through: id flows into the denormalized payload below.
+            } elseif (true !== ($context['api_allow_update'] ?? true)) {
                 throw new NotNormalizableValueException('Update is not allowed for this operation.');
-            }
-
-            $context += ['fetch_data' => false];
-            if ($this->useIriAsId) {
-                $context[self::OBJECT_TO_POPULATE] = $this->iriConverter->getResourceFromIri(
-                    $data['data']['id'],
-                    $context
-                );
             } else {
-                $operation = $context['operation'] ?? null;
-                if ($operation instanceof HttpOperation) {
+                $context += ['fetch_data' => false];
+                if ($this->useIriAsId) {
+                    $context[self::OBJECT_TO_POPULATE] = $this->iriConverter->getResourceFromIri(
+                        $data['data']['id'],
+                        $context
+                    );
+                } elseif ($operation instanceof HttpOperation) {
                     $iri = $this->reconstructIri($type, (string) $data['data']['id'], $operation);
                     $context[self::OBJECT_TO_POPULATE] = $this->iriConverter->getResourceFromIri($iri, $context);
                 }
@@ -234,6 +248,11 @@ public function denormalize(mixed $data, string $type, ?string $format = null, a
             $data['data']['relationships'] ?? []
         );
 
+        // Surface the client-generated id so the entity setter receives it.
+        if ($isPostOperation && $allowClientGeneratedId && isset($data['data']['id'])) {
+            $dataToDenormalize['id'] = $data['data']['id'];
+        }
+
         return parent::denormalize(
             $dataToDenormalize,
             $type,

diff --git a/src/JsonApi/Tests/JsonSchema/SchemaFactoryTest.php b/src/JsonApi/Tests/JsonSchema/SchemaFactoryTest.php
@@ -22,6 +22,7 @@
 use ApiPlatform\Metadata\Get;
 use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\Operations;
+use ApiPlatform\Metadata\Post;
 use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
 use ApiPlatform\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
 use ApiPlatform\Metadata\Property\PropertyNameCollection;
@@ -49,6 +50,7 @@ protected function setUp(): void
         );
         $propertyNameCollectionFactory = $this->prophesize(PropertyNameCollectionFactoryInterface::class);
         $propertyNameCollectionFactory->create(Dummy::class, ['enable_getter_setter_extraction' => true, 'schema_type' => Schema::TYPE_OUTPUT])->willReturn(new PropertyNameCollection());
+        $propertyNameCollectionFactory->create(Dummy::class, ['enable_getter_setter_extraction' => true, 'schema_type' => Schema::TYPE_INPUT])->willReturn(new PropertyNameCollection());
         $propertyMetadataFactory = $this->prophesize(PropertyMetadataFactoryInterface::class);
 
         $definitionNameFactory = new DefinitionNameFactory(null);
@@ -164,4 +166,22 @@ public function testSchemaTypeBuildSchema(): void
         $forcedCollection = $this->schemaFactory->buildSchema(Dummy::class, 'jsonapi', Schema::TYPE_OUTPUT, forceCollection: true);
         $this->assertEquals($resultSchema['allOf'][0]['$ref'], $forcedCollection['allOf'][0]['$ref']);
     }
+
+    public function testBuildSchemaForPostInputDoesNotRequireId(): void
+    {
+        $resultSchema = $this->schemaFactory->buildSchema(Dummy::class, 'jsonapi', Schema::TYPE_INPUT, new Post());
+        $rootDefinitionKey = $resultSchema->getRootDefinitionKey();
+        $properties = $resultSchema['definitions'][$rootDefinitionKey]['properties'];
+
+        $this->assertSame(['type'], $properties['data']['required']);
+    }
+
+    public function testBuildSchemaForPostOutputStillRequiresId(): void
+    {
+        $resultSchema = $this->schemaFactory->buildSchema(Dummy::class, 'jsonapi', Schema::TYPE_OUTPUT, new Post());
+        $rootDefinitionKey = $resultSchema->getRootDefinitionKey();
+        $properties = $resultSchema['definitions'][$rootDefinitionKey]['properties'];
+
+        $this->assertSame(['type', 'id'], $properties['data']['required']);
+    }
 }
diff --git a/src/JsonApi/Tests/Serializer/ItemNormalizerTest.php b/src/JsonApi/Tests/Serializer/ItemNormalizerTest.php
@@ -26,6 +26,7 @@
 use ApiPlatform\Metadata\IriConverterInterface;
 use ApiPlatform\Metadata\Link;
 use ApiPlatform\Metadata\Operations;
+use ApiPlatform\Metadata\Post;
 use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
 use ApiPlatform\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
 use ApiPlatform\Metadata\Property\PropertyNameCollection;
@@ -989,4 +990,151 @@ public function testDenormalizeInputDtoDoesNotDoubleUnwrapJsonApiStructure(): vo
         $this->assertSame('Hello', $result->title);
         $this->assertSame('World', $result->body);
     }
+
+    public function testDenormalizePostWithIdThrowsWithoutOptIn(): void
+    {
+        $this->expectException(NotNormalizableValueException::class);
+        $this->expectExceptionMessage('Client-generated IDs are not allowed on this operation.');
+
+        $normalizer = new ItemNormalizer(
+            $this->prophesize(PropertyNameCollectionFactoryInterface::class)->reveal(),
+            $this->prophesize(PropertyMetadataFactoryInterface::class)->reveal(),
+            $this->prophesize(IriConverterInterface::class)->reveal(),
+            $this->prophesize(ResourceClassResolverInterface::class)->reveal(),
+        );
+
+        $normalizer->denormalize(
+            [
+                'data' => [
+                    'id' => 'b1f3e6a4-1234-4abc-9def-0123456789ab',
+                    'type' => 'dummy',
+                ],
+            ],
+            Dummy::class,
+            ItemNormalizer::FORMAT,
+            [
+                'operation' => new Post(),
+            ]
+        );
+    }
+
+    public function testDenormalizePostWithIdSucceedsWithOptIn(): void
+    {
+        $clientId = 'b1f3e6a4-1234-4abc-9def-0123456789ab';
+        $data = [
+            'data' => [
+                'type' => 'dummy',
+                'id' => $clientId,
+                'attributes' => [
+                    'name' => 'foo',
+                ],
+            ],
+        ];
+
+        $propertyNameCollectionFactoryProphecy = $this->prophesize(PropertyNameCollectionFactoryInterface::class);
+        $propertyNameCollectionFactoryProphecy->create(Dummy::class, Argument::any())->willReturn(new PropertyNameCollection(['id', 'name']));
+
+        $propertyMetadataFactoryProphecy = $this->prophesize(PropertyMetadataFactoryInterface::class);
+        $propertyMetadataFactoryProphecy->create(Dummy::class, 'id', Argument::any())->willReturn((new ApiProperty())->withNativeType(Type::string())->withReadable(false)->withWritable(true)->withIdentifier(true));
+        $propertyMetadataFactoryProphecy->create(Dummy::class, 'name', Argument::any())->willReturn((new ApiProperty())->withNativeType(Type::string())->withReadable(false)->withWritable(true));
+
+        // The IRI converter MUST NOT be queried for an existing resource on POST with a client-generated id.
+        $iriConverterProphecy = $this->prophesize(IriConverterInterface::class);
+        $iriConverterProphecy->getResourceFromIri(Argument::cetera())->shouldNotBeCalled();
+
+        $propertyAccessorProphecy = $this->prophesize(PropertyAccessorInterface::class);
+        $propertyAccessorProphecy->setValue(Argument::type(Dummy::class), 'name', 'foo')->shouldBeCalled();
+        $propertyAccessorProphecy->setValue(Argument::type(Dummy::class), 'id', $clientId)->shouldBeCalled();
+
+        $resourceClassResolverProphecy = $this->prophesize(ResourceClassResolverInterface::class);
+        $resourceClassResolverProphecy->getResourceClass(null, Dummy::class)->willReturn(Dummy::class);
+        $resourceClassResolverProphecy->isResourceClass(Dummy::class)->willReturn(true);
+
+        $resourceMetadataCollectionFactory = $this->prophesize(ResourceMetadataCollectionFactoryInterface::class);
+        $resourceMetadataCollectionFactory->create(Dummy::class)->willReturn(new ResourceMetadataCollection(Dummy::class, [
+            (new ApiResource())->withOperations(new Operations([new Post(name: 'post')])),
+        ]));
+
+        $serializerProphecy = $this->prophesize(SerializerInterface::class);
+        $serializerProphecy->willImplement(NormalizerInterface::class);
+
+        $normalizer = new ItemNormalizer(
+            $propertyNameCollectionFactoryProphecy->reveal(),
+            $propertyMetadataFactoryProphecy->reveal(),
+            $iriConverterProphecy->reveal(),
+            $resourceClassResolverProphecy->reveal(),
+            $propertyAccessorProphecy->reveal(),
+            new ReservedAttributeNameConverter(),
+            null,
+            [],
+            $resourceMetadataCollectionFactory->reveal(),
+        );
+        $normalizer->setSerializer($serializerProphecy->reveal());
+
+        $result = $normalizer->denormalize($data, Dummy::class, ItemNormalizer::FORMAT, [
+            'operation' => new Post(),
+            ItemNormalizer::ALLOW_CLIENT_GENERATED_ID => true,
+        ]);
+
+        $this->assertInstanceOf(Dummy::class, $result);
+    }
+
+    public function testDenormalizePostWithIdSucceedsWhenEnabledViaDefaultContext(): void
+    {
+        $clientId = 'b1f3e6a4-1234-4abc-9def-0123456789ab';
+        $data = [
+            'data' => [
+                'type' => 'dummy',
+                'id' => $clientId,
+                'attributes' => [
+                    'name' => 'foo',
+                ],
+            ],
+        ];
+
+        $propertyNameCollectionFactoryProphecy = $this->prophesize(PropertyNameCollectionFactoryInterface::class);
+        $propertyNameCollectionFactoryProphecy->create(Dummy::class, Argument::any())->willReturn(new PropertyNameCollection(['id', 'name']));
+
+        $propertyMetadataFactoryProphecy = $this->prophesize(PropertyMetadataFactoryInterface::class);
+        $propertyMetadataFactoryProphecy->create(Dummy::class, 'id', Argument::any())->willReturn((new ApiProperty())->withNativeType(Type::string())->withReadable(false)->withWritable(true)->withIdentifier(true));
+        $propertyMetadataFactoryProphecy->create(Dummy::class, 'name', Argument::any())->willReturn((new ApiProperty())->withNativeType(Type::string())->withReadable(false)->withWritable(true));
+
+        $iriConverterProphecy = $this->prophesize(IriConverterInterface::class);
+        $iriConverterProphecy->getResourceFromIri(Argument::cetera())->shouldNotBeCalled();
+
+        $propertyAccessorProphecy = $this->prophesize(PropertyAccessorInterface::class);
+        $propertyAccessorProphecy->setValue(Argument::type(Dummy::class), 'name', 'foo')->shouldBeCalled();
+        $propertyAccessorProphecy->setValue(Argument::type(Dummy::class), 'id', $clientId)->shouldBeCalled();
+
+        $resourceClassResolverProphecy = $this->prophesize(ResourceClassResolverInterface::class);
+        $resourceClassResolverProphecy->getResourceClass(null, Dummy::class)->willReturn(Dummy::class);
+        $resourceClassResolverProphecy->isResourceClass(Dummy::class)->willReturn(true);
+
+        $resourceMetadataCollectionFactory = $this->prophesize(ResourceMetadataCollectionFactoryInterface::class);
+        $resourceMetadataCollectionFactory->create(Dummy::class)->willReturn(new ResourceMetadataCollection(Dummy::class, [
+            (new ApiResource())->withOperations(new Operations([new Post(name: 'post')])),
+        ]));
+
+        $serializerProphecy = $this->prophesize(SerializerInterface::class);
+        $serializerProphecy->willImplement(NormalizerInterface::class);
+
+        $normalizer = new ItemNormalizer(
+            $propertyNameCollectionFactoryProphecy->reveal(),
+            $propertyMetadataFactoryProphecy->reveal(),
+            $iriConverterProphecy->reveal(),
+            $resourceClassResolverProphecy->reveal(),
+            $propertyAccessorProphecy->reveal(),
+            new ReservedAttributeNameConverter(),
+            null,
+            [ItemNormalizer::ALLOW_CLIENT_GENERATED_ID => true],
+            $resourceMetadataCollectionFactory->reveal(),
+        );
+        $normalizer->setSerializer($serializerProphecy->reveal());
+
+        $result = $normalizer->denormalize($data, Dummy::class, ItemNormalizer::FORMAT, [
+            'operation' => new Post(),
+        ]);
+
+        $this->assertInstanceOf(Dummy::class, $result);
+    }
 }
diff --git a/src/Laravel/ApiPlatformProvider.php b/src/Laravel/ApiPlatformProvider.php
@@ -969,6 +969,7 @@ public function register(): void
         $this->app->singleton(JsonApiItemNormalizer::class, static function (Application $app) {
             $config = $app['config'];
             $defaultContext = $config->get('api-platform.serializer', []);
+            $defaultContext[JsonApiItemNormalizer::ALLOW_CLIENT_GENERATED_ID] = $config->get('api-platform.jsonapi.allow_client_generated_id', false);
 
             return new JsonApiItemNormalizer(
                 $app->make(PropertyNameCollectionFactoryInterface::class),

diff --git a/src/Laravel/config/api-platform.php b/src/Laravel/config/api-platform.php
@@ -152,6 +152,12 @@
         // 'datetime_format' => \DateTimeInterface::RFC3339,
     ],
 
+    'jsonapi' => [
+        // Allow clients to provide an id on POST per https://jsonapi.org/format/#crud-creating-client-ids.
+        // Off by default to prevent ID spoofing.
+        'allow_client_generated_id' => false,
+    ],
+
     // we recommend using "file" or "acpu"
     'cache' => 'file',
 

diff --git a/src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php b/src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php
@@ -30,6 +30,7 @@
 use ApiPlatform\GraphQl\Resolver\QueryCollectionResolverInterface;
 use ApiPlatform\GraphQl\Resolver\QueryItemResolverInterface;
 use ApiPlatform\GraphQl\Type\Definition\TypeInterface as GraphQlTypeInterface;
+use ApiPlatform\JsonApi\Serializer\ItemNormalizer as JsonApiItemNormalizer;
 use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\AsOperationMutator;
 use ApiPlatform\Metadata\AsResourceMutator;
@@ -701,8 +702,11 @@ private function registerJsonApiConfiguration(ContainerBuilder $container, array
         $loader->load('jsonapi.php');
         $loader->load('state/jsonapi.php');
 
-        $container->getDefinition('api_platform.jsonapi.normalizer.item')
-            ->addArgument($config['jsonapi']['use_iri_as_id']);
+        $itemNormalizerDefinition = $container->getDefinition('api_platform.jsonapi.normalizer.item');
+        $itemNormalizerDefinition->replaceArgument(7, [
+            JsonApiItemNormalizer::ALLOW_CLIENT_GENERATED_ID => $config['jsonapi']['allow_client_generated_id'],
+        ]);
+        $itemNormalizerDefinition->addArgument($config['jsonapi']['use_iri_as_id']);
     }
 
     private function registerJsonLdHydraConfiguration(ContainerBuilder $container, array $formats, PhpFileLoader $loader, array $config): void

diff --git a/src/Symfony/Bundle/DependencyInjection/Configuration.php b/src/Symfony/Bundle/DependencyInjection/Configuration.php
@@ -108,6 +108,10 @@ public function getConfigTreeBuilder(): TreeBuilder
                             ->defaultTrue()
                             ->info('Set to false to use entity identifiers instead of IRIs as the "id" field in JSON:API responses.')
                         ->end()
+                        ->booleanNode('allow_client_generated_id')
+                            ->defaultFalse()
+                            ->info('Allow clients to provide an id on POST per https://jsonapi.org/format/#crud-creating-client-ids. Off by default to prevent ID spoofing.')
+                        ->end()
                     ->end()
                 ->end()
                 ->arrayNode('eager_loading')