fix(library): root policy segment matching to prevent false positives 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>

Author: Copilot

src/Microsoft.OpenApi/Services/OpenApiPathHelper.cs

@@ -143,6 +143,33 @@ internal static string BuildPath(string[] segments, int length)
 #endif
     }
 
+    /// <summary>
+    /// HTTP method names used to identify operation-level structural positions in the path.
+    /// </summary>
+    internal static readonly HashSet<string> HttpMethods = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "get", "post", "put", "delete", "patch", "options", "head", "trace",
+    };
+
+    /// <summary>
+    /// Returns <c>true</c> if any segment before <paramref name="exclusiveUpperBound"/> indicates
+    /// that the path has descended into a JSON Schema property tree — meaning subsequent segment
+    /// names are schema property/key names rather than OpenAPI structural keywords.
+    /// </summary>
+    internal static bool IsSchemaContext(string[] segments, int exclusiveUpperBound)
+    {
+        for (var i = 0; i < exclusiveUpperBound; i++)
+        {
+            if (string.Equals(segments[i], OpenApiConstants.Properties, StringComparison.Ordinal) ||
+                string.Equals(segments[i], OpenApiConstants.AdditionalProperties, StringComparison.Ordinal))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
     /// <summary>
     /// Copies segments into the target buffer, skipping a contiguous range.
     /// Returns the number of segments written.
@@ -166,8 +193,7 @@ internal static int CopySkipping(string[] source, int sourceLength, string[] tar
 
 /// <summary>
 /// Returns null for paths that have no equivalent in OpenAPI v2 (Swagger).
-/// Covers: servers, webhooks, callbacks, links, requestBody (inline),
-/// encoding, and unsupported component types.
+/// Covers: servers, webhooks, callbacks, links, encoding, and unsupported component types.
 /// </summary>
 internal sealed class V2UnsupportedPathPolicy : IOpenApiPathRepresentationPolicy
 {
@@ -219,7 +245,14 @@ public bool TryGetVersionedPath(string[] segments, out string? result)
         {
             var segment = segments[i];
 
-            // servers, callbacks, links, requestBody at any nested level
+            // 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;
@@ -252,11 +285,13 @@ public bool TryGetVersionedPath(string[] segments, out string? result)
     {
         result = null;
 
-        // Find requestBody segment
+        // Find requestBody immediately after an HTTP method — operation-level requestBody only.
+        // This prevents false positives when "requestBody" is a schema property name.
         var requestBodyIndex = -1;
-        for (var i = 0; i < segments.Length; i++)
+        for (var i = 1; i < segments.Length; i++)
         {
-            if (string.Equals(segments[i], OpenApiConstants.RequestBody, StringComparison.Ordinal))
+            if (string.Equals(segments[i], OpenApiConstants.RequestBody, StringComparison.Ordinal) &&
+                OpenApiPathHelper.HttpMethods.Contains(segments[i - 1]))
             {
                 requestBodyIndex = i;
                 break;
@@ -364,6 +399,7 @@ public bool TryGetVersionedPath(string[] segments, out string? result)
             // Content unwrapping: skip "content" and "{mediaType}" after "responses/{code}"
             if (string.Equals(segments[i], OpenApiConstants.Content, StringComparison.Ordinal) &&
                 i >= 3 &&
+                !OpenApiPathHelper.IsSchemaContext(segments, i) &&
                 string.Equals(segments[i - 2], OpenApiConstants.Responses, StringComparison.Ordinal) &&
                 i + 1 < segments.Length)
             {
@@ -374,6 +410,7 @@ public bool TryGetVersionedPath(string[] segments, out string? result)
             // Header schema unwrapping: skip "schema" after "headers/{name}"
             if (string.Equals(segments[i], OpenApiConstants.Schema, StringComparison.Ordinal) &&
                 i >= 3 &&
+                !OpenApiPathHelper.IsSchemaContext(segments, i) &&
                 string.Equals(segments[i - 2], OpenApiConstants.Headers, StringComparison.Ordinal))
             {
                 continue;
@@ -397,11 +434,15 @@ public bool TryGetVersionedPath(string[] segments, out string? result)
     {
         result = null;
 
-        // Find: responses / {code} / content / {mediaType}
+        // Find: {method} / responses / {code} / content / {mediaType}
+        // Require the HTTP method immediately before "responses" to anchor this to a real
+        // operation response, preventing false positives from schema properties named "responses"
+        // or from extension paths that happen to match the pattern.
         var contentIndex = -1;
-        for (var i = 0; i < segments.Length - 3; i++)
+        for (var i = 1; i < segments.Length - 3; i++)
         {
             if (string.Equals(segments[i], OpenApiConstants.Responses, StringComparison.Ordinal) &&
+                OpenApiPathHelper.HttpMethods.Contains(segments[i - 1]) &&
                 string.Equals(segments[i + 2], OpenApiConstants.Content, StringComparison.Ordinal))
             {
                 contentIndex = i + 2;
@@ -433,10 +474,12 @@ public bool TryGetVersionedPath(string[] segments, out string? result)
         result = null;
 
         // Find: headers / {name} / schema
+        // Guard against schema property trees where "headers" is just a property name.
         var schemaIndex = -1;
         for (var i = 0; i < segments.Length - 2; i++)
         {
             if (string.Equals(segments[i], OpenApiConstants.Headers, StringComparison.Ordinal) &&
+                !OpenApiPathHelper.IsSchemaContext(segments, i) &&
                 string.Equals(segments[i + 2], OpenApiConstants.Schema, StringComparison.Ordinal))
             {
                 schemaIndex = i + 2;

test/Microsoft.OpenApi.Tests/Services/OpenApiPathHelperTests.cs

@@ -280,6 +280,84 @@ public void Issue2806_ResponseContentSchemaPath_ConvertedToV2()
 
     #endregion
 
+    #region V2 rooting / false-positive guards
+
+    // V2ResponseContentUnwrappingPolicy false positives: "responses" and "content" are schema property names.
+    [Theory]
+    [InlineData("#/paths/~1items/get/responses/200/schema/properties/responses/200/content/application~1json")]
+    [InlineData("#/x-ms-sneaky-extension/additionalReference/responses/data/content/0")]
+    [InlineData("#/paths/~1items/get/parameters/0/schema/properties/responses/200/content/application~1json/schema")]
+    public void V2_ResponsesContentInsideSchemaOrExtension_NotUnwrapped(string path)
+    {
+        var result = OpenApiPathHelper.GetVersionedPath(path, OpenApiSpecVersion.OpenApi2_0);
+        Assert.Equal(path, result);
+    }
+
+    // V2RequestBodyToBodyParameterPolicy false positives: "requestBody" is a schema property name.
+    [Theory]
+    [InlineData("#/paths/~1items/get/responses/200/schema/properties/requestBody/content/application~1json/schema")]
+    [InlineData("#/paths/~1items/get/responses/200/schema/properties/requestBody/description")]
+    public void V2_RequestBodyInsideSchemaProperties_NotConvertedToBodyParameter(string path)
+    {
+        var result = OpenApiPathHelper.GetVersionedPath(path, OpenApiSpecVersion.OpenApi2_0);
+        Assert.Equal(path, result);
+    }
+
+    // V2HeaderSchemaUnwrappingPolicy false positives: "headers" is a schema property name.
+    [Theory]
+    [InlineData("#/paths/~1items/get/responses/200/schema/properties/headers/X-My-Header/schema/type")]
+    [InlineData("#/paths/~1items/get/responses/200/schema/properties/headers/X-My-Header/schema")]
+    public void V2_HeaderSchemaInsideSchemaProperties_NotUnwrapped(string path)
+    {
+        var result = OpenApiPathHelper.GetVersionedPath(path, OpenApiSpecVersion.OpenApi2_0);
+        Assert.Equal(path, result);
+    }
+
+    // V2UnsupportedPathPolicy false positives: unsupported keywords are schema property names.
+    [Theory]
+    [InlineData("#/paths/~1items/get/responses/200/schema/properties/servers/0")]
+    [InlineData("#/paths/~1items/get/responses/200/schema/properties/callbacks/onEvent")]
+    [InlineData("#/paths/~1items/get/responses/200/schema/properties/links/item")]
+    public void V2_UnsupportedKeywordsInsideSchemaProperties_NotReturnedNull(string path)
+    {
+        var result = OpenApiPathHelper.GetVersionedPath(path, OpenApiSpecVersion.OpenApi2_0);
+        Assert.Equal(path, result);
+    }
+
+    // V2ComponentRenamePolicy false positives: "content" after a property named "responses" in a schema.
+    [Fact]
+    public void V2_ComponentSchemaWithResponsesPropertyContainingContent_ContentNotUnwrapped()
+    {
+        // components/schemas/MyModel has a property "responses" whose value has a "content" property.
+        // The inline content-unwrapping should NOT fire here.
+        var path = "#/components/schemas/MyModel/properties/responses/properties/content/properties/foo";
+        var result = OpenApiPathHelper.GetVersionedPath(path, OpenApiSpecVersion.OpenApi2_0);
+        // Only the component rename applies (#/components/schemas → #/definitions).
+        Assert.Equal("#/definitions/MyModel/properties/responses/properties/content/properties/foo", result);
+    }
+
+    [Fact]
+    public void V2_ComponentSchemaWithRequestBodyPropertyInSchema_RequestBodyNotConvertedToBodyParameter()
+    {
+        // A component schema with a property named "requestBody" — component rename applies but
+        // requestBody → body parameter conversion should NOT fire.
+        var path = "#/components/schemas/Pet/properties/requestBody/content/application~1json";
+        var result = OpenApiPathHelper.GetVersionedPath(path, OpenApiSpecVersion.OpenApi2_0);
+        Assert.Equal("#/definitions/Pet/properties/requestBody/content/application~1json", result);
+    }
+
+    [Fact]
+    public void V2_ComponentSchemaWithHeadersPropertyInSchema_HeaderSchemaNotUnwrapped()
+    {
+        // A component schema with a property named "headers" — component rename applies but
+        // headers/schema unwrapping should NOT fire.
+        var path = "#/components/schemas/Pet/properties/headers/Content-Type/schema";
+        var result = OpenApiPathHelper.GetVersionedPath(path, OpenApiSpecVersion.OpenApi2_0);
+        Assert.Equal("#/definitions/Pet/properties/headers/Content-Type/schema", result);
+    }
+
+    #endregion
+
     #region OpenApiValidatorError.GetVersionedPointer
 
     [Fact]