Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[Json-Schema] Nested resources lost externalDoc and description data

Open
  • Is something wrong?
#8,721 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@abp002 is already working on this.

Since Oct 16, 2026.

  • #8723 by @abp002 — open

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
68/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
php
Domain
api, backend-api-design

Research direction

Start by reading the change in src/Hydra/JsonSchema/SchemaFactory.ph introduced by #8652, which the report identifies as the source of the regression. Reproduce the example with nested SchemaThing resources and compare the generated JSON OpenAPI output before and after the change. Done means the nested resource retains its documentation and externalDocs data.

Written by the indexing model from the issue text.

Description

API Platform version(s) affected: 5.0.4

Description
We have some shared api schemas that are linked to schema.org specs, and the generated jsonopenapi spec file contained this information. But after updating to the latest version, we lost these details.

Both the documentation and externalDocs fields are now empty.

screenshots Before: Image

After:
Image

How to reproduce

#[Get(provider: EntityStateProvider::class, processor: EntityStateProcessor::class)]
class Entity
{
    public function __construct(
        #[ApiProperty(identifier: true)]
        public int         $id,
        #[ApiProperty(readableLink: true)]
        public SchemaThing $thing
    )
    {
    }
}

#[ApiResource(description: "A schema type", types: ['https://schema.org/Thing'], operations: [])]
class SchemaThing
{
    #[ApiProperty(description: "The name of the item.", iris: ['https://schema.org/name'])]
    public string $name;
    #[ApiProperty(description: "An alias for the item.", iris: ['https://schema.org/alternateName'])]
    public string $alternateName;
}

Additional Context
If I revert the change in ‎src/Hydra/JsonSchema/SchemaFactory.ph by #8652 the issue is fixed

Dominant language
PHP
Stars
2.6k
Forks
989
Avg merge
1d 23h
Merged PRs (30d)
102

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from api-platform/core

All issues in api-platform/core

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.