Align the docs with the implementation, and centralise references on Reference::

[tymondesigns]

Audit of the docs against the current implementation. Where the honest answer would have been a workaround, I fixed the thing that made the workaround necessary instead of writing it down.

Includes #23, merged into this branch, plus main merged in for PHP 8.4, Pest 5, and json-schema 2.

Code

Every reference is built through Reference::. The X::ref() shortcuts covered nine of the ten component registries and could never cover the tenth: schemas go through Reference::schema(), because Schema belongs to cortexphp/json-schema, which knows nothing about #/components. A family that advertises uniformity while omitting its most-used member is what makes Schema::ref('User') look reasonable when it cannot exist. Before the change there were 25 X::ref() call sites against 97 Reference:: ones, 61 of those Reference::schema(). All nine shortcuts were one-line delegations, so nothing is lost:

Response::ref('NotFound')     →  Reference::response('NotFound')
Parameter::ref('PetId')       →  Reference::parameter('PetId')
RequestBody::ref('Create')    →  Reference::requestBody('Create')
Header::ref('RateLimit')      →  Reference::header('RateLimit')
Example::ref('AdminUser')     →  Reference::example('AdminUser')
Link::ref('GetPet')           →  Reference::link('GetPet')
Callback::ref('OnEvent')      →  Reference::callback('OnEvent')
PathItem::ref('LegacyPets')   →  Reference::pathItem('LegacyPets')
SecurityScheme::ref('OAuth2') →  Reference::securityScheme('OAuth2')

Breaking, done now rather than after 1.0. The nine per-class tests went with them, since ReferenceTest already asserts all ten registries.

responses() accepts a referenced response. It keys each entry from getStatusCode(), and a bare Reference has none, so a referenced response could not go in. This is the only place in the package with that problem — Operation::parameters() and PathItem::parameters() take Parameter|Reference happily, because they build a list and derive no key. Removing the static freed the name for the fluent form:

Operation::get()->responses(
    Response::ok()->json(Reference::schema('User')),
    Response::notFound()->ref('NotFound'),
);

Byte-identical to ->response(404, Reference::response('NotFound')), asserted in a test rather than eyeballed. A referenced response emits the $ref alone, because a Reference Object has nowhere to put content — last-call-wins, matching responses() and content(), and pinned by a test.

Nested schemas leaked the JSON Schema $schema URI. JSON Schema 2020-12 core §8.1.1 allows it only at the root of a schema resource, and OAS 3.1 §Schema Object repeats the restriction, so every nested occurrence the builder can produce is invalid output. BuildsArray now strips it at every depth, skipping maps whose keys are user-chosen so a property literally named $schema survives, and leaving raw array schemas alone as the way to declare a dialect deliberately.

One for the json-schema side: 2.0 fixed this for items but contains still emits the URI. Of its ~20 nested serialization call sites those two were the only ones not passing includeSchemaRef: false by hand, and the fix reached one of them. A propagating rule rather than an argument repeated per keyword would have caught both.

Docs

New page: Validation & Output. The "Built-in Validation" and "Multiple Output Formats" cards both linked to /openapi/validation-and-output, which was never written. It covers validate(), the structured errors() payload keyed by JSON pointer, what the meta-schema does and does not catch, and the three output formats. It also decodes the anyOf error that reports one rule as three missing-property lines.

Page	Was	Now
Introduction	OpenApi::v310() / v311()	OpenApi::create(OpenApiVersion::V3_1_1)
Introduction	"$schema and title are stripped"	Builder names are dropped, an explicit ->title() is published, $schema never appears
Components, Webhooks	allOf(Reference::schema('BaseEntity')) — a TypeError	allOf(Schema::typeless()->ref(...)); Schema::object()->ref() emits a stray "type": "object" beside the $ref
Info & Metadata	Tags referenced "by name string"	tags() takes Tag objects, strings, or a mix
Request Bodies	->style(string)	->style() also takes the Style enum
Installation	—	YAML needs symfony/yaml; toYaml() throws without it
README	Info::create()->title(...)->version(...)	Info::create('Example API', '1.0.0')

Also added: Operation::callback(), jsonSchemaDialect(), and Reference::example(), plus missing use statements in the Security and Webhooks samples. The quickstart's "Working with References" section is now the single place references are taught.

Left alone

• discriminator and xml have no builder method. They are OpenAPI fields rather than JSON Schema ones. Documented as spreading a built schema into the array form, instead of hand-writing the whole array.
• A mis-targeted reference still ships silently. ->response(200, Reference::schema('User')) type-checks, since every reference is the same class, and validate() passes it because pointers are never resolved. Catching that needs a reference-integrity pass over the finished document — separate work, and the same pass would close the dangling-$ref gap the new page has to document as a blind spot.
• No $id-aware exception in the $schema strip. Unreachable through the builder, and it would survive mutation testing as dead code.

Verification

All 13 CI checks pass: PHP 8.4 and 8.5, prefer-lowest and prefer-stable, Linux and Windows, plus format, phpstan, type-coverage, and CodeQL.

Locally on PHP 8.4 with json-schema 2.0: 193 tests, PHPStan level 10, ECS and Rector clean, 100% type coverage, mutation score 83.46%. Every sample on the touched pages was executed against the package, and the README example builds and validates.

The $schema tests assert only that no nested URI survives, rather than asserting upstream's bug as a precondition — which is precisely what broke when json-schema 2.0 fixed items.

  

[Copilot]

🟡 Changes recommended

Recursive schema sanitization can corrupt arbitrary values containing a $schema property.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Aligns documentation with the implemented API, centralizes component references, supports referenced responses, and sanitizes nested schemas.

Changes:

• Replaces object-specific reference shortcuts with Reference::*.
• Adds fluent referenced responses while retaining status codes.
• Expands documentation and nested-schema handling.

File summaries

File	Description
README.md	Corrects validation and Info examples.
src/Concerns/BuildsArray.php	Recursively removes nested $schema keys.
src/Objects/Callback.php	Removes the callback reference shortcut.
src/Objects/Example.php	Removes the example reference shortcut.
src/Objects/Header.php	Removes the header reference shortcut.
src/Objects/Link.php	Removes the link reference shortcut.
src/Objects/Parameter.php	Removes the parameter reference shortcut.
src/Objects/PathItem.php	Removes the path-item reference shortcut.
src/Objects/RequestBody.php	Removes the request-body reference shortcut.
src/Objects/Response.php	Adds status-preserving fluent references.
src/Objects/SecurityScheme.php	Removes the security-scheme reference shortcut.
tests/Unit/Concerns/BuildsArrayTest.php	Tests nested schema sanitization.
tests/Unit/Objects/CallbackTest.php	Removes shortcut coverage.
tests/Unit/Objects/ExampleTest.php	Removes shortcut coverage.
tests/Unit/Objects/HeaderTest.php	Removes shortcut coverage.
tests/Unit/Objects/LinkTest.php	Removes shortcut coverage.
tests/Unit/Objects/OperationTest.php	Tests referenced responses and callbacks.
tests/Unit/Objects/ParameterTest.php	Removes shortcut coverage.
tests/Unit/Objects/PathItemTest.php	Removes shortcut coverage.
tests/Unit/Objects/RequestBodyTest.php	Removes shortcut coverage.
tests/Unit/Objects/ResponseTest.php	Tests fluent response references.
tests/Unit/Objects/SecuritySchemeTest.php	Removes shortcut coverage.
docs/docs.json	Adds the validation page to navigation.
docs/openapi/components.mdx	Updates component reference guidance.
docs/openapi/info-and-metadata.mdx	Clarifies operation tag inputs.
docs/openapi/installation.mdx	Documents the optional YAML dependency.
docs/openapi/introduction.mdx	Corrects schema and version guidance.
docs/openapi/paths-and-operations.mdx	Documents tags and response attachment.
docs/openapi/quickstart.mdx	Centralizes reference documentation.
docs/openapi/request-bodies.mdx	Updates styles and references.
docs/openapi/responses.mdx	Documents fluent referenced responses.
docs/openapi/security.mdx	Adds a missing import.
docs/openapi/validation-and-output.mdx	Adds validation and serialization guidance.
docs/openapi/webhooks-and-callbacks.mdx	Corrects schema references and callback examples.

Review details

Suppressed comments (3)

tests/Unit/Objects/ResponseTest.php:94

• The test description still names refTo() even though the exercised API is ref().
  tests/Unit/Objects/ResponseTest.php:98
• Rename the stale refTo() reference to ref() so test output identifies the public method correctly.
  tests/Unit/Objects/ResponseTest.php:107
• This test description refers to the discarded refTo() name rather than the implemented ref() method.

• Files reviewed: 34/34 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.