feat(jsonld): add resource-level jsonldContext for namespace prefixes (#8204)

soyuka · web-flow · commit 5ddf94aeb9b5 · 2026-05-28T16:49:17.000+02:00
diff --git a/src/JsonLd/ContextBuilder.php b/src/JsonLd/ContextBuilder.php
@@ -180,6 +180,11 @@ private function generateContextUri(?string $shortName, ?int $referenceType): st
     private function getResourceContextWithShortname(string $resourceClass, int $referenceType, string $shortName, ?HttpOperation $operation = null): array
     {
         $context = $this->getBaseContext($referenceType);
+
+        if ($operation && $jsonldContext = $operation->getJsonldContext()) {
+            $context = array_merge($context, $jsonldContext);
+        }
+
         $propertyContext = $operation ? ['normalization_groups' => $operation->getNormalizationContext()['groups'] ?? null, 'denormalization_groups' => $operation->getDenormalizationContext()['groups'] ?? null] : ['normalization_groups' => [], 'denormalization_groups' => []];
 
         foreach ($this->propertyNameCollectionFactory->create($resourceClass) as $propertyName) {
diff --git a/src/Metadata/ApiResource.php b/src/Metadata/ApiResource.php
@@ -326,6 +326,14 @@ public function __construct(
         protected ?array $denormalizationContext = null,
         protected ?bool $collectDenormalizationErrors = null,
         protected ?array $hydraContext = null,
+        /**
+         * Extra entries to merge into the JSON-LD `@context` for this resource (e.g. namespace prefix declarations).
+         *
+         * Example: `jsonldContext: ['dct' => 'http://purl.org/dc/terms/']`
+         *
+         * @see https://api-platform.com/docs/core/extending-jsonld-context/
+         */
+        protected ?array $jsonldContext = null,
         protected bool|OpenApiOperation|null $openapi = null,
         /**
          * The `validationContext` option configures the context of validation for the current ApiResource.
@@ -1373,6 +1381,19 @@ public function withHydraContext(array $hydraContext): static
         return $self;
     }
 
+    public function getJsonldContext(): ?array
+    {
+        return $this->jsonldContext;
+    }
+
+    public function withJsonldContext(array $jsonldContext): static
+    {
+        $self = clone $this;
+        $self->jsonldContext = $jsonldContext;
+
+        return $self;
+    }
+
     public function getOpenapi(): bool|OpenApiOperation|null
     {
         return $this->openapi;
diff --git a/src/Metadata/Delete.php b/src/Metadata/Delete.php
@@ -44,6 +44,7 @@ public function __construct(
         ?array $cacheHeaders = null,
         ?array $paginationViaCursor = null,
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         bool|OpenApiOperation|Webhook|null $openapi = null,
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
@@ -129,6 +130,7 @@ public function __construct(
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
diff --git a/src/Metadata/Error.php b/src/Metadata/Error.php
@@ -44,6 +44,7 @@ public function __construct(
         ?array $cacheHeaders = null,
         ?array $paginationViaCursor = null,
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         bool|OpenApiOperation|Webhook|null $openapi = null,
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
@@ -123,6 +124,7 @@ public function __construct(
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
diff --git a/src/Metadata/ErrorResource.php b/src/Metadata/ErrorResource.php
@@ -49,6 +49,7 @@ public function __construct(
         ?array $denormalizationContext = null,
         ?bool $collectDenormalizationErrors = null,
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         OpenApiOperation|bool|null $openapi = null,
         ?array $validationContext = null,
         ?array $filters = null,
@@ -116,6 +117,7 @@ class: $class,
             denormalizationContext: $denormalizationContext,
             collectDenormalizationErrors: $collectDenormalizationErrors,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             validationContext: $validationContext,
             filters: $filters,
diff --git a/src/Metadata/Extractor/XmlResourceExtractor.php b/src/Metadata/Extractor/XmlResourceExtractor.php
@@ -93,6 +93,7 @@ private function buildExtendedBase(\SimpleXMLElement $resource): array
             'schemes' => $this->buildArrayValue($resource, 'scheme'),
             'cacheHeaders' => $this->buildCacheHeaders($resource),
             'hydraContext' => isset($resource->hydraContext->values) ? $this->buildValues($resource->hydraContext->values) : null,
+            'jsonldContext' => isset($resource->jsonldContext->values) ? $this->buildValues($resource->jsonldContext->values) : null,
             'openapi' => $this->buildOpenapi($resource),
             'paginationViaCursor' => $this->buildPaginationViaCursor($resource),
             'exceptionToStatus' => $this->buildExceptionToStatus($resource),
diff --git a/src/Metadata/Extractor/YamlResourceExtractor.php b/src/Metadata/Extractor/YamlResourceExtractor.php
@@ -114,6 +114,7 @@ private function buildExtendedBase(array $resource): array
             'types' => $this->buildArrayValue($resource, 'types'),
             'cacheHeaders' => $this->buildArrayValue($resource, 'cacheHeaders'),
             'hydraContext' => $this->buildArrayValue($resource, 'hydraContext'),
+            'jsonldContext' => $this->buildArrayValue($resource, 'jsonldContext'),
             'openapi' => $this->buildOpenapi($resource),
             'paginationViaCursor' => $this->buildArrayValue($resource, 'paginationViaCursor'),
             'exceptionToStatus' => $this->buildArrayValue($resource, 'exceptionToStatus'),
diff --git a/src/Metadata/Extractor/schema/resources.xsd b/src/Metadata/Extractor/schema/resources.xsd
@@ -479,6 +479,7 @@
             <xsd:element name="defaults" minOccurs="0" type="sequenceWithValues"/>
             <xsd:element name="formats" minOccurs="0" type="formats"/>
             <xsd:element name="hydraContext" minOccurs="0" type="sequenceWithValues"/>
+            <xsd:element name="jsonldContext" minOccurs="0" type="sequenceWithValues"/>
             <xsd:element name="inputFormats" minOccurs="0" type="formats"/>
             <xsd:element name="openapi" minOccurs="0" type="openApiOperation"/>
             <xsd:element name="parameters" minOccurs="0" type="parameters"/>
diff --git a/src/Metadata/Get.php b/src/Metadata/Get.php
@@ -44,6 +44,7 @@ public function __construct(
         ?array $cacheHeaders = null,
         ?array $paginationViaCursor = null,
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         bool|OpenApiOperation|Webhook|null $openapi = null,
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
@@ -128,6 +129,7 @@ public function __construct(
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
diff --git a/src/Metadata/GetCollection.php b/src/Metadata/GetCollection.php
@@ -44,6 +44,7 @@ public function __construct(
         ?array $cacheHeaders = null,
         ?array $paginationViaCursor = null,
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         bool|OpenApiOperation|Webhook|null $openapi = null,
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
@@ -129,6 +130,7 @@ public function __construct(
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
diff --git a/src/Metadata/HttpOperation.php b/src/Metadata/HttpOperation.php
@@ -164,6 +164,7 @@ public function __construct(
         protected ?array $cacheHeaders = null,
         protected ?array $paginationViaCursor = null,
         protected ?array $hydraContext = null,
+        protected ?array $jsonldContext = null,
         protected bool|OpenApiOperation|Webhook|null $openapi = null,
         protected ?array $exceptionToStatus = null,
         protected ?array $links = null,
@@ -629,6 +630,19 @@ public function withHydraContext(array $hydraContext): static
         return $self;
     }
 
+    public function getJsonldContext(): ?array
+    {
+        return $this->jsonldContext;
+    }
+
+    public function withJsonldContext(array $jsonldContext): static
+    {
+        $self = clone $this;
+        $self->jsonldContext = $jsonldContext;
+
+        return $self;
+    }
+
     public function getOpenapi(): bool|OpenApiOperation|Webhook|null
     {
         return $this->openapi;
diff --git a/src/Metadata/McpResource.php b/src/Metadata/McpResource.php
@@ -126,6 +126,7 @@ public function __construct(
         ?array $cacheHeaders = null,
         ?array $paginationViaCursor = null,
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         bool|OpenApiOperation|Webhook|null $openapi = null,
         ?array $exceptionToStatus = null,
         ?array $links = null,
@@ -209,6 +210,7 @@ public function __construct(
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             exceptionToStatus: $exceptionToStatus,
             links: $links,
diff --git a/src/Metadata/McpTool.php b/src/Metadata/McpTool.php
@@ -122,6 +122,7 @@ public function __construct(
         ?array $cacheHeaders = null,
         ?array $paginationViaCursor = null,
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         bool|OpenApiOperation|Webhook|null $openapi = null,
         ?array $exceptionToStatus = null,
         ?array $links = null,
@@ -205,6 +206,7 @@ public function __construct(
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             exceptionToStatus: $exceptionToStatus,
             links: $links,
diff --git a/src/Metadata/NotExposed.php b/src/Metadata/NotExposed.php
@@ -56,6 +56,7 @@ public function __construct(
         ?array $paginationViaCursor = null,
 
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         bool|OpenApiOperation|Webhook|null $openapi = false,
         ?array $exceptionToStatus = null,
 
@@ -135,6 +136,7 @@ public function __construct(
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
diff --git a/src/Metadata/Patch.php b/src/Metadata/Patch.php
@@ -44,6 +44,7 @@ public function __construct(
         ?array $cacheHeaders = null,
         ?array $paginationViaCursor = null,
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         bool|OpenApiOperation|Webhook|null $openapi = null,
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
@@ -129,6 +130,7 @@ public function __construct(
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
diff --git a/src/Metadata/Post.php b/src/Metadata/Post.php
@@ -44,6 +44,7 @@ public function __construct(
         ?array $cacheHeaders = null,
         ?array $paginationViaCursor = null,
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         bool|OpenApiOperation|Webhook|null $openapi = null,
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
@@ -130,6 +131,7 @@ public function __construct(
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
diff --git a/src/Metadata/Put.php b/src/Metadata/Put.php
@@ -44,6 +44,7 @@ public function __construct(
         ?array $cacheHeaders = null,
         ?array $paginationViaCursor = null,
         ?array $hydraContext = null,
+        ?array $jsonldContext = null,
         bool|OpenApiOperation|Webhook|null $openapi = null,
         ?array $exceptionToStatus = null,
         ?bool $queryParameterValidationEnabled = null,
@@ -130,6 +131,7 @@ public function __construct(
             cacheHeaders: $cacheHeaders,
             paginationViaCursor: $paginationViaCursor,
             hydraContext: $hydraContext,
+            jsonldContext: $jsonldContext,
             openapi: $openapi,
             exceptionToStatus: $exceptionToStatus,
             queryParameterValidationEnabled: $queryParameterValidationEnabled,
diff --git a/src/Metadata/Tests/Extractor/Adapter/XmlResourceAdapter.php b/src/Metadata/Tests/Extractor/Adapter/XmlResourceAdapter.php
@@ -230,6 +230,11 @@ private function buildHydraContext(\SimpleXMLElement $resource, array $values):
         $this->buildValues($resource->addChild('hydraContext'), $values);
     }
 
+    private function buildJsonldContext(\SimpleXMLElement $resource, array $values): void
+    {
+        $this->buildValues($resource->addChild('jsonldContext'), $values);
+    }
+
     private function buildOpenapi(\SimpleXMLElement $resource, array $values): void
     {
         $node = $resource->openapi ?? $resource->addChild('openapi');
diff --git a/src/Metadata/Tests/Extractor/Adapter/resources.xml b/src/Metadata/Tests/Extractor/Adapter/resources.xml
diff --git a/src/Metadata/Tests/Extractor/Adapter/resources.yaml b/src/Metadata/Tests/Extractor/Adapter/resources.yaml
diff --git a/src/Metadata/Tests/Extractor/ResourceMetadataCompatibilityTest.php b/src/Metadata/Tests/Extractor/ResourceMetadataCompatibilityTest.php
diff --git a/src/Metadata/Tests/Extractor/XmlExtractorTest.php b/src/Metadata/Tests/Extractor/XmlExtractorTest.php
diff --git a/src/Metadata/Tests/Extractor/YamlExtractorTest.php b/src/Metadata/Tests/Extractor/YamlExtractorTest.php
diff --git a/tests/Fixtures/TestBundle/ApiResource/JsonLd/JsonLdContextDummy.php b/tests/Fixtures/TestBundle/ApiResource/JsonLd/JsonLdContextDummy.php
diff --git a/tests/Functional/JsonLd/ContextTest.php b/tests/Functional/JsonLd/ContextTest.php
