Using External Vocabularies

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

JSON-LD を使用すると、Schema.organ や Good Relations などのオープン ボキャブラリを使用して、API のクラスとプロパティを定義できます。

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

API プラットフォームは、関連する外部 IRI を指定するために、PHP クラスとプロパティで使用できる注釈を提供します。

<?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:

製品用に生成された JSON および関連するコンテキスト ドキュメントは、指定された注釈に従って外部 IRI を使用するようになりました。

GET /books/22

GET /本/22

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

GET /contexts/Book

GET /コンテキスト/本

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

Linked Open Vocabularies (LOV) データベースでは、既存のオープン語彙の拡張リストを利用できます。

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:

デフォルトでは、#[ApiProperty] アノテーションで何も指定しなかった場合、API プラットフォームは検証を使用するときに既知の Schema.org タイプをプロパティの IRI として定義しようとします。組み込みのマッピングは次のとおりです。

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