# OpenAPI description

A machine-readable contract for the site's API.

**[Capabilities](/docs/capabilities)** · checked once per host (item type `openapi`) · 5 checks that can fail it

It is the difference between an agent guessing at an API and calling it correctly first time. Most of what we flag is optional per the spec and load-bearing for an agent, such as a missing `operationId` or an absent server URL.

## Adoption

**Web baseline** (L4) — the format is settled, but whether a site publishes its contract at all varies

Standard equipment on the web. Its absence is the exception rather than its presence. Direction of travel: ► flat, as of 2026-07-28.

The de facto standard for describing REST APIs. The variable is not adoption but whether the contract is served publicly.

## What we check

Absence is never a finding: every check below runs only once `openApiPresent` is true, so a site that has not
adopted this is not assessed on it and appears in no report.

| Check | Kind | Raises | On whose authority |
|---|---|---|---|
| `openApiInvalidDocument` | high severity | usability | Lumar readiness profile |
| `openApiInvalidVersion` | medium severity | usability | Lumar readiness profile |
| `openApiMissingOperationId` | medium severity | usability | Lumar readiness profile |
| `openApiDuplicateOperationId` | medium severity | conformance, usability | specification (OpenAPI 3.2.0) |
| `openApiUntypedSchema` | medium severity | usability | Lumar readiness profile |
| `openApiUnresolvedReference` | informational | nothing | specification (OpenAPI 3.2.0) |
| `openApiPartiallyAssessed` | coverage note | nothing | our own coverage |

## Examples

These are the fixtures the test suite runs through the real collector, not snippets written for a document.

- Correct: `test/e2e/test-pages/capabilities/correct.openapi.json`
- Present but wrong: `test/e2e/test-pages/capabilities/issues.openapi.json`

## Specifications

| Document | Revision | Kind |
|---|---|---|
| [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) | 3.2 (any 3.x accepted) | specification |

Last re-read against the published documents: 2026-08-12.