v3.0 Using External Vocabularies

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;
    
    // ...
}

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"
}

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.

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:

ConstraintsSchema.org type
Symfony\Component\Validator\Constraints\Urlhttps://schema.org/url
Symfony\Component\Validator\Constraints\Emailhttps://schema.org/email
Symfony\Component\Validator\Constraints\Uuidhttps://schema.org/identifier
Symfony\Component\Validator\Constraints\CardSchemehttps://schema.org/identifier
Symfony\Component\Validator\Constraints\Bichttps://schema.org/identifier
Symfony\Component\Validator\Constraints\Ibanhttps://schema.org/identifier
Symfony\Component\Validator\Constraints\Datehttps://schema.org/Date
Symfony\Component\Validator\Constraints\DateTimehttps://schema.org/DateTime
Symfony\Component\Validator\Constraints\Timehttps://schema.org/Time
Symfony\Component\Validator\Constraints\Imagehttps://schema.org/image
Symfony\Component\Validator\Constraints\Filehttps://schema.org/MediaObject
Symfony\Component\Validator\Constraints\Currencyhttps://schema.org/priceCurrency
Symfony\Component\Validator\Constraints\Isbnhttps://schema.org/isbn
Symfony\Component\Validator\Constraints\Issnhttps://schema.org/issn

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