From c7cc6d26ba60344e6c49d0c780d141135d585a26 Mon Sep 17 00:00:00 2001 From: Andrew Tatomyr Date: Mon, 2 Nov 2026 20:40:01 +0200 Subject: [PATCH 1/7] fix: accept the description field of a Media Type Object in OpenAPI 3.2 --- .changeset/oas32-media-type-description.md | 6 + packages/core/src/types/oas3_2.ts | 5 + tests/e2e/lint/oas3.2/openapi.yaml | 1 + tests/e2e/lint/oas3.2/snapshot.txt | 132 ++++++++++----------- 4 files changed, 78 insertions(+), 66 deletions(-) create mode 100644 .changeset/oas32-media-type-description.md diff --git a/.changeset/oas32-media-type-description.md b/.changeset/oas32-media-type-description.md new file mode 100644 index 0000000000..b8141798bb --- /dev/null +++ b/.changeset/oas32-media-type-description.md @@ -0,0 +1,6 @@ +--- +'@redocly/openapi-core': patch +'@redocly/cli': patch +--- + +Added the `description` field of the Media Type Object, which OpenAPI 3.2.1 defines, so that `lint` no longer reports it in OpenAPI 3.2 descriptions. diff --git a/packages/core/src/types/oas3_2.ts b/packages/core/src/types/oas3_2.ts index 33ebe6d0e4..62950312f3 100755 --- a/packages/core/src/types/oas3_2.ts +++ b/packages/core/src/types/oas3_2.ts @@ -231,6 +231,11 @@ const MediaType: NodeType = { ...Oas3_1Types.MediaType, properties: { ...Oas3_1Types.MediaType.properties, + description: { + type: 'string', + description: + 'An optional description for the media type. CommonMark syntax MAY be used for rich text representation.', + }, itemSchema: 'Schema', prefixEncoding: listOf('Encoding', { description: diff --git a/tests/e2e/lint/oas3.2/openapi.yaml b/tests/e2e/lint/oas3.2/openapi.yaml index c477ba2907..2ff48e3e70 100644 --- a/tests/e2e/lint/oas3.2/openapi.yaml +++ b/tests/e2e/lint/oas3.2/openapi.yaml @@ -53,6 +53,7 @@ paths: required: true content: application/json: + description: Should allow a description in a Media Type Object (OpenAPI 3.2.1) schema: type: object properties: diff --git a/tests/e2e/lint/oas3.2/snapshot.txt b/tests/e2e/lint/oas3.2/snapshot.txt index 5ac8b8d07a..eae161b255 100644 --- a/tests/e2e/lint/oas3.2/snapshot.txt +++ b/tests/e2e/lint/oas3.2/snapshot.txt @@ -102,44 +102,44 @@ Property `wrong` is not expected here. Error was generated by the struct rule. -[8] openapi.yaml:156:9 at #/components/schemas/MyResponseType/discriminator/wrong +[8] openapi.yaml:157:9 at #/components/schemas/MyResponseType/discriminator/wrong Property `wrong` is not expected here. -154 | propertyName: petType -155 | defaultMapping: OtherPet # Should be allowed -156 | wrong: Should catch a wrong field in discriminator! +155 | propertyName: petType +156 | defaultMapping: OtherPet # Should be allowed +157 | wrong: Should catch a wrong field in discriminator! | ^^^^^ -157 | Lizard: -158 | type: object +158 | Lizard: +159 | type: object Error was generated by the struct rule. -[9] openapi.yaml:132:11 at #/components/securitySchemes/petstore_auth/flows/implicit/wrong +[9] openapi.yaml:133:11 at #/components/securitySchemes/petstore_auth/flows/implicit/wrong Property `wrong` is not expected here. -130 | implicit: -131 | authorizationUrl: https://example.org/api/oauth/dialog -132 | wrong: Should catch wrong prop in oauth2 flows! +131 | implicit: +132 | authorizationUrl: https://example.org/api/oauth/dialog +133 | wrong: Should catch wrong prop in oauth2 flows! | ^^^^^ -133 | scopes: -134 | write:pets: modify pets in your account +134 | scopes: +135 | write:pets: modify pets in your account Error was generated by the struct rule. -[10] openapi.yaml:144:9 at #/components/securitySchemes/device_auth/flows/deviceAuthorization +[10] openapi.yaml:145:9 at #/components/securitySchemes/device_auth/flows/deviceAuthorization The field `scopes` must be present on this level. -142 | type: oauth2 -143 | flows: -144 | deviceAuthorization: +143 | type: oauth2 +144 | flows: +145 | deviceAuthorization: | ^^^^^^^^^^^^^^^^^^^ -145 | # scopes: Scopes are required in deviceAuthorization! -146 | deviceAuthorizationUrl: http://localhost +146 | # scopes: Scopes are required in deviceAuthorization! +147 | deviceAuthorizationUrl: http://localhost Error was generated by the struct rule. @@ -207,16 +207,16 @@ Warning was generated by the operation-operationId rule. Reference: https://redocly.com/docs/cli/rules/oas/operation-operationId -[15] openapi.yaml:65:7 at #/paths/~1products/query/responses +[15] openapi.yaml:66:7 at #/paths/~1products/query/responses Operation must have at least one `4XX` response. -63 | items: -64 | type: string -65 | responses: +64 | items: +65 | type: string +66 | responses: | ^^^^^^^^^ -66 | '200': -67 | description: Search results +67 | '200': +68 | description: Search results Warning was generated by the operation-4xx-response rule. @@ -239,112 +239,112 @@ Warning was generated by the operation-operationId rule. Reference: https://redocly.com/docs/cli/rules/oas/operation-operationId -[17] openapi.yaml:70:5 at #/paths/~1stream/get/operationId +[17] openapi.yaml:71:5 at #/paths/~1stream/get/operationId Operation object should contain `operationId` field. -68 | summary: Should allow summary in responses -69 | /stream: -70 | get: +69 | summary: Should allow summary in responses +70 | /stream: +71 | get: | ^^^ -71 | summary: Stream -72 | responses: +72 | summary: Stream +73 | responses: Warning was generated by the operation-operationId rule. Reference: https://redocly.com/docs/cli/rules/oas/operation-operationId -[18] openapi.yaml:72:7 at #/paths/~1stream/get/responses +[18] openapi.yaml:73:7 at #/paths/~1stream/get/responses Operation must have at least one `4XX` response. -70 | get: -71 | summary: Stream -72 | responses: +71 | get: +72 | summary: Stream +73 | responses: | ^^^^^^^^^ -73 | 200: -74 | description: Stream of updates +74 | 200: +75 | description: Stream of updates Warning was generated by the operation-4xx-response rule. Reference: https://redocly.com/docs/cli/rules/oas/operation-4xx-response -[19] openapi.yaml:83:5 at #/paths/~1thing/get/operationId +[19] openapi.yaml:84:5 at #/paths/~1thing/get/operationId Operation object should contain `operationId` field. -81 | data: { type: object } -82 | /thing: -83 | get: +82 | data: { type: object } +83 | /thing: +84 | get: | ^^^ -84 | summary: a sample api -85 | responses: +85 | summary: a sample api +86 | responses: Warning was generated by the operation-operationId rule. Reference: https://redocly.com/docs/cli/rules/oas/operation-operationId -[20] openapi.yaml:85:7 at #/paths/~1thing/get/responses +[20] openapi.yaml:86:7 at #/paths/~1thing/get/responses Operation must have at least one `4XX` response. -83 | get: -84 | summary: a sample api -85 | responses: +84 | get: +85 | summary: a sample api +86 | responses: | ^^^^^^^^^ -86 | '200': -87 | description: OK +87 | '200': +88 | description: OK Warning was generated by the operation-4xx-response rule. Reference: https://redocly.com/docs/cli/rules/oas/operation-4xx-response -[21] openapi.yaml:149:5 at #/components/schemas/MyResponseType +[21] openapi.yaml:150:5 at #/components/schemas/MyResponseType Component: "MyResponseType" is never used. -147 | tokenUrl: http://localhost -148 | schemas: -149 | MyResponseType: +148 | tokenUrl: http://localhost +149 | schemas: +150 | MyResponseType: | ^^^^^^^^^^^^^^ -150 | oneOf: -151 | - $ref: '#/components/schemas/Lizard' +151 | oneOf: +152 | - $ref: '#/components/schemas/Lizard' Warning was generated by the no-unused-components rule. Reference: https://redocly.com/docs/cli/rules/oas/no-unused-components -[22] openapi.yaml:125:5 at #/components/securitySchemes/petstore_auth +[22] openapi.yaml:126:5 at #/components/securitySchemes/petstore_auth Security scheme: "petstore_auth" is never used. -123 | components: -124 | securitySchemes: -125 | petstore_auth: +124 | components: +125 | securitySchemes: +126 | petstore_auth: | ^^^^^^^^^^^^^ -126 | type: oauth2 -127 | deprecated: true # Should allow deprecation +127 | type: oauth2 +128 | deprecated: true # Should allow deprecation Warning was generated by the no-unused-components rule. Reference: https://redocly.com/docs/cli/rules/oas/no-unused-components -[23] openapi.yaml:136:5 at #/components/securitySchemes/api_key +[23] openapi.yaml:137:5 at #/components/securitySchemes/api_key Security scheme: "api_key" is never used. -134 | write:pets: modify pets in your account -135 | read:pets: read your pets -136 | api_key: +135 | write:pets: modify pets in your account +136 | read:pets: read your pets +137 | api_key: | ^^^^^^^ -137 | type: apiKey -138 | in: header +138 | type: apiKey +139 | in: header Warning was generated by the no-unused-components rule. From 4dc6fe4b7f1f167df205dee791da08955edec4ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jacek=20=C5=81=C4=99kawa?= <164185257+JLekawa@users.noreply.github.com> Date: Wed, 4 Nov 2026 11:47:47 +0100 Subject: [PATCH 2/7] Apply suggestion from @JLekawa --- .changeset/oas32-media-type-description.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.changeset/oas32-media-type-description.md b/.changeset/oas32-media-type-description.md index b8141798bb..5bd1cc8d81 100644 --- a/.changeset/oas32-media-type-description.md +++ b/.changeset/oas32-media-type-description.md @@ -3,4 +3,5 @@ '@redocly/cli': patch --- -Added the `description` field of the Media Type Object, which OpenAPI 3.2.1 defines, so that `lint` no longer reports it in OpenAPI 3.2 descriptions. +Added support for the `description` field of the Media Type Object, defined in OpenAPI 3.2.1. +The `lint` command no longer reports it as an error in OpenAPI 3.2 descriptions. From ebe394cfa0740e3d57f6f67a1e7af6ab9f968181 Mon Sep 17 00:00:00 2001 From: Andrew Tatomyr Date: Wed, 4 Nov 2026 20:43:38 +0200 Subject: [PATCH 3/7] chore: say that the Media Type Object description comes with the next OpenAPI 3.2 patch release --- .changeset/oas32-media-type-description.md | 2 +- tests/e2e/lint/oas3.2/openapi.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.changeset/oas32-media-type-description.md b/.changeset/oas32-media-type-description.md index 5bd1cc8d81..062fa787c3 100644 --- a/.changeset/oas32-media-type-description.md +++ b/.changeset/oas32-media-type-description.md @@ -3,5 +3,5 @@ '@redocly/cli': patch --- -Added support for the `description` field of the Media Type Object, defined in OpenAPI 3.2.1. +Added support for the `description` field of the Media Type Object, which the next patch release of OpenAPI 3.2 adds. The `lint` command no longer reports it as an error in OpenAPI 3.2 descriptions. diff --git a/tests/e2e/lint/oas3.2/openapi.yaml b/tests/e2e/lint/oas3.2/openapi.yaml index 2ff48e3e70..9b6aebab6e 100644 --- a/tests/e2e/lint/oas3.2/openapi.yaml +++ b/tests/e2e/lint/oas3.2/openapi.yaml @@ -53,7 +53,7 @@ paths: required: true content: application/json: - description: Should allow a description in a Media Type Object (OpenAPI 3.2.1) + description: Should allow a description in a Media Type Object (next OpenAPI 3.2 patch release) schema: type: object properties: From dfb4438515c0943a440c4e780b97a5c01e65af82 Mon Sep 17 00:00:00 2001 From: Andrew Tatomyr Date: Wed, 4 Nov 2026 20:45:07 +0200 Subject: [PATCH 4/7] chore: name the specification pull request that adds the Media Type Object description --- .changeset/oas32-media-type-description.md | 2 +- tests/e2e/lint/oas3.2/openapi.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.changeset/oas32-media-type-description.md b/.changeset/oas32-media-type-description.md index 062fa787c3..ed04f78e7a 100644 --- a/.changeset/oas32-media-type-description.md +++ b/.changeset/oas32-media-type-description.md @@ -3,5 +3,5 @@ '@redocly/cli': patch --- -Added support for the `description` field of the Media Type Object, which the next patch release of OpenAPI 3.2 adds. +Added support for the `description` field of the Media Type Object, which OpenAPI 3.2 adds in https://github.com/OAI/OpenAPI-Specification/pull/5584. The `lint` command no longer reports it as an error in OpenAPI 3.2 descriptions. diff --git a/tests/e2e/lint/oas3.2/openapi.yaml b/tests/e2e/lint/oas3.2/openapi.yaml index 9b6aebab6e..33e4b66b95 100644 --- a/tests/e2e/lint/oas3.2/openapi.yaml +++ b/tests/e2e/lint/oas3.2/openapi.yaml @@ -53,7 +53,7 @@ paths: required: true content: application/json: - description: Should allow a description in a Media Type Object (next OpenAPI 3.2 patch release) + description: Should allow a description in a Media Type Object (OAI/OpenAPI-Specification#5584) schema: type: object properties: From 9b84d9b35bf9d1e689ba6df66263c108e5389c91 Mon Sep 17 00:00:00 2001 From: Andrew Tatomyr Date: Wed, 4 Nov 2026 20:53:00 +0200 Subject: [PATCH 5/7] chore: name OpenAPI 3.2 for the Media Type Object description --- .changeset/oas32-media-type-description.md | 2 +- tests/e2e/lint/oas3.2/openapi.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.changeset/oas32-media-type-description.md b/.changeset/oas32-media-type-description.md index ed04f78e7a..0e2a446e3c 100644 --- a/.changeset/oas32-media-type-description.md +++ b/.changeset/oas32-media-type-description.md @@ -3,5 +3,5 @@ '@redocly/cli': patch --- -Added support for the `description` field of the Media Type Object, which OpenAPI 3.2 adds in https://github.com/OAI/OpenAPI-Specification/pull/5584. +Added support for the `description` field of the Media Type Object in OpenAPI 3.2. The `lint` command no longer reports it as an error in OpenAPI 3.2 descriptions. diff --git a/tests/e2e/lint/oas3.2/openapi.yaml b/tests/e2e/lint/oas3.2/openapi.yaml index 33e4b66b95..19745b9901 100644 --- a/tests/e2e/lint/oas3.2/openapi.yaml +++ b/tests/e2e/lint/oas3.2/openapi.yaml @@ -53,7 +53,7 @@ paths: required: true content: application/json: - description: Should allow a description in a Media Type Object (OAI/OpenAPI-Specification#5584) + description: Should allow a description in a Media Type Object (OpenAPI 3.2) schema: type: object properties: From 4ec2132b139fb5a4e848999e3db6fb149980df21 Mon Sep 17 00:00:00 2001 From: Andrew Tatomyr Date: Thu, 5 Nov 2026 11:10:47 +0200 Subject: [PATCH 6/7] chore: drop the specification text from the Media Type Object description field --- packages/core/src/types/oas3_2.ts | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/packages/core/src/types/oas3_2.ts b/packages/core/src/types/oas3_2.ts index 6e30e8fdc0..261c52529f 100755 --- a/packages/core/src/types/oas3_2.ts +++ b/packages/core/src/types/oas3_2.ts @@ -231,11 +231,7 @@ const MediaType: NodeType = { ...Oas3_1Types.MediaType, properties: { ...Oas3_1Types.MediaType.properties, - description: { - type: 'string', - description: - 'An optional description for the media type. CommonMark syntax MAY be used for rich text representation.', - }, + description: { type: 'string' }, itemSchema: 'Schema', prefixEncoding: listOf('Encoding', { description: From e59d45d25cec8b945479064bc4a703660bcfe840 Mon Sep 17 00:00:00 2001 From: Andrew Tatomyr Date: Thu, 5 Nov 2026 19:53:19 +0200 Subject: [PATCH 7/7] chore: drop the repeated sentence from the changeset --- .changeset/oas32-media-type-description.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.changeset/oas32-media-type-description.md b/.changeset/oas32-media-type-description.md index 0e2a446e3c..64a118c621 100644 --- a/.changeset/oas32-media-type-description.md +++ b/.changeset/oas32-media-type-description.md @@ -4,4 +4,3 @@ --- Added support for the `description` field of the Media Type Object in OpenAPI 3.2. -The `lint` command no longer reports it as an error in OpenAPI 3.2 descriptions.