From 268bab7dc6c0639c6c59c1b3310b1f8a6cd7b94c Mon Sep 17 00:00:00 2001 From: soyuka Date: Wed, 23 Sep 2026 14:43:49 +0200 Subject: [PATCH] docs: clarify property iris versus types The example on this page used `ApiProperty(types:)` on a property and then showed a JSON-LD `@context` that only `iris` produces. Property `types` reaches no RDF output at all: its only consumer is the `externalDocs.url` field of the generated OpenAPI schema. Fixes the example and adds a section stating which attribute drives which output. Closes api-platform/core#7051 --- core/external-vocabularies.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/core/external-vocabularies.md b/core/external-vocabularies.md index 5590013c312..f98aac7f619 100644 --- a/core/external-vocabularies.md +++ b/core/external-vocabularies.md @@ -20,7 +20,7 @@ class Book { // ... - #[ApiProperty(types: ['https://schema.org/name'])] + #[ApiProperty(iris: ['https://schema.org/name'])] public $name; // ... @@ -53,6 +53,30 @@ according to the specified attributes: } ``` +## Resource `types`, Property `iris`, and Property `types` + +These three attributes each control a different output, and mixing them up is a common mistake: + +- `types` on `#[ApiResource]` sets the RDF class of the resource. It replaces the JSON-LD `@type` + and sets the `subClassOf` value in the Hydra documentation. +- `iris` on `#[ApiProperty]` sets the RDF property IRI. It is used in the JSON-LD `@context` (as + shown above) and in the Hydra documentation. Without it, API Platform builds a local term from + the property name instead. +- `types` on `#[ApiProperty]` produces no RDF output at all. Its only effect is to populate the + `externalDocs.url` field of that property in the generated OpenAPI schema. + +To map both the class and a property to Schema.org, use `types` on the resource and `iris` on the +property: + +```php +#[ApiResource(types: ['https://schema.org/Store'])] +class Store +{ + #[ApiProperty(iris: ['https://schema.org/name'])] + public string $name; +} +``` + An extended list of existing open vocabularies is available on [the Linked Open Vocabularies (LOV) database](https://lov.linkeddata.es/dataset/lov/).