Standardizing Idempotency Definitions in OpenAPI Specification

Defining Write-Safety for Non-Idempotent Methods

The OpenAPI Specification (OAS) provides a framework for describing API interfaces, but it lacks a dedicated keyword to explicitly mark an endpoint as idempotent. While PUT and DELETE are inherently idempotent per RFC 7231, POST requests often require custom logic—such as the use of an Idempotency-Key header—to prevent duplicate writes during client-side retries.

Currently, developers must document these requirements within the parameters or description fields. This approach relies on manual documentation rather than a machine-readable attribute that a gateway or client library could use to automate retry safety.

Which standard approach is recommended for defining idempotency constraints in OAS to ensure consistent behavior across different toolsets? Does the specification allow for a custom extension to formally signal that a POST endpoint supports idempotent retries?