Using External JSON-LD Vocabularies

JSON-LD allows to define classes and properties of your API with open vocabularies such as Schema.org and Good Relations.

API Platform Core provides annotations usable on PHP classes and properties for specifying a related external IRI.

<?php

// src/AppBundle/Entity/Book.php

namespace AppBundle\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")
     */
    public $name;
}

The generated JSON for products and the related context document will now use external IRIs according to the specified annotations:

GET /books/22

{
  "@context": "/contexts/Book",
  "@id": "/books/22",
  "@type": "https://schema.org/Product",
  "name": "My awesome book"
}

GET /contexts/Book

{
  "@context": {
    "@vocab": "http://example.com/apidoc#",
    "hydra": "http://www.w3.org/ns/hydra/core#",
    "name": "https://schema.org/name"
  }
}

An extended list of existing open vocabularies is available on the Linked Open Vocabularies (LOV) database.

Previous chapter: Content Negotiation

Next chapter: Extending JSON-LD context