# API OpenAPI Discriminators and Polymorphic Schemas
Status: public
Confidence: medium (0.825) (verified)
Last verified: 2026-06-03
Generation: ai_structured


## TL;DR

OpenAPI discriminators help agents choose the correct schema variant when requests or responses are polymorphic.

## Core Explanation

API tools often return objects that share common fields but differ by type, such as webhook events, payment methods, identity principals, or job states. A discriminator tells consumers which field selects the concrete schema branch.

Agents should inspect the discriminator property, schema mapping, oneOf or anyOf variants, required fields, and examples before generating arguments. If the discriminator value is missing or unknown, the agent should avoid inventing a variant and should fall back to schema validation or clarification.

## Source-Mapped Facts

- The OpenAPI Specification defines the Discriminator Object as adding support for polymorphism. ([source](https://spec.openapis.org/oas/v3.1.1.html))
- The OpenAPI Discriminator Object has a required propertyName field and an optional mapping field. ([source](https://spec.openapis.org/oas/v3.1.1.html))
- Redocly documentation describes discriminator use with oneOf or anyOf when an API can return multiple object types. ([source](https://redocly.com/learn/openapi/discriminator))

## Further Reading

- [OpenAPI Specification 3.1.1](https://spec.openapis.org/oas/v3.1.1.html)
- [Redocly OpenAPI Discriminator](https://redocly.com/learn/openapi/discriminator)