feat(Spec): add plain OpenAPI 3.2 fields - #2149
Draft
DerManoMann wants to merge 4 commits into
Draft
Conversation
`Example::$value` and `Link::$requestBody` were the last two `mixed` properties defaulting to `null`, and so could not express an explicit `null`. Compiled output is unchanged. The convention, and why it exists, is now in `docs/dev/pipeline.md` under "`null` means unset, except where `null` is a value"; `UndefinedDefaultsTest` asserts it.
`OpenApi::$self`, `Server::$name`, `Response::$summary`, `Example::$dataValue`/`$serializedValue` and `Security\Scheme::$deprecated`/`$oauth2MetadataUrl`. Each is carried on the version-agnostic DTO and emitted only by `OpenApi32Compiler`, so 3.0 and 3.1 drop them the way they already drop `Tag::$parent`. `deprecated` and `oauth2MetadataUrl` also reach the typed `Security\Scheme\*` subtypes. The Example Object's mutual-exclusion rules are validated with a warning, matching the existing License `url`/`identifier` check. `MediaType::$description` is deliberately absent: it appears in the 3.2 JSON Schema but not in the spec's fixed-field table for the Media Type Object, and redocly rejects it.
Fourteen `CompilerTest` cases pairing "3.2 emits" with "3.1 omits" become one spec-mode fixture and three expected documents, since `ScratchTest`'s version matrix asserts the omissions without any test code. The emitted documents now go through `composer redocly`, which nothing else in the suite does for compiler output. Two cases could not move and stay in `CompilerTest`: the `$self` key position, because `assertSpecEquals` compares maps order-independently, and the mutual-exclusion warnings, which need a document redocly rejects. `Spec32.php` holds no fixture material — discovery globs `Scratch/*.php` and skips `-spec` names, so the classic file has to exist for the spec one to be found. With no classic YAMLs every classic combination skips and the anchor is never loaded.
DerManoMann
marked this pull request as draft
September 1, 2026 22:30
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
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.
Overview
This adds 3.2 fields that need nothing but a property and somewhere to emit it. Spec
attributes stay version-agnostic — one DTO carries every version's fields and the
per-version compiler decides what to emit — so each field is carried on the DTO and
emitted only by
OpenApi32Compiler. A 3.0 or 3.1 document drops it silently, the way italready drops
Tag::$parent.Along the way this settles a convention that was never written down: a
mixedpropertycannot use
nullto mean "unset", becausenullis a legal value for it.Changes
OpenApi::$self— a URI identifying the document, and the base URI for relativereferences
Server::$name— a unique name for the server, for use in toolingResponse::$summary— a short summary alongside the existingdescriptionExample::$dataValue— the example value before serializationExample::$serializedValue— the example value after serializationSecurity\Scheme::$deprecated— applies to every scheme typeSecurity\Scheme::$oauth2MetadataUrl— the RFC 8414 authorization server metadata URL,emitted for
oauth2schemes onlydeprecatedandoauth2MetadataUrlalso reach the typedSecurity\Scheme\*subtypesexisting License
url/identifiercheckExample::$valueandLink::$requestBodymove toUndefined::UNDEFINED, the sentinelevery other
mixedproperty already used, so both can now express an explicitnull.Compiled output is otherwise unchanged, and
HybridBridgepasses both straight throughinstead of translating them
docs/dev/pipeline.md@varonOpenApi::$securityis dropped