Opens in a new tabSkip to content
Agent LighthouseAgent Lighthouse

    Searches the text of every published page. The evidence sources themselves are not in this index — search all of them on the trusted sources page.

    GitHub ↗
    Browse checks and page contents
    agent-interfaces/openapi-schemas

    OpenAPI request/response schemas

    What it checks

    Without request/response schemas, AI agents must guess the data format for your endpoints. This leads to malformed requests and failed API calls. Define JSON schemas for all request bodies and responses.

    Why it matters

    The JSON Schema under an operation’s requestBody and responses content is what a tool-calling runtime turns into the tool’s input schema, and what the model uses to interpret the reply. An operation with no schema therefore forces the model to guess the payload shape.

    Evidence

    • Anthropic tool definitions take input_schema, “A JSON Schema object defining the expected parameters for the tool” — the request-body schema is what becomes that object when a spec is converted — platform.claude.com/…/define-tools (verified 2026-08-21)
    • OpenAI function calling: a function’s parameters are “defined by a JSON schema”, supporting “property types, enums, descriptions, nested objects” — developers.openai.com/…/function-calling (verified 2026-08-21)
    • Microsoft 365 Copilot states: “Parameters are used by Copilot to get all the required information from a user’s prompt for making a request to the API.” It also asks authors to “Clearly define all possible responses for each operation … Including examples of responses helps Copilot to understand what to expect from the API” — learn.microsoft.com/…/openapi-document-guidance (verified 2026-08-21)
    • Gemini function declarations accept only “a subset of the OpenAPI schema”, so schema shape directly determines whether an operation can be exposed at all — ai.google.dev/…/function-calling (verified 2026-08-21)

    Limits

    Microsoft’s own response example points its schema at $ref: '#/components/schemas/Repair'. The audit counts a media type’s schema as present when it holds any value, a $ref included, so that example passes. The reference itself is not resolved, so a $ref to a missing component also counts — learn.microsoft.com/…/openapi-document-guidance (verified 2026-10-17). A whole response written as a $ref to components/responses carries no content the audit can see, and counts as having no schema.

    No source states that a response schema is required for a call to succeed: the request-side schema carries the documented weight, while response schemas improve interpretation. Operations that legitimately return no body (204, HEAD, OPTIONS) and bodyless POSTs are normal API design, so the coverage ratio this audit computes overstates the mechanism’s reach.

    How it scores

    Every documented tool-calling runtime defines its parameters as JSON Schema, and one named agent, Microsoft 365 Copilot, is documented to read the spec’s parameters and responses for exactly this purpose. The response-side half is documented as an aid to interpretation, rather than a requirement for the call to succeed.

    Example finding

    A site publishes /openapi.json whose POST /contact operation declares no requestBody schema and whose responses declare no content schema. An agent must guess the field names and types to send, and cannot tell what came back.

    A site that publishes no OpenAPI document — or one that declares no operations — is not a failure here. Schema coverage was never measured, so the audit returns “not applicable” and takes no weight off the score.

    A document whose paths is present and yields nothing readable is a different case. That document exists and is broken — "paths": ["get","post"] puts a string where a path item belongs, {"/x": {"get": "yes"}} puts one where an operation belongs — so it still fails, and the report names the defect. Absent means absent; present-and-broken is a finding.

    One broken entry does not erase the operations beside it. Coverage is measured over the operations that can be read, and any entry that could not be read is named in the report rather than counted against the ones that could.

    Sources