Documentation version: nextdevelopment documentation
Skip to content

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 ​

bash
vendor/bin/gesso doctor \
  --spec=openapi/front.yaml \
  --strip-prefix=/api

The 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: cookie parameters;
  • parameters declared with content instead of schema, except the OpenAPI 3.2 in: querystring parameter;
  • request or response media types using itemSchema streaming, unless a JSON media type also declares schema;
  • non-JSON media types that declare a schema, except form request bodies (application/x-www-form-urlencoded, multipart/form-data) and application/x-www-form-urlencoded responses (an application/* range is reported too: it validates JSON bodies only);
  • multipart/form-data responses with a schema;
  • JSON media-type keys that carry parameters (application/json; charset=utf-8): runtime validation matches JSON keys literally and never selects them;
  • operation callbacks and root webhooks, 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:

  • example and every examples.<name>.value on Media Type, Parameter, and Header objects;
  • example on Schema objects and, in OpenAPI 3.1/3.2, every entry of the examples array, 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:

bash
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:

bash
vendor/bin/gesso doctor \
  --spec=openapi/bundled/front.yaml \
  --local-ref-root=openapi \
  --phpunit-snippet

The 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:

bash
vendor/bin/gesso doctor \
  --spec=openapi/front.yaml \
  --spec=openapi/admin.json \
  --strip-prefix=/api \
  --emit-config > gesso.php

The 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:

Optiongesso.php key
--specspec.base_path + spec.names (front when names is absent), the same specs the PHPUnit extension loads
--strip-prefixspec.strip_prefixes
--acknowledge-unvalidatable-schemevalidation.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:

bash
vendor/bin/gesso doctor

The 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):

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:

bash
vendor/bin/gesso doctor \
  --spec=openapi/root.yaml \
  --allow-remote-refs \
  --remote-ref-host=specs.example.com \
  --remote-ref-max-bytes=10485760

The 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:

bash
$ vendor/bin/gesso --version
gesso 3.0.0

It 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.

json
{
    "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 ​

CodeMeaning
0All selected specs are compatible. Warnings and skipped features may still be present.
1At least one diagnostic error prevents reliable contract enforcement.
2The 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.