Merge pull request #2395 from microsoft/fix/schema-no-warn

fix: warn instead of error out when $schema is present in the document

Author: baywet

src/Microsoft.OpenApi/Reader/ParseNodes/PropertyNode.cs

@@ -74,8 +74,15 @@ public void ParseField<T>(
                 }
                 else
                 {
-                    Context.Diagnostic.Errors.Add(
-                        new("", $"{Name} is not a valid property at {Context.GetLocation()}"));
+                    var error = new OpenApiError("", $"{Name} is not a valid property at {Context.GetLocation()}");
+                    if ("$schema".Equals(Name, StringComparison.OrdinalIgnoreCase))
+                    {
+                        Context.Diagnostic.Warnings.Add(error);
+                    }
+                    else
+                    {
+                        Context.Diagnostic.Errors.Add(error);
+                    }
                 }
             }
         }

test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDocumentTests.cs

@@ -579,6 +579,17 @@ public async Task ParseDocumentWithEmptyTagsWorks()
 
             doc.Paths["/groups"].Operations[HttpMethod.Get].Tags.Should().BeNull("Empty tags are ignored, so we should not have any tags");
         }
+        [Fact]
+        public async Task DocumentWithSchemaResultsInWarning()
+        {
+            var path = Path.Combine(SampleFolderPath, "documentWithSchema.json");
+            var (doc, diag) = await OpenApiDocument.LoadAsync(path, SettingsFixture.ReaderSettings);
+            Assert.NotNull(doc);
+            Assert.NotNull(diag);
+            Assert.Empty(diag.Errors);
+            Assert.Single(diag.Warnings);
+            Assert.StartsWith("$schema is not a valid property", diag.Warnings[0].Message);
+        }
 
         [Fact]
         public void ParseEmptyMemoryStreamThrowsAnArgumentException()

test/Microsoft.OpenApi.Readers.Tests/V31Tests/Samples/OpenApiDocument/documentWithSchema.json

@@ -0,0 +1,27 @@
+{
+    "$schema": "https://spec.openapis.org/oas/3.1/schema/2025-02-13",
+    "openapi": "3.1.0",
+    "info": {
+        "title": "Sample API",
+        "version": "1.0.0"
+    },
+    "paths": {
+        "/example": {
+            "get": {
+                "summary": "Example operation",
+                "responses": {
+                    "200": {
+                        "description": "Successful response",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "string"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}