fix(jsonschema/jsonld): make @id and @type properties required only in the JSON-LD schema for output
#7397
+100
−93
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ttskch
force-pushed
the
fix/jsonschema-jsonld
branch
from
6ea2a72 to
ff5e438
Compare
ttskch
changed the title
|
Interesting, but its possible when using JSON-LD to have |
I see. If so, when using JSON-LD, Would it be ok to modify this PR like that? |
ttskch
force-pushed
the
fix/jsonschema-jsonld
branch
from
834d183 to
638ad92
Compare
|
like this. (Just a PoC, don't merge yet.) |
Example of output result
openapi.json{
"components": {
"schemas": {
"Book": {
"type": "object",
"properties": {
"id": {
"readOnly": true,
"type": "integer"
},
"title": {
"type": "string"
}
},
"required": [
"title"
]
},
"Book.jsonld.input": {
"allOf": [
{
"$ref": "#/components/schemas/HydraItemBaseSchema"
},
{
"$ref": "#/components/schemas/Book"
}
]
},
"Book.jsonld.output": {
"allOf": [
{
"$ref": "#/components/schemas/HydraOutputBaseSchema"
},
{
"$ref": "#/components/schemas/Book"
}
]
},
"HydraItemBaseSchema": {
"type": "object",
"properties": {
"@context": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"@vocab": {
"type": "string"
},
"hydra": {
"type": "string",
"enum": [
"http://www.w3.org/ns/hydra/core#"
]
}
},
"required": [
"@vocab",
"hydra"
],
"additionalProperties": true
}
]
},
"@id": {
"type": "string"
},
"@type": {
"type": "string"
}
}
},
"HydraOutputBaseSchema": {
"required": [
"@id",
"@type"
],
"type": "object",
"properties": {
"@context": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"@vocab": {
"type": "string"
},
"hydra": {
"type": "string",
"enum": [
"http://www.w3.org/ns/hydra/core#"
]
}
},
"required": [
"@vocab",
"hydra"
],
"additionalProperties": true
}
]
},
"@id": {
"type": "string"
},
"@type": {
"type": "string"
}
}
}
}
}
}Reproducer |
|
Nice this looks fine! Can the |
ttskch
changed the title
@id and @type properties required only in the JSON-LD schema for output
|
@soyuka I fixed in 479f46b and updated the PR title and description. Example of output result
openapi.json{
"openapi": "3.1.0",
"info": {
"title": "Hello API Platform",
"description": "",
"version": "1.0.0"
},
"servers": [
{
"url": "/",
"description": ""
}
],
"paths": {
"/api/books": {
"get": {
"operationId": "api_books_get_collection",
"tags": [
"Book"
],
"responses": {
"200": {
"description": "Book collection",
"content": {
"application/ld+json": {
"schema": {
"type": "object",
"description": "Book.jsonld collection.",
"allOf": [
{
"$ref": "#/components/schemas/HydraCollectionBaseSchema"
},
{
"type": "object",
"properties": {
"hydra:member": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Book.jsonld"
}
}
}
}
]
}
}
}
}
},
"summary": "Retrieves the collection of Book resources.",
"description": "Retrieves the collection of Book resources.",
"parameters": [
{
"name": "page",
"in": "query",
"description": "The collection page number",
"required": false,
"deprecated": false,
"schema": {
"type": "integer",
"default": 1
},
"style": "form",
"explode": false
}
]
},
"post": {
"operationId": "api_books_post",
"tags": [
"Book"
],
"responses": {
"201": {
"description": "Book resource created",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/Book.jsonld"
}
}
},
"links": {}
},
"400": {
"description": "Invalid input",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/Error.jsonld"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"links": {}
},
"422": {
"description": "An error occurred",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/ConstraintViolation.jsonld"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ConstraintViolation"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConstraintViolation"
}
}
},
"links": {}
}
},
"summary": "Creates a Book resource.",
"description": "Creates a Book resource.",
"parameters": [],
"requestBody": {
"description": "The new Book resource",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/Book.jsonld.input"
}
}
},
"required": true
}
}
},
"/api/books/{id}": {
"get": {
"operationId": "api_books_id_get",
"tags": [
"Book"
],
"responses": {
"200": {
"description": "Book resource",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/Book.jsonld"
}
}
}
},
"404": {
"description": "Not found",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/Error.jsonld"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"links": {}
}
},
"summary": "Retrieves a Book resource.",
"description": "Retrieves a Book resource.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Book identifier",
"required": true,
"deprecated": false,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
]
},
"delete": {
"operationId": "api_books_id_delete",
"tags": [
"Book"
],
"responses": {
"204": {
"description": "Book resource deleted"
},
"404": {
"description": "Not found",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/Error.jsonld"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"links": {}
}
},
"summary": "Removes the Book resource.",
"description": "Removes the Book resource.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Book identifier",
"required": true,
"deprecated": false,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
]
},
"patch": {
"operationId": "api_books_id_patch",
"tags": [
"Book"
],
"responses": {
"200": {
"description": "Book resource updated",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/Book.jsonld"
}
}
},
"links": {}
},
"400": {
"description": "Invalid input",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/Error.jsonld"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"links": {}
},
"422": {
"description": "An error occurred",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/ConstraintViolation.jsonld"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/ConstraintViolation"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConstraintViolation"
}
}
},
"links": {}
},
"404": {
"description": "Not found",
"content": {
"application/ld+json": {
"schema": {
"$ref": "#/components/schemas/Error.jsonld"
}
},
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"links": {}
}
},
"summary": "Updates the Book resource.",
"description": "Updates the Book resource.",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Book identifier",
"required": true,
"deprecated": false,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
],
"requestBody": {
"description": "The updated Book resource",
"content": {
"application/merge-patch+json": {
"schema": {
"$ref": "#/components/schemas/Book"
}
}
},
"required": true
}
}
}
},
"components": {
"schemas": {
"Book": {
"type": "object",
"properties": {
"id": {
"readOnly": true,
"type": "integer"
},
"title": {
"type": "string"
}
},
"required": [
"title"
]
},
"Book.jsonld": {
"allOf": [
{
"$ref": "#/components/schemas/HydraOutputBaseSchema"
},
{
"$ref": "#/components/schemas/Book"
}
]
},
"Book.jsonld.input": {
"allOf": [
{
"$ref": "#/components/schemas/HydraItemBaseSchema"
},
{
"$ref": "#/components/schemas/Book"
}
]
},
"ConstraintViolation": {
"type": "object",
"description": "Unprocessable entity",
"properties": {
"status": {
"default": 422,
"type": "integer"
},
"violations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"propertyPath": {
"type": "string",
"description": "The property path of the violation"
},
"message": {
"type": "string",
"description": "The message associated with the violation"
}
}
}
},
"detail": {
"readOnly": true,
"type": "string"
},
"type": {
"readOnly": true,
"type": "string"
},
"title": {
"readOnly": true,
"type": [
"string",
"null"
]
},
"instance": {
"readOnly": true,
"type": [
"string",
"null"
]
}
}
},
"ConstraintViolation.jsonld": {
"allOf": [
{
"$ref": "#/components/schemas/HydraOutputBaseSchema"
},
{
"$ref": "#/components/schemas/ConstraintViolation"
}
]
},
"Error": {
"type": "object",
"description": "A representation of common errors.",
"properties": {
"title": {
"readOnly": true,
"description": "A short, human-readable summary of the problem.",
"type": "string"
},
"detail": {
"readOnly": true,
"description": "A human-readable explanation specific to this occurrence of the problem.",
"type": "string"
},
"status": {
"type": "number",
"examples": [
404
],
"default": 400
},
"instance": {
"readOnly": true,
"description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.",
"type": [
"string",
"null"
]
},
"type": {
"readOnly": true,
"description": "A URI reference that identifies the problem type",
"type": "string"
}
}
},
"Error.jsonld": {
"allOf": [
{
"$ref": "#/components/schemas/HydraOutputBaseSchema"
},
{
"$ref": "#/components/schemas/Error"
}
]
},
"HydraCollectionBaseSchema": {
"type": "object",
"required": [
"hydra:member"
],
"properties": {
"hydra:member": {
"type": "array"
},
"hydra:totalItems": {
"type": "integer",
"minimum": 0
},
"hydra:view": {
"type": "object",
"properties": {
"@id": {
"type": "string",
"format": "iri-reference"
},
"@type": {
"type": "string"
},
"hydra:first": {
"type": "string",
"format": "iri-reference"
},
"hydra:last": {
"type": "string",
"format": "iri-reference"
},
"hydra:previous": {
"type": "string",
"format": "iri-reference"
},
"hydra:next": {
"type": "string",
"format": "iri-reference"
}
},
"example": {
"@id": "string",
"type": "string",
"hydra:first": "string",
"hydra:last": "string",
"hydra:previous": "string",
"hydra:next": "string"
}
},
"hydra:search": {
"type": "object",
"properties": {
"@type": {
"type": "string"
},
"hydra:template": {
"type": "string"
},
"hydra:variableRepresentation": {
"type": "string"
},
"hydra:mapping": {
"type": "array",
"items": {
"type": "object",
"properties": {
"@type": {
"type": "string"
},
"variable": {
"type": "string"
},
"property": {
"type": [
"string",
"null"
]
},
"required": {
"type": "boolean"
}
}
}
}
}
}
}
},
"HydraItemBaseSchema": {
"type": "object",
"properties": {
"@context": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"@vocab": {
"type": "string"
},
"hydra": {
"type": "string",
"enum": [
"http://www.w3.org/ns/hydra/core#"
]
}
},
"required": [
"@vocab",
"hydra"
],
"additionalProperties": true
}
]
},
"@id": {
"type": "string"
},
"@type": {
"type": "string"
}
}
},
"HydraOutputBaseSchema": {
"required": [
"@id",
"@type"
],
"type": "object",
"properties": {
"@context": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"@vocab": {
"type": "string"
},
"hydra": {
"type": "string",
"enum": [
"http://www.w3.org/ns/hydra/core#"
]
}
},
"required": [
"@vocab",
"hydra"
],
"additionalProperties": true
}
]
},
"@id": {
"type": "string"
},
"@type": {
"type": "string"
}
}
}
},
"responses": {},
"parameters": {},
"examples": {},
"requestBodies": {},
"headers": {},
"securitySchemes": {}
},
"security": [],
"tags": [
{
"name": "Book",
"description": "Resource 'Book' operations."
}
],
"webhooks": {}
}Reproducer |
|
I'm still working to fix the CI error. |
ttskch
force-pushed
the
fix/jsonschema-jsonld
branch
2 times, most recently
from
1cda6cf to
5fdaa77
Compare
|
I can take a look if you want, and I may move this test to phpunit I thought that keeping |
soyuka
force-pushed
the
fix/jsonschema-jsonld
branch
from
cb98a29 to
b0cac3a
Compare
soyuka
reviewed
Sep 29, 2025
| $definitionName .= '.input'; | ||
| } | ||
|
|
||
| $jsonSchema = $this->schemaFactory->buildSchema($className, 'json', $type, $operation, new Schema(version: $schema->getVersion()), $serializerContext, $forceCollection); |
There was a problem hiding this comment.
this doesn't work as references will be with json instead of jsonld
There was a problem hiding this comment.
@soyuka What do you mean?🤔 I understand that the intention of your fix in #6960 was to reference a json schema in the definition of a jsonld schema. I completely agree with that intention, but unfortunately #6960 had the following bugs:
- The output schema was applied even on input, making
@idand@typerequired. - The json schema was not referenced (only
HydraItemBaseSchemaandHydraCollectionBaseSchemawere referenced).
This PR fixes these two bugs.
In order to reference or embed a json schema (e.g., Book instead of Book.jsonld), I believe you need to explicitly create a json schema here.
soyuka
force-pushed
the
fix/jsonschema-jsonld
branch
from
b0cac3a to
5fdaa77
Compare
soyuka
reviewed
Sep 29, 2025
| public function buildSchema(string $className, string $format = 'jsonld', string $type = Schema::TYPE_OUTPUT, ?Operation $operation = null, ?Schema $schema = null, ?array $serializerContext = null, bool $forceCollection = false): Schema | ||
| { | ||
| if ('jsonld' !== $format || 'input' === $type) { | ||
| if ('jsonld' !== $format) { |
There was a problem hiding this comment.
I'm quite unsure about this as when its an input we were going through this path making @id required only on output
There was a problem hiding this comment.
@soyuka If we add 'input' === $type here, this method will not be executed at all during input, and Book.jsonld.input will not be generated.
The @id @type @context properties will be added during both input and output, and @id @type should only be required during output. This control is done here and here.
ttskch
force-pushed
the
fix/jsonschema-jsonld
branch
from
53e1e96 to
fa1305f
Compare
…ferencing it It cannot always be referenced, as there may be resources that don't have a JSON schema but only a JSON-LD schema. It's not certain at the time the JSON-LD schema is being generated whether a JSON schema will ultimately be defined. Therefore, the JSON schema will be referenced only if it's already defined.
ttskch
force-pushed
the
fix/jsonschema-jsonld
branch
from
fa1305f to
ad9be8a
Compare
|
rebased with current 4.2 |
ttskch
force-pushed
the
fix/jsonschema-jsonld
branch
from
e92aeff to
d1e60d9
Compare
|
@soyuka I've mostly revised the existing tests to match the implementation. The only thing I'm unsure of is how to properly modify The new schema uses |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR makes
@idand@typeproperties required only in the JSON-LD schema for output.