Context

#[NotExposed] is currently documented only in jsonapi.md (for JSON:API relations) and briefly mentioned in openapi.md. It is missing from the two pages most users land on when designing DTOs:

• core/design.md
• core/dto.md

Problem

API Platform's metadata pipeline (Hydra docs, OpenAPI, JSON Schema, property security, etc.) walks #[ApiResource] classes only. Nested POPOs referenced via property typehints are invisible to the doc generators. Users hit this repeatedly (e.g. api-platform/core#8187, api-platform/core#8087) and the typical answer — "mark the nested DTO with #[NotExposed]" — is not discoverable from the DTO docs.

Suggested addition

Short subsection in dto.md (and a mention in design.md) covering:

• Nested DTOs referenced from an output DTO are not introspected for docs unless they are themselves resources
• Use #[NotExposed] on a nested DTO to register its metadata (Hydra/OpenAPI/property factories) without exposing public endpoints
• Brief example:

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\NotExposed;

#[ApiResource(operations: [new Get(/* ... */)])]
class Response
{
    /** @var Nested[] */
    public array $data = [];
}

#[NotExposed]
class Nested
{
    public function __construct(public int $id) {}
}

• Cross-link to the existing NotExposed reference in jsonapi.md