OpenAPI description — agent readiness

Why an agent cares

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. Standard equipment on the web. Its absence is the exception rather than its presence. For this one in particular, the format is settled, but whether a site publishes its contract at all varies.

Direction of travel: ► flat, as at 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. 5 of these 7 can fail it. In a Lumar crawl these land on one row per site, in the crawl-level table where itemType is openapi.

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

Examples

Both of these are fixtures the test suite runs through the real collector, not snippets written for a document: the first is a shape we score as valid, the second is one we flag.

correctjsontest/e2e/test-pages/capabilities/correct.openapi.json

{
  "openapi": "3.1.0",
  "info": { "title": "Example Catalog API", "version": "1.0.0" },
  "paths": {
    "/pets": {
      "get": {
        "operationId": "listPets",
        "responses": {
          "200": {
            "description": "A list of pets",
            "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } }
          }
        }
      },
      "post": {
        "operationId": "createPet",
        "requestBody": {
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } }
        },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    }
  }
}

present but wrongjsontest/e2e/test-pages/capabilities/issues.openapi.json

{
  "openapi": "3.1.0",
  "info": { "title": "Broken Catalog API", "version": "1.0.0" },
  "paths": {
    "/pets": {
      "get": {
        "responses": {
          "200": {
            "description": "A list of pets",
            "content": { "application/json": { "schema": {} } }
          }
        }
      }
    }
  }
}

Specifications

Document	Revision	Kind
OpenAPI Specification	`3.2 (any 3.x accepted)`	specification

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