feat/path conversions by baywet · Pull Request #2827 · microsoft/OpenAPI.NET

baywet · 2026-04-16T19:21:24Z

Signed-off-by: Vincent Biret <vibiret@microsoft.com>

…where finding Agent-Logs-Url: https://github.com/microsoft/OpenAPI.NET/sessions/4f39d2a9-62e7-497f-be81-7f0efcb876c9 Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

…ce and rename V3_0 to V30 Agent-Logs-Url: https://github.com/microsoft/OpenAPI.NET/sessions/0fac65d3-0bbb-44db-b82e-7648c8fb8f86 Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

baywet · 2026-04-19T18:12:59Z

@copilot we're missing a policy to map the requestBody property to a in:body parameter for the path conversion to v2

…sion Agent-Logs-Url: https://github.com/microsoft/OpenAPI.NET/sessions/3e249ace-8d41-41c9-af08-288d036a4def Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

Copilot · 2026-04-19T18:19:51Z

@copilot we're missing a policy to map the requestBody property to a in:body parameter for the path conversion to v2

Added in c0d89d1. The new V2RequestBodyToBodyParameterPolicy maps:

#/paths/~1items/post/requestBody → #/paths/~1items/post/parameters/0
#/paths/~1items/post/requestBody/content/application~1json/schema → #/paths/~1items/post/parameters/0/schema
#/paths/~1items/post/requestBody/{prop} → #/paths/~1items/post/parameters/0/{prop}

requestBody was also removed from V2UnsupportedPathPolicy.UnsupportedSegments so it's no longer returned as null.

baywet · 2026-04-19T18:23:55Z

@copilot the policies aren't 'rooted' in the document then they can have false positive matches. For example the V2ResponseContentUnwrappingPolicy can match an extension or schema that just happens to have a path that matches ./responses/[^/]/content/[^/]*.

Example paths that can cause incorrect path conversions: #/paths/~~1items/get/requestBody/content/application~~1json/schema/properties/responses/properties/content/properties/foo#/x-ms-sneaky-extension/additionalReference/responses/data/content/0

Attempt to root the regexes where possible (dollar sign), add additional negative tests

… in schema trees Agent-Logs-Url: https://github.com/microsoft/OpenAPI.NET/sessions/ade1e55d-3bd6-4d67-baee-32d89b1ad9f9 Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

Copilot · 2026-04-19T18:36:05Z

@copilot the policies aren't 'rooted' in the document then they can have false positive matches. For example the V2ResponseContentUnwrappingPolicy can match an extension or schema that just happens to...

Addressed in c063087. Two rooting strategies were applied:

HTTP method anchor for operation-level keywords — V2RequestBodyToBodyParameterPolicy now requires requestBody to be immediately preceded by an HTTP method, and V2ResponseContentUnwrappingPolicy requires responses to be immediately preceded by an HTTP method. This prevents both example false positives: the schema-property responses/content inside a deep schema tree, and the #/x-ms-sneaky-extension/additionalReference/responses/data/content/0 extension path.
IsSchemaContext guard for the remaining policies — a new helper returns true when any prior segment is properties or additionalProperties, indicating the path has entered a JSON Schema property map. Applied to V2UnsupportedPathPolicy, V2HeaderSchemaUnwrappingPolicy, and V2ComponentRenamePolicy's inline unwrapping checks.

Added negative tests covering schema-property false positives, extension-path false positives, and component-schema paths where only the rename applies.

sonarqubecloud · 2026-04-20T13:14:06Z

Quality Gate passed

Issues
0 New issues
1 Accepted issue

Measures
0 Security Hotspots
95.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Copilot

Pull request overview

Adds an experimental path/pointer conversion helper so JSON Pointer paths produced by the v3-based walker/validator can be translated to equivalent pointers for older specs (notably OpenAPI v2), addressing issue #2806’s incorrect pointer output for v2 inputs.

Changes:

Introduces OpenApiPathHelper with pluggable policies to transform or null-out pointers for unsupported constructs by target spec version.
Adds OpenApiValidatorError.GetVersionedPointer(...) as a convenience API for converting validation error pointers.
Adds comprehensive unit tests and new documentation for experimental API usage, including an ExperimentalAttribute polyfill for non-.NET8 targets.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/Microsoft.OpenApi.Tests/Services/OpenApiPathHelperTests.cs	Adds coverage for v2/v3 pointer conversion behaviors and edge cases.
src/Microsoft.OpenApi/Validations/OpenApiValidatorError.cs	Adds experimental `GetVersionedPointer` convenience method.
src/Microsoft.OpenApi/Services/OpenApiPathHelper.cs	Implements path conversion logic via spec-targeted policies.
src/Microsoft.OpenApi/Services/IOpenApiPathRepresentationPolicy.cs	Introduces internal policy interface for conversions.
src/Microsoft.OpenApi/PublicAPI.Unshipped.txt	Declares new public APIs for PublicAPI analyzer.
src/Microsoft.OpenApi/Attributes/ExperimentalAttribute.cs	Provides non-.NET8 polyfill for `ExperimentalAttribute`.
docs/experimental-apis.md	Documents experimental API diagnostics and the new path conversion APIs.

Copilot · 2026-04-20T14:44:56Z

+### Supported Transformations (v2 target)
+
+| v3 Path Pattern | v2 Equivalent |
+|---|---|
+| `#/components/schemas/{name}/**` | `#/definitions/{name}/**` |
+| `#/components/parameters/{name}/**` | `#/parameters/{name}/**` |
+| `#/components/responses/{name}/**` | `#/responses/{name}/**` |
+| `#/components/securitySchemes/{name}/**` | `#/securityDefinitions/{name}/**` |
+| `.../responses/{code}/content/{mediaType}/schema/**` | `.../responses/{code}/schema/**` |
+| `.../headers/{name}/schema/**` | `.../headers/{name}/**` |
+
+### Paths With No v2 Equivalent (returns `null`)
+
+- `#/servers/**`
+- `#/webhooks/**`
+- `.../callbacks/**`
+- `.../links/**`
+- `.../requestBody/**`
+- `.../content/{mediaType}/encoding/**`
+- `#/components/examples/**`, `#/components/headers/**`, `#/components/pathItems/**`,
+  `#/components/links/**`, `#/components/callbacks/**`, `#/components/requestBodies/**`,
+  `#/components/mediaTypes/**`


The documentation contradicts the implementation: .../requestBody/** is listed as having “no v2 equivalent (returns null)”, but OpenApiPathHelper currently maps operation-level requestBody paths to .../parameters/0/.... Either remove requestBody from the “returns null” list and document the mapping (and add it to the Supported Transformations table), or change the implementation to return null for requestBody paths.

@copilot remove that entry from the list

Done in f3c36ed. Removed .../requestBody/** from the "Paths With No v2 Equivalent" list and added its three mapping variants to the "Supported Transformations" table.

Copilot · 2026-04-20T14:44:57Z

+        // Walk through segments looking for v3-only constructs
+        for (var i = 1; i < segments.Length; i++)
+        {
+            var segment = segments[i];
+
+            // Skip segments that are inside a schema property tree — they are property names,
+            // not structural OpenAPI keywords.
+            if (OpenApiPathHelper.IsSchemaContext(segments, i))
+            {
+                continue;
+            }
+
+            // servers, callbacks, links at any nested level
+            if (UnsupportedSegments.Contains(segment))
+            {
+                return true;
+            }


V2UnsupportedPathPolicy treats servers/callbacks/links segments as unsupported at any nested level (outside schema properties). For pointers that traverse extension payloads (e.g., #/x-foo/servers/0), this will return null even though extensions are version-agnostic and the path should typically be left unchanged. Consider adding an “extension context” guard (similar to IsSchemaContext) that disables v2 structural keyword handling after any segment starting with x- (OpenApiConstants.ExtensionFieldNamePrefix).

…dd to transformations table Agent-Logs-Url: https://github.com/microsoft/OpenAPI.NET/sessions/f2c0015f-dd1e-488a-a10f-1eaecad56cbe Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

baywet added 4 commits April 16, 2026 13:46

feat: adds path translation from v3 to v2 for validation errors

329e9b3

Signed-off-by: Vincent Biret <vibiret@microsoft.com>

docs: adds documentation about the experimental path mapping helpers

098f24e

Signed-off-by: Vincent Biret <vibiret@microsoft.com>

chore: marks new APIs as experimental

6dc21b3

Signed-off-by: Vincent Biret <vibiret@microsoft.com>

perf: reduce allocations translating paths

7a6be84

Signed-off-by: Vincent Biret <vibiret@microsoft.com>

baywet self-assigned this Apr 16, 2026

github-advanced-security AI found potential problems Apr 16, 2026

View reviewed changes

Comment thread src/Microsoft.OpenApi/Services/OpenApiPathHelper.cs Fixed

Copilot started work on behalf of baywet April 16, 2026 22:11 View session

fix(library): replace foreach with LINQ Any to address CodeQL missed-…

d3dd449

…where finding Agent-Logs-Url: https://github.com/microsoft/OpenAPI.NET/sessions/4f39d2a9-62e7-497f-be81-7f0efcb876c9 Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

Copilot finished work on behalf of baywet April 16, 2026 22:15

baywet requested a review from davidrea-MS April 17, 2026 11:17

baywet commented Apr 17, 2026

View reviewed changes

Comment thread src/Microsoft.OpenApi/Attributes/ExperimentalAttribute.cs Outdated

Comment thread src/Microsoft.OpenApi/Services/OpenApiPathHelper.cs Outdated

Copilot started work on behalf of baywet April 17, 2026 11:23 View session

style(library): move conditional compilation directives above namespa…

c46f13c

…ce and rename V3_0 to V30 Agent-Logs-Url: https://github.com/microsoft/OpenAPI.NET/sessions/0fac65d3-0bbb-44db-b82e-7648c8fb8f86 Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

Copilot finished work on behalf of baywet April 17, 2026 11:26

Copilot started work on behalf of baywet April 19, 2026 18:13 View session

feat(library): add V2RequestBodyToBodyParameterPolicy for path conver…

c0d89d1

…sion Agent-Logs-Url: https://github.com/microsoft/OpenAPI.NET/sessions/3e249ace-8d41-41c9-af08-288d036a4def Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

Copilot finished work on behalf of baywet April 19, 2026 18:20

Copilot started work on behalf of baywet April 19, 2026 18:24 View session

fix(library): root policy segment matching to prevent false positives…

c063087

… in schema trees Agent-Logs-Url: https://github.com/microsoft/OpenAPI.NET/sessions/ade1e55d-3bd6-4d67-baee-32d89b1ad9f9 Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

Copilot finished work on behalf of baywet April 19, 2026 18:37

baywet requested a review from Copilot April 20, 2026 14:36

Copilot started reviewing on behalf of baywet April 20, 2026 14:36 View session

Copilot AI reviewed Apr 20, 2026

View reviewed changes

Copilot started work on behalf of baywet April 20, 2026 14:58 View session

docs(experimental-apis): remove requestBody from null-returns list, a…

f3c36ed

…dd to transformations table Agent-Logs-Url: https://github.com/microsoft/OpenAPI.NET/sessions/f2c0015f-dd1e-488a-a10f-1eaecad56cbe Co-authored-by: baywet <7905502+baywet@users.noreply.github.com>

Copilot finished work on behalf of baywet April 20, 2026 15:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat/path conversions#2827

feat/path conversions#2827
baywet wants to merge 9 commits intomainfrom
feat/path-conversions

baywet commented Apr 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

baywet commented Apr 19, 2026

Uh oh!

Copilot AI commented Apr 19, 2026

Uh oh!

baywet commented Apr 19, 2026

Uh oh!

Copilot AI commented Apr 19, 2026

Uh oh!

sonarqubecloud bot commented Apr 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 20, 2026

Uh oh!

baywet Apr 20, 2026

Uh oh!

Copilot AI Apr 20, 2026

Uh oh!

Uh oh!

Copilot AI Apr 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

baywet commented Apr 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

baywet commented Apr 19, 2026

Uh oh!

Copilot AI commented Apr 19, 2026

Uh oh!

baywet commented Apr 19, 2026

Uh oh!

Copilot AI commented Apr 19, 2026

Uh oh!

sonarqubecloud bot commented Apr 20, 2026

Quality Gate passed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

baywet Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants