A `$ref` in `requestBody` is silently dropped, so the request body is never validated

[shadowhand]

A requestBody that is a Reference Object is silently discarded during parsing, and the request body is then not validated at all. This fails open: malformed bodies are accepted and required: true is not enforced. No exception, no warning.

Parameter and Response both support $ref; RequestBody is the one Reference-Object-capable member of the Operation Object that does not.

Reproduce

<?php
use Duyler\OpenApi\Builder\OpenApiValidatorBuilder;
use Nyholm\Psr7\Factory\Psr17Factory;

$spec = <<<'YAML'
openapi: 3.1.0
info:
  title: Ref RequestBody API
  version: 1.0.0
paths:
  /data:
    post:
      requestBody:
        $ref: '#/components/requestBodies/UserBody'
      responses:
        '201':
          description: Created
components:
  requestBodies:
    UserBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [name]
            properties:
              name:
                type: string
YAML;

$validator = OpenApiValidatorBuilder::create()->fromYamlString($spec)->build();
$factory = new Psr17Factory();

// `name` must be a string, and the body is required.
$request = $factory->createServerRequest('POST', '/data')
    ->withHeader('Content-Type', 'application/json')
    ->withBody($factory->createStream('{"name": 12345}'));

$validator->validateRequest($request); // passes — expected a validation error

Expected

A validation error for name (integer where a string is required), and a MissingRequestBodyException for an empty body.

Actual

Both requests pass. Inlining the same requestBody instead of referencing it produces the expected errors, so the schema itself is fine — the reference is the problem.

$document->paths->paths['/data']->post->requestBody is:

object(Duyler\OpenApi\Schema\Model\RequestBody)#24 (3) {
  ["description"] => NULL
  ["content"]     => NULL
  ["required"]    => bool(false)
}

The $ref is gone, and with it the content and required: true it pointed at.

Root cause

Reference Object support for requestBody is absent at every layer of the pipeline, where Parameter and Response have it:

1. Model — Schema\Model\RequestBody has no ref field. Schema\Model\Response and Schema\Model\Parameter both carry ref / refSummary / refDescription.

2. Parser — Schema\Parser\Internal\ComponentTreeBuilder::buildRequestBody() never inspects $ref:

   public function buildRequestBody(array $data): RequestBody
   {
       return new RequestBody(
           description: TypeHelper::asStringOrNull($data['description'] ?? null),
           content: $this->nullable($data, 'content', $this->buildContent(...)),
           required: (bool) ($data['required'] ?? false),
       );
   }

   Compare ResponseTreeBuilder::buildResponse() and PathItemBuilder::buildParameter(), which both open with an isset($data['$ref']) branch. Because $ref matches none of the three keys read above, a Reference Object parses to an empty RequestBody — a silent drop rather than an error.

3. Navigator — Validator\Schema\Internal\DocumentNavigator::navigate() returns Schema|Parameter|Response and rejects anything else with Target is not a Schema, Parameter, or Response. A #/components/requestBodies/* pointer cannot be resolved even though Components::$requestBodies is parsed and populated:

   $navigator->navigate($document, ['components', 'requestBodies', 'UserBody']);
   // UnresolvableRefException: Target is not a Schema, Parameter, or Response

   RefCache::$map is typed to the same three-class union.

4. Resolver — Validator\Schema\RefResolverInterface declares resolveParameter() / resolveResponse() and resolveParameterWithOverride() / resolveResponseWithOverride(). There is no RequestBody counterpart.

5. Validator — Validator\Request\RequestBodyValidatorWithContext::validate() dereferences the media type's schema ($content->schema->ref) but never the request body object itself.

Layer 2 is what makes this fail open rather than throw. The empty RequestBody reaches validate(), which returns at its null === $requestBody->content early exit:

if (null === $requestBody->content) {
    if ($requestBody->required) {   // false — the ref's `required: true` was dropped
        throw new MissingRequestBodyException();
    }

    return;                          // body never validated
}

So the fix needs all five layers: without 2 the pointer never reaches the validator, and without 3 and 4 the validator has no way to resolve it.

Notes

• Affects #/components/requestBodies/* and external/file $ref targets alike, and applies to webhooks and callbacks, which build operations through the same PathItemBuilder::buildOperation().
• OAS 3.1+ allows summary and description as siblings of $ref in a Reference Object. Response and Parameter model these as refSummary / refDescription and let them override the resolved values; RequestBody should behave the same way for consistency.
• Related: Response validation with referenced items seems not to work correctly #18 fixed the same class of problem for response validation with referenced content. This is the request-side counterpart.

Environment

• duyler/openapi — reproduced on dev at 8718cbc
• PHP 8.4

[milinsky]

@shadowhand Thanks for your issue. I will soon release a large number of fixes and improvements from the dev branch and return to your pull requests.