Introducing a new way to review your PRs.

Read the announcement

appwrite / appwrite

The open-source cloud for agents & devs. Including Auth, Databases, Storage, Functions, Messaging, Hosting, Realtime, WAF and more

View on GitHub

59 documents · Updated Nov 20, 2026

docs / openapi-library

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 formatCanonical versionMain schema rules
OpenAPI 2.0Version::V2OpenAPI 2.0 schema rules
OpenAPI 3.0 and its patch releasesVersion::V3_0OpenAPI 3.0 schema rules
OpenAPI 3.1 and its patch releasesVersion::V3_1OpenAPI 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 kindModel behaviorReason
Non-schema object referenceResolve to the referenced object while readingConsumers need the complete typed object
Schema referenceKeep a ReferenceSchema with its $ref valueRecursive 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 kindMain purpose
StringSchemaText length, pattern, format, and string values
IntegerSchema and NumberSchemaNumeric bounds and step rules
BooleanSchemaBoolean values
ObjectSchemaNamed properties, required properties, and additional properties
ArraySchemaItem schema, item limits, and uniqueness
CompositeSchemaoneOf, anyOf, allOf, and not relationships
ReferenceSchemaAn explicit $ref that has not been expanded
AnySchema and NeverSchemaUnrestricted 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 conceptCanonical model concept
host, basePath, and schemesServer objects
definitionsNamed schemas
Body parametersRequest bodies
Form-data parametersRequest content and encoding
consumes and producesMedia types
Response schemaResponse media schema
securityDefinitionsSecurity schemes
Root and operation securitySecurity 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

TriggerConsequenceGuard
Missing or unsupported swagger or openapi versionThe document cannot be assigned a readerRequire one of the supported version forms before reading
Caller-required version differs from the declared versionParsing stops with an invalid specification errorPass an expected Version only when the input contract is known
Missing local reference or invalid JSON Pointer escapeThe dependent object cannot be builtKeep local references valid and use ~1 for / and ~0 for ~
Circular non-schema reference chainObject resolution stops with a circular-reference errorKeep object reference chains acyclic
External reference in a model objectThe reference is not fetched or resolvedResolve external documents before passing input to this package
Recursive schema referenceSchema expansion would loop if references were followedTreat ReferenceSchema as a graph edge and resolve only when needed
OpenAPI 2.0 body and form-data parameters used togetherThe request cannot be represented as one normalized bodyUse one request-body style for an operation
Optional path parameterThe route contract is invalid for the modelMark every path parameter as required

Key files

FileWhy to read it
packages/…/Parser.phpShows input decoding, version detection, reader selection, and the public parser entry point
packages/…/Specification.phpDefines the canonical top-level model and its operation and schema access points
packages/…/OpenAPI2.phpShows how OpenAPI 2.0 concepts become the common model
packages/…/OpenAPI3.phpShows shared OpenAPI 3 path, operation, request, response, and security behavior
packages/…/Reader.phpDefines the source-to-schema-tree rules and version-sensitive schema behavior
packages/…/Dialect.phpSummarizes the schema rule differences between supported versions
packages/…/LocalResolver.phpDefines local JSON Pointer lookup, chained object references, and cycle checks
packages/…/Operation.phpDefines the API call description consumed by route and contract tooling
packages/…/CompositeSchema.phpPreserves schema composition and provides derived enum and conditional-reference views