utopia-php/openapi

• Add Specification::resolveSchema() for explicit local schema reference resolution.
• Support chained OpenAPI 3 component and Swagger 2 definition references.
• Preserve missing, external, and cyclic references.
• Handle percent-encoded local schema names safely.

• Map annotated string enumerations onto synthesized StringSchema metadata while preserving their CompositeSchema tree.
• Add CompositeSchema::stringEnum() for closed and open annotated enums.
• Derive enum type names from composite titles and value names from branch titles.
• Keep vendor extensions opaque instead of interpreting enum metadata from x-enum-name and x-enum-keys.
• Reject malformed annotated enum unions with source JSON Pointer context.

This is a breaking release. Consumers using enum vendor extensions should migrate their specifications to annotated enumerations before upgrading.

• Preserve empty enum-key lists as the signal to derive identifiers.
• Continue rejecting partial non-empty enum-key mappings.

• Preserve typed enum metadata for OpenAPI 2 inline parameters.
• Reject partial enum-key mappings.
• Restrict open-enum recognition to unrestricted string branches.

• Expose typed enum names and keys on StringSchema.
• Preserve open string-enum provenance on extracted enum branches.
• Validate every x-enum-keys entry as a string.

What's changed

• Expose the enum-bearing branch for open string enum anyOf schemas through CompositeSchema::openStringEnumBranch().

Full changelog: 0.1.1...0.1.2

Changed

• Stop interpreting the unofficial x-nullable extension as schema nullability.
• Preserve x-nullable only as an uninterpreted vendor extension where extensions are captured.

First tagged release.

A framework-independent OpenAPI parser with an immutable canonical model. A 2.0, 3.0 or 3.1 document reads into the same Specification shape, so consumers do not branch on the source version.

What it gives you

• One model for three versions. Utopia\OpenAPI\Parser::parse() detects the version and returns a Specification. A Swagger 2 document and the OpenAPI 3.1 document describing the same service produce the same shape.
• Typed schemas. One class per kind — ObjectSchema, ArraySchema, StringSchema, CompositeSchema, ReferenceSchema, and so on — all extending Schema, all readonly.
• References left intact. A $ref between schemas is preserved as a ReferenceSchema rather than expanded, because recursive schema graphs are legal. Object references (parameters, responses, examples, security schemes) are resolved.
• Extensions preserved. Any x- prefixed key is captured on every model that can carry one, and never interpreted.
• Located errors. Parse failures name their position as a JSON Pointer, so a bad value is traceable to where it came from.

Requirements

PHP 8.5+, ext-json.

Install

composer require utopia-php/openapi