Mark OpenAPI schema enum value as deprecated

Question

Is there a possibility to mark specific enum values as deprecated in OpenAPI defintion?

For example, how can I mark Value1 as deprecated?

type: string
title: CustomEnum
enum:
  - Value1
  - Value2

Answer 1

The general answer is no if you're using OAS 3.0.x because it's limited to the use of JSON Schema draft-04 superset and subset.

If you're using OAS 3.1.x, you have the full capability to use JSON Schema and deprecated was introduced in JSON Schema 2019-09. Thus, you can refactor your enum with the following:

oneOf or anyOf in this situation can be equally substituted.

oneOf/anyOf:
  - const: 'red'
  - const: 'green',
    description: green is deprecated, use red or blue
    deprecated: true
  - const: 'blue'

OR

oneOf/anyOf:
  - enum:
      - red
      - blue
  - enum:
      - green
        description: this is deprecated
        deprecated: true

If you're using any type of code generation, either of these will probably be a breaking change because you no longer have the enum defined at the top level of this property. Now it's a union type and your code generator may have some difficulty with that.

It's important to know the deprecated keyword is merely an annotation and does not prevent successful validation. This keyword indicates that applications should refrain from using the declared property.

src: https://json-schema.org/understanding-json-schema/reference/annotations