From bbb20ca46ebbd96850d20c83b9461195991637cb Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 15 May 2025 17:30:12 -0700 Subject: [PATCH 1/2] Define a policy for deprecation markings. We already deprecate `example` in the Schema Object, but do not define what deprecations means. We also effectively deprecate `allowEmptyValue` in the Parameter Object but did not explictly say so. We will likely make other deprecations in the future. This defines a very basic deprecaton policy (they are still supported, but we reserve the right to define a policy for removing them in the future) and marks `allowEmptyValue` with the same formatting used for `example`. --- src/oas.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 9151acac30..37c306e351 100644 --- a/src/oas.md +++ b/src/oas.md @@ -149,6 +149,14 @@ The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versionin Occasionally, non-backwards compatible changes may be made in `minor` versions of the OAS where impact is believed to be low relative to the benefit provided. +#### Deprecation + +Certain fields or features may be marked **Deprecated**. +These fields and features remain part of the specification and can be used like any other field or feature. +However, OpenAPI Description authors should use newer fields and features documented to replace the deprecated ones whenever possible. + +At this time, such elements are expected to remain part of the OAS until the next major version, although a future minor version of this specification may define a policy for later removal of deprecated elements. + ### Format An OpenAPI Document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in [[RFC8259|JSON]] or [[YAML|YAML]] format. @@ -926,7 +934,7 @@ These fields MAY be used with either `content` or `schema`. | description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | | required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameter-in) is `"path"`, this field is **REQUIRED** and its value MUST be `true`. Otherwise, the field MAY be included and its default value is `false`. | | deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`. | -| allowEmptyValue | `boolean` | If `true`, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted entirely, which the server SHOULD interpret as the parameter being unused. Default value is `false`. If [`style`](#parameter-style) is used, and if [behavior is _n/a_ (cannot be serialized)](#style-examples), the value of `allowEmptyValue` SHALL be ignored. Interactions between this field and the parameter's [Schema Object](#schema-object) are implementation-defined. This field is valid only for `query` parameters. Use of this field is NOT RECOMMENDED, and it is likely to be removed in a later revision. | +| allowEmptyValue | `boolean` | If `true`, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted entirely, which the server SHOULD interpret as the parameter being unused. Default value is `false`. If [`style`](#parameter-style) is used, and if [behavior is _n/a_ (cannot be serialized)](#style-examples), the value of `allowEmptyValue` SHALL be ignored. Interactions between this field and the parameter's [Schema Object](#schema-object) are implementation-defined. This field is valid only for `query` parameters.

**Deprecated:** Use of this field is NOT RECOMMENDED, and it is likely to be removed in a later revision. | This object MAY be extended with [Specification Extensions](#specification-extensions). From 6571fb31830446b112735076fe618b073b660c8b Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 16 May 2025 10:16:52 -0700 Subject: [PATCH 2/2] Fix Deprecation heading level --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 37c306e351..3e3fd8bf39 100644 --- a/src/oas.md +++ b/src/oas.md @@ -149,7 +149,7 @@ The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versionin Occasionally, non-backwards compatible changes may be made in `minor` versions of the OAS where impact is believed to be low relative to the benefit provided. -#### Deprecation +### Deprecation Certain fields or features may be marked **Deprecated**. These fields and features remain part of the specification and can be used like any other field or feature.