OpenAPI modeling and parsing library
The OpenAPI package is a framework-independent PHP library that reads OpenAPI 2.0, 3.0, and 3.1 documents into one immutable, typed API model. It gives reusable platform packages a common view of API metadata, operations, schemas, requests, responses, servers, and security without making each consumer handle each source format. See the reusable platform packages page for the wider package group and the API platform page for the system that uses API descriptions.
Canonical specification model
The Specification is the library's main product. It presents the same model shape for supported source versions so downstream code can inspect an API description without first branching on its document format.
Specification versions
The library supports OpenAPI 2.0, OpenAPI 3.0, and OpenAPI 3.1. A coarse Version identifies the model rules, while sourceVersion keeps the exact string declared by the document. For example, all 3.1 patch releases use the 3.1 model version but keep their full source version for consumers that need it.
| Source format | Canonical version | Main schema rules |
|---|---|---|
| OpenAPI 2.0 | Version::V2 | OpenAPI 2.0 schema rules |
| OpenAPI 3.0 and its patch releases | Version::V3_0 | OpenAPI 3.0 schema rules |
| OpenAPI 3.1 and its patch releases | Version::V3_1 | OpenAPI 3.1 schema rules |
Swagger 1.x is outside the supported set. The model also preserves an OpenAPI 3.1 jsonSchemaDialect value as source metadata, but it does not select custom dialect behavior.
References: packages/…/Version.php• L7-27 packages/…/Specification.php• L18-42 packages/…/Dialect.php• L9-27
Specification contents
The canonical model joins the parts of an API description that consumers need to understand how an API is named, reached, called, and secured. The top-level object provides these related areas:
- API identity through
Info, tags, external documentation, and vendor extensions. - Deployment targets through servers and server variables.
- Service behavior through paths and operations.
- Data contracts through named schemas.
- Access rules through security schemes and security requirements.
The model is read-only after parsing. Consumers can retrieve all operations in document order or select operations by tag, while tags remain descriptive OpenAPI tags and do not acquire platform-specific meaning.
References: packages/…/Specification.php• L18-93 packages/…/Info.php• L7-35 packages/…/Server.php• L7-25
Parser and reference flow
The parser turns JSON text or a decoded associative array into the canonical specification. It detects the declared format, selects the matching reader and schema rules, and reports structural errors with a location in the source document.
Parser flow
The parser accepts JSON content or an already decoded document. It reads the swagger or openapi version field, checks an optional caller-supplied expected version, and then sends the document to the reader for that version.
The following flow shows how source input becomes a version-independent model.
flowchart LR
A[JSON text or decoded document] --> B[Parse and normalize input]
B --> C[Detect source version]
C --> D{Supported version}
D -->|2.0| E[OpenAPI 2 reader]
D -->|3.0| F[OpenAPI 3.0 reader]
D -->|3.1| G[OpenAPI 3.1 reader]
E --> H[Canonical Specification]
F --> H
G --> H
The parser checks the structure needed to build the model. It does not provide complete OpenAPI conformance validation, YAML parsing, serialization, or implicit file and network access.
References: packages/…/Parser.php• L17-40 packages/…/Parser.php• L43-114 packages/…/Reader.php• L7-12
Reference resolution flow
References connect one part of an OpenAPI document to another. The library resolves local references for model objects such as parameters, responses, examples, and security schemes, while schema references stay as explicit ReferenceSchema nodes so recursive data contracts remain safe and visible.
Local references use JSON Pointer syntax. The resolver decodes pointer escapes, follows chained local object references, detects cycles, and rejects missing or external references. It never fetches a file or URL on its own.
The two reference paths have different goals:
| Reference kind | Model behavior | Reason |
|---|---|---|
| Non-schema object reference | Resolve to the referenced object while reading | Consumers need the complete typed object |
| Schema reference | Keep a ReferenceSchema with its $ref value | Recursive schema graphs must not be expanded |
The specification can later resolve a chain of local component schema references when a consumer needs the concrete local schema. Missing, external, and cyclic schema references remain unresolved in that step.
References: packages/…/LocalResolver.php• L10-65 packages/…/AbstractReader.php• L223-233 packages/…/Specification.php• L45-72 packages/…/ReferenceSchema.php• L7-24
Schema model
Schemas describe the data accepted or returned by an API. The library converts source schema forms into a typed schema tree that keeps both simple constraints and composition relationships available to consumers.
Schema kinds and constraints
Every schema shares common annotations such as a title, description, nullability, default, enum values, format, examples, read-only state, write-only state, deprecation, and extensions. The concrete kind then adds the rules that apply to that data shape.
| Schema kind | Main purpose |
|---|---|
StringSchema | Text length, pattern, format, and string values |
IntegerSchema and NumberSchema | Numeric bounds and step rules |
BooleanSchema | Boolean values |
ObjectSchema | Named properties, required properties, and additional properties |
ArraySchema | Item schema, item limits, and uniqueness |
CompositeSchema | oneOf, anyOf, allOf, and not relationships |
ReferenceSchema | An explicit $ref that has not been expanded |
AnySchema and NeverSchema | Unrestricted and impossible schema values |
Object properties and array items contain more schema nodes, so consumers can walk the tree when they need to understand nested data. Vendor extensions remain opaque maps and are not assigned package-specific meaning.
References: packages/…/Schema.php• L7-27 packages/…/ObjectSchema.php• L7-32 packages/…/ArraySchema.php• L7-27 packages/…/Reader.php• L42-174
Schema composition
Composite schemas preserve the source relationship instead of reducing it to one concrete type. This matters when an API uses alternatives, shared parts, exclusions, or discriminators to describe a data contract.
OpenAPI 3.1 annotated string values receive a useful view without losing the original composite tree. A oneOf or anyOf made from titled string constants can expose a synthesized string enum with its values and names. If the union also allows any other string, the enum is marked open so consumers do not treat the listed values as exhaustive.
Composite schemas can also expose conditional references. These are selection hints that pair a referenced schema with required scalar conditions from the same union branch. They are not validation results and do not guarantee that anyOf branches are exclusive.
References: packages/…/CompositeSchema.php• L9-120 packages/…/CompositeSchema.php• L189-219 packages/…/Reader.php• L107-120
Version-specific schema rules
The schema reader applies the rules allowed by the selected OpenAPI version. OpenAPI 3.1 permits boolean schemas, type arrays, and const; OpenAPI 2.0 and 3.0 do not. OpenAPI 3.0 nullability uses nullable, while OpenAPI 3.1 can express null in a type array.
This distinction is about how the source document is read. It does not split the model into separate 2.0, 3.0, and 3.1 schema classes.
References: packages/…/Dialect.php• L9-27 packages/…/Reader.php• L42-105 packages/…/Reader.php• L192-211
API description model
The API model describes the call surface around the schema tree. It links an operation to its route, parameters, request content, response content, server targets, tags, and access rules.
Paths and operations
Paths group operations by route. Each operation records its HTTP method, path, identifier, tags, description, deprecation state, parameters, request body, responses, servers, security, and extensions.
Path-level parameters are inherited by their operations. An operation parameter with the same case-sensitive name and location replaces the inherited parameter. This gives consumers one effective parameter list while retaining the source scope that defines the route.
References: packages/…/PathItem.php• L7-29 packages/…/Operation.php• L7-33 packages/…/OpenAPI3.php• L55-156 packages/…/OpenAPI2.php• L78-182
Requests and responses
Requests and responses use a shared content model based on media types. A request body describes whether content is required and maps media types to schemas, examples, and encoding rules. A response keeps its description, headers, media types, and examples under the original status-code or default key.
OpenAPI 2.0 body parameters and form-data parameters are normalized into this same request model. Its consumes and produces lists become request and response media types, which lets consumers handle content in the same way across source versions.
References: packages/…/RequestBody.php• L7-19 packages/…/Response.php• L7-20 packages/…/MediaType.php• L7-21 packages/…/OpenAPI2.php• L113-164 packages/…/OpenAPI3.php• L107-126
Security requirements
Security schemes define available access methods. They cover API keys, HTTP authentication, OAuth 2 flows, OpenID Connect, and OpenAPI 3.1 mutual TLS. Security requirements state how those schemes apply to the API or to an operation.
The model keeps OpenAPI's two levels of security logic. Schemes in one requirement are used together, while separate requirements are alternatives. Missing operation security inherits the root rule; an explicit empty list disables inherited security; an empty requirement permits anonymous access as one alternative.
References: packages/…/SecurityScheme.php• L7-25 packages/…/SecurityRequirement.php• L7-12 packages/…/AbstractReader.php• L137-153 packages/…/OpenAPI3.php• L129-151
Cross-version normalization
The readers interpret source-specific fields and place their meaning into the common model. OpenAPI 2.0 is read directly rather than first being rewritten as an OpenAPI 3 document.
OpenAPI 2.0 mapping
The main normalization choices make older and newer API descriptions comparable:
| OpenAPI 2.0 source concept | Canonical model concept |
|---|---|
host, basePath, and schemes | Server objects |
definitions | Named schemas |
| Body parameters | Request bodies |
| Form-data parameters | Request content and encoding |
consumes and produces | Media types |
Response schema | Response media schema |
securityDefinitions | Security schemes |
Root and operation security | Security requirements |
Global and operation-level values keep their source inheritance and override behavior during this mapping. The result is one model for downstream consumers rather than a separate access pattern for OpenAPI 2.0.
References: packages/…/OpenAPI2.php• L22-57 packages/…/OpenAPI2.php• L59-75 packages/…/OpenAPI2.php• L105-182 packages/…/AbstractReader.php• L235-313
Change checklist
When these files or sections are changed, remember to consider these:
- When a supported source version changes, keep version detection, schema dialect rules, and the matching reader aligned.
- When a canonical model field changes, check both OpenAPI 2.0 and OpenAPI 3 readers so normalization still produces the same contract.
- When reference behavior changes, preserve the split between local object resolution and unexpanded schema references.
- When security inheritance or parameter inheritance changes, check root, path, and operation scopes together.
- When schema composition changes, keep the original composite tree and the derived enum or conditional-reference views consistent.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
Missing or unsupported swagger or openapi version | The document cannot be assigned a reader | Require one of the supported version forms before reading |
| Caller-required version differs from the declared version | Parsing stops with an invalid specification error | Pass an expected Version only when the input contract is known |
| Missing local reference or invalid JSON Pointer escape | The dependent object cannot be built | Keep local references valid and use ~1 for / and ~0 for ~ |
| Circular non-schema reference chain | Object resolution stops with a circular-reference error | Keep object reference chains acyclic |
| External reference in a model object | The reference is not fetched or resolved | Resolve external documents before passing input to this package |
| Recursive schema reference | Schema expansion would loop if references were followed | Treat ReferenceSchema as a graph edge and resolve only when needed |
| OpenAPI 2.0 body and form-data parameters used together | The request cannot be represented as one normalized body | Use one request-body style for an operation |
| Optional path parameter | The route contract is invalid for the model | Mark every path parameter as required |
Key files
| File | Why to read it |
|---|---|
| packages/…/Parser.php | Shows input decoding, version detection, reader selection, and the public parser entry point |
| packages/…/Specification.php | Defines the canonical top-level model and its operation and schema access points |
| packages/…/OpenAPI2.php | Shows how OpenAPI 2.0 concepts become the common model |
| packages/…/OpenAPI3.php | Shows shared OpenAPI 3 path, operation, request, response, and security behavior |
| packages/…/Reader.php | Defines the source-to-schema-tree rules and version-sensitive schema behavior |
| packages/…/Dialect.php | Summarizes the schema rule differences between supported versions |
| packages/…/LocalResolver.php | Defines local JSON Pointer lookup, chained object references, and cycle checks |
| packages/…/Operation.php | Defines the API call description consumed by route and contract tooling |
| packages/…/CompositeSchema.php | Preserves schema composition and provides derived enum and conditional-reference views |