Using External Vocabularies

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

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

<?php
// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(types: ['https://schema.org/Book'])]
class Book
{
    // ...

    #[ApiProperty(types: ['https://schema.org/name'])]
    public $name;
    
    // ...
}

<?php
// api/src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Metadata\ApiProperty;
use ApiPlatform\Metadata\ApiResource;

#[ApiResource(types: ['https://schema.org/Book'])]
class Book
{
    // ...

    #[ApiProperty(types: ['https://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/Book",
  "name": "My awesome book"
}

{
  "@context": "/contexts/Book",
  "@id": "/books/22",
  "@type": "https://schema.org/Book",
  "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"
  }
}

{
  "@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.

By default, when using validations API Platform will try to define known Schema.org types as IRIs for your properties if you did not provide any in your #[ApiProperty] annotations. Built-in mapping is:

Constraints	Schema.org type
Symfony\Component\Validator\Constraints\Url	https://schema.org/url
Symfony\Component\Validator\Constraints\Email	https://schema.org/email
Symfony\Component\Validator\Constraints\Uuid	https://schema.org/identifier
Symfony\Component\Validator\Constraints\CardScheme	https://schema.org/identifier
Symfony\Component\Validator\Constraints\Bic	https://schema.org/identifier
Symfony\Component\Validator\Constraints\Iban	https://schema.org/identifier
Symfony\Component\Validator\Constraints\Date	https://schema.org/Date
Symfony\Component\Validator\Constraints\DateTime	https://schema.org/DateTime
Symfony\Component\Validator\Constraints\Time	https://schema.org/Time
Symfony\Component\Validator\Constraints\Image	https://schema.org/image
Symfony\Component\Validator\Constraints\File	https://schema.org/MediaObject
Symfony\Component\Validator\Constraints\Currency	https://schema.org/priceCurrency
Symfony\Component\Validator\Constraints\Isbn	https://schema.org/isbn
Symfony\Component\Validator\Constraints\Issn	https://schema.org/issn