API Schema Quality for Agent Consumption

API Schema Quality for Agent Consumption asks whether an AI agent can actually use your OpenAPI spec, not just whether one exists. friendly4AI parses a prefetched spec and checks four quality categories: unique operationId coverage, typed 2xx response schemas, response examples, and RFC 7807 application/problem+json error models. Pass three of the four and you earn the full score of 100.

What does this parameter check?

When friendly4AI has a prefetched spec, it reads the paths and measures four quality categories:

• The share of operations carrying a unique operationId.
• The share with typed 2xx response schemas (a $ref or type).
• The share with response examples.
• Whether the spec uses RFC 7807 application/problem+json error models.

If no spec parses, the scanner looks for those same signals in the homepage HTML instead.

Why does schema quality matter for AI-readiness?

An agent can only call your API reliably when the spec spells out exactly what to send and what comes back:

• Unique operationId values give the agent stable function names.
• Typed request and response schemas let it build and validate payloads.
• Response examples show it what a real call looks like.
• A consistent error model (RFC 7807 Problem Details) lets it recover from a failure instead of crashing.

A spec that exists but stays untyped or inconsistent leaves the agent guessing. That guess is where most automated integrations fall apart.

How is the score calculated?

This is a gradient AI-Specific Signals parameter. The scanner sharpens the published rubric with concrete thresholds.

With a parseable spec, it counts how many quality categories clear their bar: operationId coverage at least 70%, typed 2xx responses at least 70%, examples at least 30%, and RFC 7807 usage.

• Pass (100): three or more categories hold.
• Partial (50): one or two categories hold.
• None: falls through to the HTML-signal path.

In the HTML fallback (no parseable spec), the strong signals are operationId, typed schemas, examples, and RFC 7807.

• Pass (100): two or more strong signals.
• Partial (50): any single strong signal, or a supporting signal such as openapi/swagger, responses, or application/json.
• Fail (0): nothing detectable.

This parameter is API-conditional. Its weighted contribution counts only when an API is detected on the site (via api-discoverability); otherwise its effective weight drops to zero and it is excluded from the score. Related signals include api-auth-transparency and action-api.

How do I fix common issues?

• Give every operation an operationId, and push the coverage well past the 70% threshold.
• Replace free-form objects with typed request and response schemas built from $ref components, so at least 70% of operations carry typed 2xx responses.
• Add example payloads to your most common operations. Even 30% coverage moves the needle.
• Standardize on one error format across every endpoint: RFC 7807 Problem Details (application/problem+json).
• Re-scan once the spec is tighter. Hit three of the four categories and the full score follows.