Doctor command
gesso doctor answers one focused question before the test suite starts: can this package load and enforce the selected OpenAPI contract as configured?
It is not a replacement for a semantic or style linter such as Spectral or Redocly.
Scope
gesso doctor is a preflight for a local OpenAPI file. It confirms Gesso can load and enforce the document — version and dialect, references, warned-about keywords, structurally valid operations — and exits non-zero when it can't. It also warns about examples that drifted from their schema. It does not fetch a deployed spec URL, and it does not compare the checked-in spec against what a running service returns. --allow-remote-refs only covers $ref targets from the local entry document.
Basic usage
vendor/bin/gesso doctor \
--spec=openapi/front.yaml \
--strip-prefix=/apiThe command checks file readability and parser availability, the declared OpenAPI version and JSON Schema dialect, internal and external references, schema keywords that the validator warns about, and structurally valid operations, request bodies, and response definitions. It also reports recognized features that are intentionally not enforced.
Request-body checks share the runtime validator's structural rules for requestBody, content, media-type entries, schema, itemSchema, and request encoding maps and entries. Doctor reports all malformed nodes as structure errors, including media types a particular request would not select and operations without responses in OpenAPI 3.1/3.2. These checks do not turn doctor into a complete OpenAPI linter: for compatibility, missing or null request-body and request-content nodes retain the runtime behavior, and response-side encoding is not inspected.
Features runtime validation does not enforce
Doctor reports each part of the contract that runtime validation accepts without checking as a skipped issue in the feature category, so a clean report means what the test suite will actually enforce:
in: cookieparameters;- parameters declared with
contentinstead ofschema, except the OpenAPI 3.2in: querystringparameter; - request or response media types using
itemSchemastreaming, unless a JSON media type also declaresschema; - non-JSON media types that declare a
schema, except form request bodies (application/x-www-form-urlencoded,multipart/form-data) andapplication/x-www-form-urlencodedresponses (anapplication/*range is reported too: it validates JSON bodies only); multipart/form-dataresponses with aschema;- JSON media-type keys that carry parameters (
application/json; charset=utf-8): runtime validation matches JSON keys literally and never selects them; - operation
callbacksand rootwebhooks, which no request path reaches.
Media types are reported only when the surrounding body structure is valid; a malformed node is a structure error instead. These issues never change the exit code.
JSON and YAML are supported. YAML requires the optional symfony/yaml package, just like runtime validation.
Examples that do not match their schema
Doctor validates every inline example against the schema it illustrates and reports each one the schema rejects as a warning in the example category (GSO314). The spec stays enforceable, so the exit code does not change, but generated docs, mocks, and fakes that serve the example drifted from the contract. Checked:
exampleand everyexamples.<name>.valueon Media Type, Parameter, and Header objects;exampleon Schema objects and, in OpenAPI 3.1/3.2, every entry of theexamplesarray, including nested property and composition schemas.
Examples are checked with the runtime validation pipeline: the same schema conversion (nullable, the document's JSON Schema dialect, discriminator enforcement) and the same validator, so doctor and runtime agree on what a value is. A request body or parameter example is checked as a request, so a readOnly property in it is rejected; a response or header example is checked as a response. A Schema-level example describes both directions and may carry readOnly and writeOnly properties. externalValue is never fetched, and media types runtime validation does not evaluate (non-JSON, non-form) are not checked. An example shared through a $ref within the document is reported once, where it is defined; an example copied by hand is reported at every place it appears.
In YAML, an unquoted date or date-time is read as a string in canonical form (2024-01-01, 2024-01-01T12:00:00Z). Quote a value whose exact spelling matters: example: 2024-01-01 12:00:00 is read as 2024-01-01T12:00:00.
Multiple specs
Repeat --spec, or provide comma-separated paths:
vendor/bin/gesso doctor \
--spec=openapi/front.yaml \
--spec=openapi/admin.json \
--strip-prefix=/api--phpunit-snippet prints the equivalent extension configuration when all entry documents share one directory: the bare <bootstrap> XML, followed by the same gesso.php that --emit-config writes. The snippet uses each entry document's filename without its extension as the configured spec name.
Local external references are confined to each entry document's directory by default. If an entry and its shared schemas use sibling directories, pass their narrowest trusted common parent:
vendor/bin/gesso doctor \
--spec=openapi/bundled/front.yaml \
--local-ref-root=openapi \
--phpunit-snippetThe generated PHPUnit snippet then uses 'base_path' => 'openapi' and the spec name bundled/front. Targets that escape the canonical root through ../, an absolute path, or a symlink are rejected; those forms remain valid when their canonical targets stay inside the root.
Generate a gesso.php
--emit-config prints the same settings as a gesso.php file on stdout, so it can be redirected straight into place:
vendor/bin/gesso doctor \
--spec=openapi/front.yaml \
--spec=openapi/admin.json \
--strip-prefix=/api \
--emit-config > gesso.phpThe file sets spec.base_path, spec.names, and, when given, spec.strip_prefixes and validation.acknowledged_unvalidatable_schemes. The base path is relative to the working directory, which is where gesso.php resolves it from when the file is written there. The report goes to stderr (or --output-file) so stdout carries only the PHP source. Nothing is printed to stdout when a spec is rejected, and, as with --phpunit-snippet, every entry document must share one directory unless --local-ref-root names a common one; otherwise the command exits 2.
Read settings from gesso.php
The doctor reads ./gesso.php, or the file named by --config=<path> (relative to the working directory), and defaults these options from it:
| Option | gesso.php key |
|---|---|
--spec | spec.base_path + spec.names (front when names is absent), the same specs the PHPUnit extension loads |
--strip-prefix | spec.strip_prefixes |
--acknowledge-unvalidatable-scheme | validation.acknowledged_unvalidatable_schemes |
Each name resolves to the entry document the runtime loader picks (<base_path>/<name>.json, then .yaml, then .yml), and spec.base_path is the local-ref root unless --local-ref-root is given. Specs taken from the file always stay inside it, as at runtime: a spec.names entry with a .. segment or an absolute path is an error. An explicit --spec under spec.base_path uses it too; one outside it keeps its own directory as the root, without affecting the others. Writing --emit-config > gesso.php over the conventional file works: the empty file the shell creates is not read as a configuration. Once the file from --emit-config is in place, run the doctor without flags:
vendor/bin/gesso doctorThe report is the same as the run that emitted the file. An explicit flag wins over the file. A --config file that is missing or invalid is a usage error (exit 2); an absent ./gesso.php changes nothing.
Acknowledged unvalidatable security schemes
When the test suite acknowledges an unvalidatable security scheme by name (see Acknowledging an unvalidatable security scheme), set it once in gesso.php and the doctor reads it from there (see Read settings from gesso.php):
'validation' => [
'acknowledged_unvalidatable_schemes' => ['ClientBasicAuth'],
],--acknowledge-unvalidatable-scheme=<name> (repeatable) overrides the file for one run.
The scheme is still listed as a skipped feature, marked as acknowledged instead of prompting for a separate authentication test. A name that is not defined in components.securitySchemes, or that names a scheme the validator can enforce, is reported as a configuration warning so the acknowledged list cannot rot.
HTTP references
Remote references remain opt-in because diagnostics must not access the network unexpectedly:
vendor/bin/gesso doctor \
--spec=openapi/root.yaml \
--allow-remote-refs \
--remote-ref-host=specs.example.com \
--remote-ref-max-bytes=10485760The command automatically uses an installed Guzzle (guzzlehttp/guzzle plus guzzlehttp/psr7) or Symfony HttpClient PSR-18 implementation. Every permitted host must be listed with --remote-ref-host; repeat the option when a trusted contract intentionally spans hosts. A nested $ref that switches to an unlisted host is rejected before any request is sent. Each remote document is limited to 10 MiB by default; use --remote-ref-max-bytes=<positive integer> only when a trusted contract requires a larger bound. Without --allow-remote-refs, an HTTP(S) $ref is reported as a reference error with an actionable hint. Network failures, oversized or malformed remote documents, content-type mismatches, and reference cycles also exit non-zero.
Installed version
gesso --version is a global flag on the binary, matched before any subcommand:
$ vendor/bin/gesso --version
gesso 3.0.0It writes to STDOUT, writes nothing to STDERR, and exits 0. When Composer's InstalledVersions metadata cannot be read it prints gesso unknown — the same sentinel the JSON documents emit — and still exits 0, so a CI script or an agent probing for the version always gets an answer rather than a usage error. gesso --help lists it under Global options:.
Machine-readable output
Use --format=json for CI and tooling. The top-level schema_version is currently 2 and will change if the machine-readable contract requires an incompatible revision.
Add --output-file=<path> to write the report, in either format, to a file instead of stdout. The file gets the same bytes stdout would.
{
"schema_version": 2,
"tool": {
"name": "studio-design/gesso",
"version": "3.0.0"
},
"status": "ok",
"summary": {
"specs": 1,
"operations": 4,
"responses": 7,
"errors": 0,
"warnings": 0,
"skipped": 0
},
"specs": [],
"issues": [],
"phpunit": null
}tool is { "name": "studio-design/gesso", "version": "<installed version or 'unknown'>" }, the same block the coverage JSON and validation JSON documents carry, in the format described under Installed version. "unknown" is emitted when Composer's InstalledVersions metadata is unavailable; the field is always a string.
Additive changes — a new field such as tool, or a new category slug — keep schema_version at 2. Removals, renames, and type changes bump it. Version 2 (3.0) renamed the v2 schemaVersion key to schema_version.
Every issue has a stable severity, category, spec, message, and nullable suggestion field, plus the failure code of its category in code (for example GSO306 for structure) and that code's page in docs_url. An example issue also carries pointer, the RFC 6901 pointer to the example in the spec, and schema_pointer, the pointer to the failing keyword in the example's schema (after $ref inlining and conversion, as in validation JSON) or null. The text report prints the code before the category: ERROR [GSO306] [structure] openapi.json: …. gesso explain <code> prints the same entry in the terminal. Severities are:
error: the contract cannot be loaded or enforced as configured;warning: validation can proceed, but the package detected a compatibility limitation;skipped: a recognized contract feature is not currently enforced and needs a separate test.
Categories currently emitted are io, parser, version, dialect, references, structure, keyword, feature, dependency, configuration, spec, compatibility, internal, and example. Consumers should branch on severity and category, not the human-readable message.
Exit codes
| Code | Meaning |
|---|---|
0 | All selected specs are compatible. Warnings and skipped features may still be present. |
1 | At least one diagnostic error prevents reliable contract enforcement. |
2 | The command-line invocation is invalid, such as a missing --spec or unknown format. |
An --output-file that cannot be written also exits 2. Shared conventions: CLI reference.
Treat both 1 and 2 as CI failures. Always inspect warnings and skipped features even when the exit code is 0.