From 701d460b15c99a26f3646f4a0323fd40e0c73bb4 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 28 Mar 2025 08:54:34 -0400 Subject: [PATCH 01/26] feat: adds additional operations for path item object Signed-off-by: Vincent Biret --- src/oas.md | 55 +++++++++++++++++++++++++++++- src/schemas/validation/schema.yaml | 22 ++++++++++++ 2 files changed, 76 insertions(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 5d56bed793..6afe86b2a0 100644 --- a/src/oas.md +++ b/src/oas.md @@ -924,6 +924,7 @@ The path itself is still exposed to the documentation viewer but they will not k | $ref | `string` | Allows for a referenced definition of this path item. The value MUST be in the form of a URI, and the referenced structure MUST be in the form of a [Path Item Object](#path-item-object). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](#relative-references-in-api-description-uris).

_**Note:** The behavior of `$ref` with adjacent properties is likely to change in future versions of this specification to bring it into closer alignment with the behavior of the [Reference Object](#reference-object)._ | | summary | `string` | An optional string summary, intended to apply to all operations in this path. | | description | `string` | An optional string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | +| additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. This map MUST NOT contain any entry matching (case-insensitive) any operation that can be defined on the parent path item object. | | get | [Operation Object](#operation-object) | A definition of a GET operation on this path. | | put | [Operation Object](#operation-object) | A definition of a PUT operation on this path. | | post | [Operation Object](#operation-object) | A definition of a POST operation on this path. | @@ -985,7 +986,39 @@ This object MAY be extended with [Specification Extensions](#specification-exten }, "style": "simple" } - ] + ], + "additionalOperations": { + "query": { + "description": "Returns pets based on ID", + "summary": "Find pets by ID", + "operationId": "queryPetsById", + "responses": { + "200": { + "description": "pet response", + "content": { + "*/*": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Pet" + } + } + } + } + }, + "default": { + "description": "error payload", + "content": { + "text/html": { + "schema": { + "$ref": "#/components/schemas/ErrorModel" + } + } + } + } + } + } + } } ``` @@ -1019,6 +1052,26 @@ parameters: items: type: string style: simple +additionalOperations: + query: + description: Returns pets based on ID + summary: Find pets by ID + operationId: queryPetsById + responses: + '200': + description: pet response + content: + '*/*': + schema: + type: array + items: + $ref: '#/components/schemas/Pet' + default: + description: error payload + content: + text/html: + schema: + $ref: '#/components/schemas/ErrorModel' ``` #### Operation Object diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 8d14aec869..666e9314d6 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -230,6 +230,28 @@ $defs: type: array items: $ref: '#/$defs/parameter-or-reference' + additionalOperations: + type: object + additionalProperties: + $ref: '#/$defs/operation' + not: + required: + - get: + $ref: '#/$defs/operation' + - put: + $ref: '#/$defs/operation' + - post: + $ref: '#/$defs/operation' + - delete: + $ref: '#/$defs/operation' + - options: + $ref: '#/$defs/operation' + - head: + $ref: '#/$defs/operation' + - patch: + $ref: '#/$defs/operation' + - trace: + $ref: '#/$defs/operation' get: $ref: '#/$defs/operation' put: From 524cc6f44cbdb1829ed0766800720537b462a1f8 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 28 Mar 2025 08:58:31 -0400 Subject: [PATCH 02/26] chore: adds test data for additional operations Signed-off-by: Vincent Biret --- .../schema/pass/path-item-object-example.yaml | 22 ++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/tests/schema/pass/path-item-object-example.yaml b/tests/schema/pass/path-item-object-example.yaml index 234325e21a..bede844d36 100644 --- a/tests/schema/pass/path-item-object-example.yaml +++ b/tests/schema/pass/path-item-object-example.yaml @@ -32,4 +32,24 @@ paths: type: array items: type: string - style: simple \ No newline at end of file + style: simple + additionalOperations: + query: + description: Returns pets based on ID + summary: Find pets by ID + operationId: queryPetsById + responses: + '200': + description: pet response + content: + '*/*': + schema: + type: array + items: + $ref: '#/components/schemas/Pet' + default: + description: error payload + content: + text/html: + schema: + $ref: '#/components/schemas/ErrorModel' \ No newline at end of file From b12f34b9560e3cdddf1932f84366b773e356d676 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 28 Mar 2025 09:03:13 -0400 Subject: [PATCH 03/26] fix: schema definition for outlawed properties Signed-off-by: Vincent Biret --- src/schemas/validation/schema.yaml | 42 ++++++++++++++++++------------ 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 666e9314d6..9e30443426 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -235,23 +235,31 @@ $defs: additionalProperties: $ref: '#/$defs/operation' not: - required: - - get: - $ref: '#/$defs/operation' - - put: - $ref: '#/$defs/operation' - - post: - $ref: '#/$defs/operation' - - delete: - $ref: '#/$defs/operation' - - options: - $ref: '#/$defs/operation' - - head: - $ref: '#/$defs/operation' - - patch: - $ref: '#/$defs/operation' - - trace: - $ref: '#/$defs/operation' + anyOf: + - properties: + - get: + $ref: '#/$defs/operation' + - properties: + - put: + $ref: '#/$defs/operation' + - properties: + - post: + $ref: '#/$defs/operation' + - properties: + - delete: + $ref: '#/$defs/operation' + - properties: + - options: + $ref: '#/$defs/operation' + - properties: + - head: + $ref: '#/$defs/operation' + - properties: + - patch: + $ref: '#/$defs/operation' + - properties: + - trace: + $ref: '#/$defs/operation' get: $ref: '#/$defs/operation' put: From 692b41315b553d268e5323f3ecd1e92fabe050c7 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 28 Mar 2025 09:05:23 -0400 Subject: [PATCH 04/26] fix: schema indentation and adds required keyword Signed-off-by: Vincent Biret --- src/schemas/validation/schema.yaml | 32 ++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 9e30443426..17351fd7de 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -238,28 +238,44 @@ $defs: anyOf: - properties: - get: - $ref: '#/$defs/operation' + $ref: '#/$defs/operation' + required: + - get - properties: - put: - $ref: '#/$defs/operation' + $ref: '#/$defs/operation' + required: + - put - properties: - post: - $ref: '#/$defs/operation' + $ref: '#/$defs/operation' + required: + - post - properties: - delete: - $ref: '#/$defs/operation' + $ref: '#/$defs/operation' + required: + - delete - properties: - options: - $ref: '#/$defs/operation' + $ref: '#/$defs/operation' + required: + - options - properties: - head: - $ref: '#/$defs/operation' + $ref: '#/$defs/operation' + required: + - head - properties: - patch: - $ref: '#/$defs/operation' + $ref: '#/$defs/operation' + required: + - patch - properties: - trace: - $ref: '#/$defs/operation' + $ref: '#/$defs/operation' + required: + - trace get: $ref: '#/$defs/operation' put: From 62dbf31569f224c917723d4e037fb4f6b525085e Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 28 Mar 2025 09:14:13 -0400 Subject: [PATCH 05/26] =?UTF-8?q?fix:=20=F0=9F=A4=A6=20vincent=20needs=20a?= =?UTF-8?q?=20coffee?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Vincent Biret --- src/schemas/validation/schema.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 17351fd7de..ed43a01f47 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -237,42 +237,42 @@ $defs: not: anyOf: - properties: - - get: + get: $ref: '#/$defs/operation' required: - get - properties: - - put: + put: $ref: '#/$defs/operation' required: - put - properties: - - post: + post: $ref: '#/$defs/operation' required: - post - properties: - - delete: + delete: $ref: '#/$defs/operation' required: - delete - properties: - - options: + options: $ref: '#/$defs/operation' required: - options - properties: - - head: + head: $ref: '#/$defs/operation' required: - head - properties: - - patch: + patch: $ref: '#/$defs/operation' required: - patch - properties: - - trace: + trace: $ref: '#/$defs/operation' required: - trace From 15e99caedf193dd1a0a91590a7c54cf655bc0ec9 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 28 Mar 2025 10:21:01 -0400 Subject: [PATCH 06/26] Apply suggestions from code review Co-authored-by: Ralf Handl --- src/oas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index 6afe86b2a0..e5291fbf9b 100644 --- a/src/oas.md +++ b/src/oas.md @@ -988,7 +988,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten } ], "additionalOperations": { - "query": { + "QUERY": { "description": "Returns pets based on ID", "summary": "Find pets by ID", "operationId": "queryPetsById", @@ -1053,7 +1053,7 @@ parameters: type: string style: simple additionalOperations: - query: + QUERY: description: Returns pets based on ID summary: Find pets by ID operationId: queryPetsById From 72a29d74c2d33f279e2a0661ef1b747a923d32e2 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 28 Mar 2025 10:21:17 -0400 Subject: [PATCH 07/26] Update tests/schema/pass/path-item-object-example.yaml Co-authored-by: Ralf Handl --- tests/schema/pass/path-item-object-example.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/schema/pass/path-item-object-example.yaml b/tests/schema/pass/path-item-object-example.yaml index bede844d36..46f7826c16 100644 --- a/tests/schema/pass/path-item-object-example.yaml +++ b/tests/schema/pass/path-item-object-example.yaml @@ -34,7 +34,7 @@ paths: type: string style: simple additionalOperations: - query: + QUERY: description: Returns pets based on ID summary: Find pets by ID operationId: queryPetsById From 2452ad17b03932560309bb53b4625e8a89163ddc Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 28 Mar 2025 10:22:25 -0400 Subject: [PATCH 08/26] chore: moves additional operations after the defined operations Signed-off-by: Vincent Biret --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index e5291fbf9b..8d91bbb1ec 100644 --- a/src/oas.md +++ b/src/oas.md @@ -924,7 +924,6 @@ The path itself is still exposed to the documentation viewer but they will not k | $ref | `string` | Allows for a referenced definition of this path item. The value MUST be in the form of a URI, and the referenced structure MUST be in the form of a [Path Item Object](#path-item-object). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](#relative-references-in-api-description-uris).

_**Note:** The behavior of `$ref` with adjacent properties is likely to change in future versions of this specification to bring it into closer alignment with the behavior of the [Reference Object](#reference-object)._ | | summary | `string` | An optional string summary, intended to apply to all operations in this path. | | description | `string` | An optional string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. | -| additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. This map MUST NOT contain any entry matching (case-insensitive) any operation that can be defined on the parent path item object. | | get | [Operation Object](#operation-object) | A definition of a GET operation on this path. | | put | [Operation Object](#operation-object) | A definition of a PUT operation on this path. | | post | [Operation Object](#operation-object) | A definition of a POST operation on this path. | @@ -933,6 +932,7 @@ The path itself is still exposed to the documentation viewer but they will not k | head | [Operation Object](#operation-object) | A definition of a HEAD operation on this path. | | patch | [Operation Object](#operation-object) | A definition of a PATCH operation on this path. | | trace | [Operation Object](#operation-object) | A definition of a TRACE operation on this path. | +| additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. This map MUST NOT contain any entry matching (case-insensitive) any operation that can be defined on the parent path item object. | | servers | [[Server Object](#server-object)] | An alternative `servers` array to service all operations in this path. If a `servers` array is specified at the [OpenAPI Object](#oas-servers) level, it will be overridden by this value. | | parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). | From 4cf516815a3f92be7e8154954a3a83ce32331241 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 28 Mar 2025 10:24:40 -0400 Subject: [PATCH 09/26] ci: adds a failing test for methods that should be defined on the parent object Signed-off-by: Vincent Biret --- .../schema/fail/path-item-object-example.yaml | 64 +++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 tests/schema/fail/path-item-object-example.yaml diff --git a/tests/schema/fail/path-item-object-example.yaml b/tests/schema/fail/path-item-object-example.yaml new file mode 100644 index 0000000000..a00db6c5f6 --- /dev/null +++ b/tests/schema/fail/path-item-object-example.yaml @@ -0,0 +1,64 @@ +openapi: 3.2.0 +info: + title: API + version: 1.0.0 +paths: + /pets/{id}: + get: + description: Returns pets based on ID + summary: Find pets by ID + operationId: getPetsById + responses: + '200': + description: pet response + content: + '*/*': + schema: + type: array + items: + $ref: '#/components/schemas/Pet' + default: + description: error payload + content: + text/html: + schema: + $ref: '#/components/schemas/ErrorModel' + parameters: + - name: id + in: path + description: ID of pet to use + required: true + schema: + type: array + items: + type: string + style: simple + additionalOperations: + POST: + description: Returns pets based on ID + summary: Find pets by ID + operationId: postPetsById + request-body: + description: ID of pet to use + required: true + content: + application/json: + schema: + type: array + items: + type: string + responses: + '200': + description: pet response + content: + '*/*': + schema: + type: array + items: + $ref: '#/components/schemas/Pet' + default: + description: error payload + content: + text/html: + schema: + $ref: '#/components/schemas/ErrorModel' \ No newline at end of file From cfdc4bc6a5a2235dd8d7c7b3662e16870a881d75 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 28 Mar 2025 12:00:43 -0400 Subject: [PATCH 10/26] Update tests/schema/fail/path-item-object-example.yaml Co-authored-by: Ralf Handl --- tests/schema/fail/path-item-object-example.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/schema/fail/path-item-object-example.yaml b/tests/schema/fail/path-item-object-example.yaml index a00db6c5f6..f068406b68 100644 --- a/tests/schema/fail/path-item-object-example.yaml +++ b/tests/schema/fail/path-item-object-example.yaml @@ -38,7 +38,7 @@ paths: description: Returns pets based on ID summary: Find pets by ID operationId: postPetsById - request-body: + requestBody: description: ID of pet to use required: true content: From d5141ec04cb653cf932c02f0cf99bde90afe14ac Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 09:03:07 -0400 Subject: [PATCH 11/26] chore: renames fail file to have more explicit definition of the case Signed-off-by: Vincent Biret --- ...aml => path-item-object-conflicting-additional-operation.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename tests/schema/fail/{path-item-object-example.yaml => path-item-object-conflicting-additional-operation.yaml} (100%) diff --git a/tests/schema/fail/path-item-object-example.yaml b/tests/schema/fail/path-item-object-conflicting-additional-operation.yaml similarity index 100% rename from tests/schema/fail/path-item-object-example.yaml rename to tests/schema/fail/path-item-object-conflicting-additional-operation.yaml From 6ed7fe87fa704093b4d008d5b1628d27a26c2ed7 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 09:04:21 -0400 Subject: [PATCH 12/26] feat: adds query as "principal" operation type in path item Signed-off-by: Vincent Biret --- src/schemas/validation/schema.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index ed43a01f47..a3230d8193 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -292,6 +292,8 @@ $defs: $ref: '#/$defs/operation' trace: $ref: '#/$defs/operation' + query: + $ref: '#/$defs/operation' $ref: '#/$defs/specification-extensions' unevaluatedProperties: false From 61fee049b6194b7d039fa9da158f15d9842c1ae2 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 09:09:44 -0400 Subject: [PATCH 13/26] fix: excluded operations filter for additional operations Signed-off-by: Vincent Biret --- src/schemas/validation/schema.yaml | 54 +++++++----------------------- 1 file changed, 12 insertions(+), 42 deletions(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index a3230d8193..4225253b63 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -234,48 +234,18 @@ $defs: type: object additionalProperties: $ref: '#/$defs/operation' - not: - anyOf: - - properties: - get: - $ref: '#/$defs/operation' - required: - - get - - properties: - put: - $ref: '#/$defs/operation' - required: - - put - - properties: - post: - $ref: '#/$defs/operation' - required: - - post - - properties: - delete: - $ref: '#/$defs/operation' - required: - - delete - - properties: - options: - $ref: '#/$defs/operation' - required: - - options - - properties: - head: - $ref: '#/$defs/operation' - required: - - head - - properties: - patch: - $ref: '#/$defs/operation' - required: - - patch - - properties: - trace: - $ref: '#/$defs/operation' - required: - - trace + propertyNames: + not: + enum: + - GET + - PUT + - POST + - DELETE + - OPTIONS + - HEAD + - PATCH + - TRACE + - QUERY get: $ref: '#/$defs/operation' put: From d3c477cffcf516cf990664c53c799178cadfa60c Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 09:12:32 -0400 Subject: [PATCH 14/26] docs: updates wording for additional operations exclusions Co-authored-by: Henry Andrews --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 8d91bbb1ec..b40e9aaad3 100644 --- a/src/oas.md +++ b/src/oas.md @@ -932,7 +932,7 @@ The path itself is still exposed to the documentation viewer but they will not k | head | [Operation Object](#operation-object) | A definition of a HEAD operation on this path. | | patch | [Operation Object](#operation-object) | A definition of a PATCH operation on this path. | | trace | [Operation Object](#operation-object) | A definition of a TRACE operation on this path. | -| additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. This map MUST NOT contain any entry matching (case-insensitive) any operation that can be defined on the parent path item object. | +| additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. This map MUST NOT contain any entry for the methods that can be defined by other Operation Object fields (e.g. no `POST` entry, as the Operation Object field `post` is used for this method). | | servers | [[Server Object](#server-object)] | An alternative `servers` array to service all operations in this path. If a `servers` array is specified at the [OpenAPI Object](#oas-servers) level, it will be overridden by this value. | | parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). | From 2dc3e06e0c4ce68ba55056623fb021c68908d3c1 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 09:15:03 -0400 Subject: [PATCH 15/26] docs: updates additional operation samples to match hoisting of query Signed-off-by: Vincent Biret --- src/oas.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/oas.md b/src/oas.md index 8d91bbb1ec..f1ec6922ca 100644 --- a/src/oas.md +++ b/src/oas.md @@ -988,10 +988,10 @@ This object MAY be extended with [Specification Extensions](#specification-exten } ], "additionalOperations": { - "QUERY": { - "description": "Returns pets based on ID", - "summary": "Find pets by ID", - "operationId": "queryPetsById", + "COPY": { + "description": "Copies pet information based on ID", + "summary": "Copies pets by ID", + "operationId": "copyPetsById", "responses": { "200": { "description": "pet response", @@ -1053,9 +1053,9 @@ parameters: type: string style: simple additionalOperations: - QUERY: - description: Returns pets based on ID - summary: Find pets by ID + COPY: + description: Copies pet information based on ID + summary: Copies pets by ID operationId: queryPetsById responses: '200': From 3fb4d91d34778fa8f53fcda3c2ef1b1db9e93086 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 09:16:44 -0400 Subject: [PATCH 16/26] ci: fixes pass example test Signed-off-by: Vincent Biret --- src/oas.md | 2 +- tests/schema/pass/path-item-object-example.yaml | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/oas.md b/src/oas.md index 48aab5f811..9875da3734 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1056,7 +1056,7 @@ additionalOperations: COPY: description: Copies pet information based on ID summary: Copies pets by ID - operationId: queryPetsById + operationId: copyPetsById responses: '200': description: pet response diff --git a/tests/schema/pass/path-item-object-example.yaml b/tests/schema/pass/path-item-object-example.yaml index 46f7826c16..4507e31396 100644 --- a/tests/schema/pass/path-item-object-example.yaml +++ b/tests/schema/pass/path-item-object-example.yaml @@ -34,10 +34,10 @@ paths: type: string style: simple additionalOperations: - QUERY: - description: Returns pets based on ID - summary: Find pets by ID - operationId: queryPetsById + COPY: + description: Copies pet information based on ID + summary: Copies pets by ID + operationId: copyPetsById responses: '200': description: pet response From dd0cf1688efdd8542102be4169593dcaec7e858a Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 09:26:27 -0400 Subject: [PATCH 17/26] docs: adds a query example to pass tests Signed-off-by: Vincent Biret --- .../schema/pass/path-item-object-example.yaml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/tests/schema/pass/path-item-object-example.yaml b/tests/schema/pass/path-item-object-example.yaml index 4507e31396..0ecc2d64fa 100644 --- a/tests/schema/pass/path-item-object-example.yaml +++ b/tests/schema/pass/path-item-object-example.yaml @@ -23,6 +23,25 @@ paths: text/html: schema: $ref: '#/components/schemas/ErrorModel' + query: + description: Returns pets based on ID + summary: Find pets by ID + operationId: queryPetsById + responses: + '200': + description: pet response + content: + '*/*': + schema: + type: array + items: + $ref: '#/components/schemas/Pet' + default: + description: error payload + content: + text/html: + schema: + $ref: '#/components/schemas/ErrorModel' parameters: - name: id in: path From fc29d3a3d29df4d84fe306bce7436dd3d3f69534 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 10:01:32 -0400 Subject: [PATCH 18/26] docs: precisions around capitalization Co-authored-by: Ralf Handl --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 9875da3734..387ab2ea56 100644 --- a/src/oas.md +++ b/src/oas.md @@ -932,7 +932,7 @@ The path itself is still exposed to the documentation viewer but they will not k | head | [Operation Object](#operation-object) | A definition of a HEAD operation on this path. | | patch | [Operation Object](#operation-object) | A definition of a PATCH operation on this path. | | trace | [Operation Object](#operation-object) | A definition of a TRACE operation on this path. | -| additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. This map MUST NOT contain any entry for the methods that can be defined by other Operation Object fields (e.g. no `POST` entry, as the Operation Object field `post` is used for this method). | +| additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. The map key is the HTTP method with the same capitalization that is to be sent in the request. This map MUST NOT contain any entry for the methods that can be defined by other Operation Object fields (e.g. no `POST` entry, as the Operation Object field `post` is used for this method). | | servers | [[Server Object](#server-object)] | An alternative `servers` array to service all operations in this path. If a `servers` array is specified at the [OpenAPI Object](#oas-servers) level, it will be overridden by this value. | | parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). | From 9a53a9de558440a92c3751e89243cc573f300039 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 14:08:23 -0400 Subject: [PATCH 19/26] ci: restricts to RFC9110 methods syntax Co-authored-by: Henry Andrews --- src/schemas/validation/schema.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 4225253b63..202874c292 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -235,6 +235,9 @@ $defs: additionalProperties: $ref: '#/$defs/operation' propertyNames: + $comment: RFC9110 restricts methods to "1*tchar" in ABNF + pattern: "^[a-zA-Z0-9!#$%&'*+.-]+$" + "^" / "_" / "`" / "|" / "~" not: enum: - GET From 621d1c3a003af31ebac18e79beb6e8926c1af098 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 14:09:25 -0400 Subject: [PATCH 20/26] docs: adds the query method to the spec Co-authored-by: Henry Andrews --- src/oas.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/oas.md b/src/oas.md index 387ab2ea56..eec14fc939 100644 --- a/src/oas.md +++ b/src/oas.md @@ -932,6 +932,7 @@ The path itself is still exposed to the documentation viewer but they will not k | head | [Operation Object](#operation-object) | A definition of a HEAD operation on this path. | | patch | [Operation Object](#operation-object) | A definition of a PATCH operation on this path. | | trace | [Operation Object](#operation-object) | A definition of a TRACE operation on this path. | +| query | [Operation Object](#operation-object) | A definition of a QUERY operation, as defined in the most recent IETF draft ([draft-ietf-httpbis-safe-method-w-body-08](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-08.html) as of this writing) or its RFC successor, on this path. | | additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. The map key is the HTTP method with the same capitalization that is to be sent in the request. This map MUST NOT contain any entry for the methods that can be defined by other Operation Object fields (e.g. no `POST` entry, as the Operation Object field `post` is used for this method). | | servers | [[Server Object](#server-object)] | An alternative `servers` array to service all operations in this path. If a `servers` array is specified at the [OpenAPI Object](#oas-servers) level, it will be overridden by this value. | | parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). | From ed5cfe4895218bd793b4d7863cb147605c364d58 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Mon, 31 Mar 2025 14:14:03 -0400 Subject: [PATCH 21/26] fix: tchar definition Signed-off-by: Vincent Biret --- src/schemas/validation/schema.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 202874c292..8a45260f74 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -236,8 +236,7 @@ $defs: $ref: '#/$defs/operation' propertyNames: $comment: RFC9110 restricts methods to "1*tchar" in ABNF - pattern: "^[a-zA-Z0-9!#$%&'*+.-]+$" - "^" / "_" / "`" / "|" / "~" + pattern: "^[a-zA-Z0-9!#$%&'*+.-^`|~]+$" not: enum: - GET From 480dc7506edee8924e1c9b94e4ba895ec7fea979 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 31 Mar 2025 12:29:20 -0700 Subject: [PATCH 22/26] Fix regex character class Co-authored-by: Ethan <133719+notEthan@users.noreply.github.com> --- src/schemas/validation/schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 8a45260f74..f17b8d8ee5 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -236,7 +236,7 @@ $defs: $ref: '#/$defs/operation' propertyNames: $comment: RFC9110 restricts methods to "1*tchar" in ABNF - pattern: "^[a-zA-Z0-9!#$%&'*+.-^`|~]+$" + pattern: "^[a-zA-Z0-9!#$%&'*+.^`|~-]+$" not: enum: - GET From 18261611f6798efc9643d962632a0d6be15240ea Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 31 Mar 2025 12:32:14 -0700 Subject: [PATCH 23/26] Fix character class in regular expression --- src/schemas/validation/schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index f17b8d8ee5..003ca7a637 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -236,7 +236,7 @@ $defs: $ref: '#/$defs/operation' propertyNames: $comment: RFC9110 restricts methods to "1*tchar" in ABNF - pattern: "^[a-zA-Z0-9!#$%&'*+.^`|~-]+$" + pattern: "^[a-zA-Z0-9!#$%&'*+.^`|~]+$-" not: enum: - GET From 3ee2d2485012d2d68dcab60b9192a011932b8874 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 31 Mar 2025 12:45:05 -0700 Subject: [PATCH 24/26] Undo my incorrect additional "fix" --- src/schemas/validation/schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 003ca7a637..f17b8d8ee5 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -236,7 +236,7 @@ $defs: $ref: '#/$defs/operation' propertyNames: $comment: RFC9110 restricts methods to "1*tchar" in ABNF - pattern: "^[a-zA-Z0-9!#$%&'*+.^`|~]+$-" + pattern: "^[a-zA-Z0-9!#$%&'*+.^`|~-]+$" not: enum: - GET From 0c4f6be57782a3498328ddb3425e8aec51e89cd9 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 1 Apr 2025 08:57:18 -0400 Subject: [PATCH 25/26] docs: typo fix in html attribute name Co-authored-by: Ralf Handl --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index eec14fc939..ebb932af29 100644 --- a/src/oas.md +++ b/src/oas.md @@ -932,7 +932,7 @@ The path itself is still exposed to the documentation viewer but they will not k | head | [Operation Object](#operation-object) | A definition of a HEAD operation on this path. | | patch | [Operation Object](#operation-object) | A definition of a PATCH operation on this path. | | trace | [Operation Object](#operation-object) | A definition of a TRACE operation on this path. | -| query | [Operation Object](#operation-object) | A definition of a QUERY operation, as defined in the most recent IETF draft ([draft-ietf-httpbis-safe-method-w-body-08](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-08.html) as of this writing) or its RFC successor, on this path. | +| query | [Operation Object](#operation-object) | A definition of a QUERY operation, as defined in the most recent IETF draft ([draft-ietf-httpbis-safe-method-w-body-08](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-08.html) as of this writing) or its RFC successor, on this path. | | additionalOperations | Map[`string`, [Operation Object](#operation-object)] | A map of additional operations on this path. The map key is the HTTP method with the same capitalization that is to be sent in the request. This map MUST NOT contain any entry for the methods that can be defined by other Operation Object fields (e.g. no `POST` entry, as the Operation Object field `post` is used for this method). | | servers | [[Server Object](#server-object)] | An alternative `servers` array to service all operations in this path. If a `servers` array is specified at the [OpenAPI Object](#oas-servers) level, it will be overridden by this value. | | parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). | From 238aacaa7e2b4a28beac367a6fdc10e92ca1a2a2 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 1 Apr 2025 08:57:37 -0400 Subject: [PATCH 26/26] docs: schema regex fix Co-authored-by: Ralf Handl --- src/schemas/validation/schema.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index f17b8d8ee5..3f804ad16b 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -236,7 +236,7 @@ $defs: $ref: '#/$defs/operation' propertyNames: $comment: RFC9110 restricts methods to "1*tchar" in ABNF - pattern: "^[a-zA-Z0-9!#$%&'*+.^`|~-]+$" + pattern: "^[a-zA-Z0-9!#$%&'*+.^_`|~-]+$" not: enum: - GET