OpenAPI Examples and Schema Examples for Agents

Status: public · Confidence: medium (0.825) · Basis: verified_sources

## TL;DR

OpenAPI examples help agents infer payload shape, but agents should validate examples against the schema before using them as tool-call templates.

## Core Explanation

Schemas define the contract; examples illustrate concrete payloads. Agents often need both. A schema can say a field is optional, while an example can show the common shape, nested objects, enum values, and realistic error payloads.

Good agent tool preparation records the operation ID, request schema, response schema, named examples, example provenance, and whether the sample validates against the current schema. Agents should not copy example secrets, placeholder IDs, or environment-specific URLs into real requests.

## Source-Mapped Facts

- OpenAPI 3.1.1 defines an Example Object that can include a summary, description, value, or externalValue. ([source](https://spec.openapis.org/oas/v3.1.1.html))
- OpenAPI 3.1.1 says example and examples fields are mutually exclusive in a Media Type Object. ([source](https://spec.openapis.org/oas/v3.1.1.html))
- JSON Schema documentation describes examples as an annotation keyword that provides sample JSON values associated with a schema. ([source](https://json-schema.org/understanding-json-schema/reference/annotations))

## Further Reading

- [OpenAPI Specification 3.1.1](https://spec.openapis.org/oas/v3.1.1.html)
- [JSON Schema Annotations](https://json-schema.org/understanding-json-schema/reference/annotations)