Api Platform conference
Register now
v2.5 Extending JSON-LD AND Hydra Contexts
API Platform Conference
September 18-19, 2025 | Lille & online

The international conference on the API Platform Framework

Get ready for our special anniversary edition!

Lear more about the event, register for the conference, and get ready for two days of inspiration, ideas, and knowledge-sharing with our incredible lineup of renowned specialists and advocates.

This edition is shaping up to be our biggest yet — secure your seat now at the best price before we sell out!

Only a few tickets left!

Extending JSON-LD AND Hydra Contexts

Table of Contents

# JSON-LD

JSON-LD screencast
Watch the JSON-LD screencast

API Platform Core provides the possibility to extend the JSON-LD context of properties. This allows you to describe JSON-LD-typed values, inverse properties using the @reverse keyword and you can even overwrite the @id property this way. Everything you define within the following annotation will be passed to the context. This provides a generic way to extend the context.

<?php
// api/src/Entity/Book.php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiProperty;
use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(iri="http://schema.org/Book")
 */
class Book
{
    // ...

    /**
     * ...
     * @ApiProperty(
     *     iri="http://schema.org/name",
     *     attributes={
     *         "jsonld_context"={
     *             "@id"="http://yourcustomid.com",
     *             "@type"="http://www.w3.org/2001/XMLSchema#string",
     *             "someProperty"={
     *                 "a"="textA",
     *                 "b"="textB"
     *             }
     *         }
     *     }
     * )
     */
    public $name;
    
    // ...
}

The generated context will now have your custom attributes set:

GET /contexts/Book

{
  "@context": {
    "@vocab": "http://example.com/apidoc#",
    "hydra": "http://www.w3.org/ns/hydra/core#",
    "name": {
      "@id": "http://yourcustomid.com",
      "@type": "http://www.w3.org/2001/XMLSchema#string",
      "someProperty": {
        "a": "textA",
        "b": "textB"
      }
    }
  }
}

Note that you do not have to provide the @id attribute. If you do not provide an @id attribute, the value from iri will be used.

# Hydra

Hydra screencast
Watch the Hydra screencast

It’s also possible to replace the Hydra context used by the documentation generator:

```php use ApiPlatform\Core\Annotation\ApiResource;

/**

  • @ApiResource(itemOperations={
  • "get"={"hydra_context"={"foo"="bar"}}
    
  • }) */ class Book { //… }

```yaml
# api/config/api_platform/resources.yaml
App\Entity\Book:
    itemOperations:
        get:
            hydra_context: { foo: 'bar' }
<?xml version="1.0" encoding="UTF-8" ?>
<!-- api/config/api_platform/resources.xml -->

<resources xmlns="https://api-platform.com/schema/metadata"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="https://api-platform.com/schema/metadata
           https://api-platform.com/schema/metadata/metadata-2.0.xsd">
    <resource class="App\Entity\Book">
        <itemOperations>
            <itemOperation name="get">              
                <attribute name="hydra_context">
                    <attribute name="foo">bar</attribute>
                </attribute>
            </itemOperation>
        </itemOperations>
    </resource>
</resources>

You can also help us improve the documentation of this page.

Made with love by

Les-Tilleuls.coop can help you design and develop your APIs and web projects, and train your teams in API Platform, Symfony, Next.js, Kubernetes and a wide range of other technologies.

Learn more

Copyright © 2023 Kévin Dunglas

Sponsored by Les-Tilleuls.coop