feat: adds the detected format as part of the diagnostic (#2482)

baywet · web-flow · commit 59d7c81fae8c · 2025-08-29T00:50:56.000Z
feat: adds the detected format to the diagnostics

-------

Signed-off-by: Vincent Biret &lt;vibiret@microsoft.com&gt;
diff --git a/src/Microsoft.OpenApi.YamlReader/OpenApiYamlReader.cs b/src/Microsoft.OpenApi.YamlReader/OpenApiYamlReader.cs
@@ -31,14 +31,14 @@ public async Task<ReadResult> ReadAsync(Stream input,
             if (input is null) throw new ArgumentNullException(nameof(input));
             if (input is MemoryStream memoryStream)
             {
-                return Read(memoryStream, location, settings);
+                return UpdateFormat(Read(memoryStream, location, settings));
             } 
             else 
             {
                 using var preparedStream = new MemoryStream();
                 await input.CopyToAsync(preparedStream, copyBufferSize, cancellationToken).ConfigureAwait(false);
                 preparedStream.Position = 0;
-                return Read(preparedStream, location, settings);
+                return UpdateFormat(Read(preparedStream, location, settings));
             }
         }
 
@@ -67,20 +67,27 @@ public ReadResult Read(MemoryStream input,
             {
                 var diagnostic = new OpenApiDiagnostic();
                 diagnostic.Errors.Add(new($"#line={ex.LineNumber}", ex.Message));
+                diagnostic.Format = OpenApiConstants.Yaml;
                 return new()
                 {
                     Document = null,
-                    Diagnostic = diagnostic
+                    Diagnostic = diagnostic,
                 };
             }
 
-            return Read(jsonNode, location, settings);
+            return UpdateFormat(Read(jsonNode, location, settings));
+        }
+        private static ReadResult UpdateFormat(ReadResult result)
+        {
+            result.Diagnostic ??= new OpenApiDiagnostic();
+            result.Diagnostic.Format = OpenApiConstants.Yaml;
+            return result;
         }
 
         /// <inheritdoc/>
         public static ReadResult Read(JsonNode jsonNode, Uri location, OpenApiReaderSettings settings)
         {
-            return _jsonReader.Read(jsonNode, location, settings);
+            return UpdateFormat(_jsonReader.Read(jsonNode, location, settings));
         }
 
         /// <inheritdoc/>
diff --git a/src/Microsoft.OpenApi/Reader/OpenApiDiagnostic.cs b/src/Microsoft.OpenApi/Reader/OpenApiDiagnostic.cs
@@ -25,6 +25,11 @@ public class OpenApiDiagnostic
         /// </summary>
         public OpenApiSpecVersion SpecificationVersion { get; set; }
 
+        /// <summary>
+        /// The format of the OpenAPI document (e.g., "json", "yaml").
+        /// </summary>
+        public string? Format { get; set; }
+
         /// <summary>
         /// Append another set of diagnostic Errors and Warnings to this one, this may be appended from another external
         /// document's parsing and we want to indicate which file it originated from.
diff --git a/src/Microsoft.OpenApi/Reader/OpenApiJsonReader.cs b/src/Microsoft.OpenApi/Reader/OpenApiJsonReader.cs
@@ -42,10 +42,11 @@ public ReadResult Read(MemoryStream input,
             catch (JsonException ex)
             {
                 diagnostic.Errors.Add(new OpenApiError($"#line={ex.LineNumber}", $"Please provide the correct format, {ex.Message}"));
+                diagnostic.Format = OpenApiConstants.Json;
                 return new ReadResult
                 {
                     Document = null,
-                    Diagnostic = diagnostic
+                    Diagnostic = diagnostic,
                 };
             }
 
@@ -102,11 +103,11 @@ public ReadResult Read(JsonNode jsonNode,
                     }
                 }                
             }
-
+            diagnostic.Format = OpenApiConstants.Json;
             return new()
             {
                 Document = document,
-                Diagnostic = diagnostic
+                Diagnostic = diagnostic,
             };
         }
 
@@ -138,10 +139,11 @@ public async Task<ReadResult> ReadAsync(Stream input,
             catch (JsonException ex)
             {
                 diagnostic.Errors.Add(new OpenApiError($"#line={ex.LineNumber}", $"Please provide the correct format, {ex.Message}"));
+                diagnostic.Format = OpenApiConstants.Json;
                 return new ReadResult
                 {
                     Document = null,
-                    Diagnostic = diagnostic
+                    Diagnostic = diagnostic,
                 };
             }
 
diff --git a/test/Microsoft.OpenApi.Readers.Tests/OpenApiReaderTests/OpenApiStreamReaderTests.cs b/test/Microsoft.OpenApi.Readers.Tests/OpenApiReaderTests/OpenApiStreamReaderTests.cs
@@ -20,8 +20,9 @@ public async Task StreamShouldCloseIfLeaveStreamOpenSettingEqualsFalse()
             using var stream = Resources.GetStream(Path.Combine(SampleFolderPath, "petStore.yaml"));
             var settings = new OpenApiReaderSettings { LeaveStreamOpen = false };
             settings.AddYamlReader();
-            _ = await OpenApiDocument.LoadAsync(stream, settings: settings);
+            (_, var diagnostic) = await OpenApiDocument.LoadAsync(stream, settings: settings);
             Assert.False(stream.CanRead);
+            Assert.Equal(OpenApiConstants.Yaml, diagnostic.Format);
         }
 
         [Fact]
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V2Tests/OpenApiServerTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V2Tests/OpenApiServerTests.cs
@@ -314,7 +314,8 @@ public void InvalidHostShouldYieldError()
                     {
                         new OpenApiError("#/", "Invalid host")
                     },
-                    SpecificationVersion = OpenApiSpecVersion.OpenApi2_0
+                    SpecificationVersion = OpenApiSpecVersion.OpenApi2_0,
+                    Format = OpenApiConstants.Yaml
                 }, result.Diagnostic);
         }
     }
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDocumentTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDocumentTests.cs
@@ -207,7 +207,7 @@ public async Task ParseDocumentWithWebhooksShouldSucceed()
             };
 
             // Assert            
-            Assert.Equivalent(new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_1 }, actual.Diagnostic);
+            Assert.Equivalent(new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_1, Format = OpenApiConstants.Yaml }, actual.Diagnostic);
             actual.Document.Should().BeEquivalentTo(expected, options => options.Excluding(x => x.Workspace).Excluding(y => y.BaseUri));
         }
 
@@ -414,7 +414,7 @@ public async Task ParseDocumentsWithReusablePathItemInWebhooksSucceeds()
             .Excluding(x => x.Workspace)
             .Excluding(y => y.BaseUri));
             Assert.Equivalent(
-                new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_1 }, actual.Diagnostic);
+                new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_1, Format = OpenApiConstants.Yaml }, actual.Diagnostic);
         }
 
         [Fact]
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiCallbackTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiCallbackTests.cs
@@ -71,7 +71,7 @@ public async Task ParseCallbackWithReferenceShouldSucceed()
             var callback = subscribeOperation.Callbacks["simpleHook"];
 
             Assert.Equivalent(
-                new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0 }, result.Diagnostic);
+                new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0, Format = OpenApiConstants.Yaml }, result.Diagnostic);
 
             Assert.Equivalent(
                 new OpenApiCallbackReference("simpleHook", result.Document)
@@ -120,7 +120,7 @@ public async Task ParseMultipleCallbacksWithReferenceShouldSucceed()
             var subscribeOperation = path.Operations[HttpMethod.Post];
 
             Assert.Equivalent(
-                new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0 }, result.Diagnostic);
+                new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0, Format = OpenApiConstants.Yaml }, result.Diagnostic);
 
             var callback1 = subscribeOperation.Callbacks["simpleHook"];
 
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiDocumentTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiDocumentTests.cs
@@ -69,7 +69,8 @@ public void ParseDocumentFromInlineStringShouldSucceed()
             Assert.Equivalent(
                 new OpenApiDiagnostic()
                 {
-                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0
+                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0,
+                    Format = OpenApiConstants.Yaml
                 }, result.Diagnostic);
         }
 
@@ -147,7 +148,8 @@ public async Task ParseBrokenMinimalDocumentShouldYieldExpectedDiagnostic()
                     {
                             new OpenApiValidatorError(nameof(OpenApiInfoRules.InfoRequiredFields),"#/info/title", "The field 'title' in 'info' object is REQUIRED.")
                     },
-                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0
+                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0,
+                    Format = OpenApiConstants.Yaml
                 }, result.Diagnostic);
         }
 
@@ -170,7 +172,8 @@ public async Task ParseMinimalDocumentShouldSucceed()
             Assert.Equivalent(
                 new OpenApiDiagnostic()
                 {
-                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0
+                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0,
+                    Format = OpenApiConstants.Yaml
                 }, result.Diagnostic);
         }
 
@@ -557,7 +560,7 @@ public async Task ParseStandardPetStoreDocumentShouldSucceed()
             actual.Document.Should().BeEquivalentTo(expectedDoc, options => options.Excluding(x => x.Workspace).Excluding(y => y.BaseUri));
 
             Assert.Equivalent(
-                new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0 }, actual.Diagnostic);
+                new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0, Format = OpenApiConstants.Yaml }, actual.Diagnostic);
         }
 
         [Fact]
@@ -1031,7 +1034,7 @@ [new OpenApiSecuritySchemeReference("securitySchemeName2")] =
             .Excluding(y => y.BaseUri));
 
             Assert.Equivalent(
-                    new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0 }, actual.Diagnostic);
+                    new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0, Format = OpenApiConstants.Yaml }, actual.Diagnostic);
         }
 
         [Fact]
@@ -1042,7 +1045,7 @@ public async Task ParsePetStoreExpandedShouldSucceed()
             // TODO: Create the object in memory and compare with the one read from YAML file.
 
             Assert.Equivalent(
-                    new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0 }, actual.Diagnostic);
+                    new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_0, Format = OpenApiConstants.Yaml }, actual.Diagnostic);
         }
 
         [Fact]
@@ -1444,9 +1447,10 @@ public void ParseBasicDocumentWithServerVariableShouldSucceed()
             };
 
             Assert.Equivalent(
-                new OpenApiDiagnostic 
-                { 
-                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0
+                new OpenApiDiagnostic
+                {
+                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0,
+                    Format = OpenApiConstants.Yaml
                 }, result.Diagnostic);
 
             result.Document.Should().BeEquivalentTo(expected, options => options.Excluding(x => x.BaseUri));
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiSchemaTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V3Tests/OpenApiSchemaTests.cs
@@ -231,7 +231,8 @@ public async Task ParseBasicSchemaWithReferenceShouldSucceed()
             Assert.Equivalent(
                 new OpenApiDiagnostic()
                 {
-                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0
+                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0,
+                    Format = OpenApiConstants.Yaml
                 }, result.Diagnostic);
 
             var expectedComponents = new OpenApiComponents
@@ -394,7 +395,8 @@ public async Task ParseExternalReferenceSchemaShouldSucceed()
             Assert.Equivalent(
                 new OpenApiDiagnostic()
                 {
-                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0
+                    SpecificationVersion = OpenApiSpecVersion.OpenApi3_0,
+                    Format = OpenApiConstants.Yaml
                 }, result.Diagnostic);
 
             var expectedComponents = new OpenApiComponents
diff --git a/test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt b/test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt
@@ -1934,6 +1934,7 @@ namespace Microsoft.OpenApi.Reader
     {
         public OpenApiDiagnostic() { }
         public System.Collections.Generic.IList<Microsoft.OpenApi.OpenApiError> Errors { get; set; }
+        public string? Format { get; set; }
         public Microsoft.OpenApi.OpenApiSpecVersion SpecificationVersion { get; set; }
         public System.Collections.Generic.IList<Microsoft.OpenApi.OpenApiError> Warnings { get; set; }
         public void AppendDiagnostic(Microsoft.OpenApi.Reader.OpenApiDiagnostic diagnosticToAdd, string? fileNameToAdd = null) { }
diff --git a/test/Microsoft.OpenApi.Tests/Reader/OpenApiModelFactoryTests.cs b/test/Microsoft.OpenApi.Tests/Reader/OpenApiModelFactoryTests.cs
@@ -114,6 +114,7 @@ await File.WriteAllTextAsync(tempFilePathReferrer,
             BaseUrl = baseUri, 
         };
         var readResult = await OpenApiDocument.LoadAsync(stream, settings: settings);
+        Assert.Equal(OpenApiConstants.Json, readResult.Diagnostic.Format);
         Assert.NotNull(readResult.Document);
         Assert.NotNull(readResult.Document.Components);
         Assert.Equal(baseUri, readResult.Document.BaseUri);

Original file line number	Diff line number	Diff line change
`@@ -31,14 +31,14 @@ public async Task<ReadResult> ReadAsync(Stream input,`
`31`	`31`	`if (input is null) throw new ArgumentNullException(nameof(input));`
`32`	`32`	`if (input is MemoryStream memoryStream)`
`33`	`33`	`{`
`34`		`- return Read(memoryStream, location, settings);`
	`34`	`+ return UpdateFormat(Read(memoryStream, location, settings));`
`35`	`35`	`}`
`36`	`36`	`else`
`37`	`37`	`{`
`38`	`38`	`using var preparedStream = new MemoryStream();`
`39`	`39`	`await input.CopyToAsync(preparedStream, copyBufferSize, cancellationToken).ConfigureAwait(false);`
`40`	`40`	`preparedStream.Position = 0;`
`41`		`- return Read(preparedStream, location, settings);`
	`41`	`+ return UpdateFormat(Read(preparedStream, location, settings));`
`42`	`42`	`}`
`43`	`43`	`}`
`44`	`44`
`@@ -67,20 +67,27 @@ public ReadResult Read(MemoryStream input,`
`67`	`67`	`{`
`68`	`68`	`var diagnostic = new OpenApiDiagnostic();`
`69`	`69`	`diagnostic.Errors.Add(new($"#line={ex.LineNumber}", ex.Message));`
	`70`	`+ diagnostic.Format = OpenApiConstants.Yaml;`
`70`	`71`	`return new()`
`71`	`72`	`{`
`72`	`73`	`Document = null,`
`73`		`- Diagnostic = diagnostic`
	`74`	`+ Diagnostic = diagnostic,`
`74`	`75`	`};`
`75`	`76`	`}`
`76`	`77`
`77`		`- return Read(jsonNode, location, settings);`
	`78`	`+ return UpdateFormat(Read(jsonNode, location, settings));`
	`79`	`+ }`
	`80`	`+ private static ReadResult UpdateFormat(ReadResult result)`
	`81`	`+ {`
	`82`	`+ result.Diagnostic ??= new OpenApiDiagnostic();`
	`83`	`+ result.Diagnostic.Format = OpenApiConstants.Yaml;`
	`84`	`+ return result;`
`78`	`85`	`}`
`79`	`86`
`80`	`87`	`/// <inheritdoc/>`
`81`	`88`	`public static ReadResult Read(JsonNode jsonNode, Uri location, OpenApiReaderSettings settings)`
`82`	`89`	`{`
`83`		`- return _jsonReader.Read(jsonNode, location, settings);`
	`90`	`+ return UpdateFormat(_jsonReader.Read(jsonNode, location, settings));`
`84`	`91`	`}`
`85`	`92`
`86`	`93`	`/// <inheritdoc/>`
Original file line number	Diff line number	Diff line change
`@@ -42,10 +42,11 @@ public ReadResult Read(MemoryStream input,`
`42`	`42`	`catch (JsonException ex)`
`43`	`43`	`{`
`44`	`44`	`diagnostic.Errors.Add(new OpenApiError($"#line={ex.LineNumber}", $"Please provide the correct format, {ex.Message}"));`
	`45`	`+ diagnostic.Format = OpenApiConstants.Json;`
`45`	`46`	`return new ReadResult`
`46`	`47`	`{`
`47`	`48`	`Document = null,`
`48`		`- Diagnostic = diagnostic`
	`49`	`+ Diagnostic = diagnostic,`
`49`	`50`	`};`
`50`	`51`	`}`
`51`	`52`
`@@ -102,11 +103,11 @@ public ReadResult Read(JsonNode jsonNode,`
`102`	`103`	`}`
`103`	`104`	`}`
`104`	`105`	`}`
`105`		`-`
	`106`	`+ diagnostic.Format = OpenApiConstants.Json;`
`106`	`107`	`return new()`
`107`	`108`	`{`
`108`	`109`	`Document = document,`
`109`		`- Diagnostic = diagnostic`
	`110`	`+ Diagnostic = diagnostic,`
`110`	`111`	`};`
`111`	`112`	`}`
`112`	`113`
`@@ -138,10 +139,11 @@ public async Task<ReadResult> ReadAsync(Stream input,`
`138`	`139`	`catch (JsonException ex)`
`139`	`140`	`{`
`140`	`141`	`diagnostic.Errors.Add(new OpenApiError($"#line={ex.LineNumber}", $"Please provide the correct format, {ex.Message}"));`
	`142`	`+ diagnostic.Format = OpenApiConstants.Json;`
`141`	`143`	`return new ReadResult`
`142`	`144`	`{`
`143`	`145`	`Document = null,`
`144`		`- Diagnostic = diagnostic`
	`146`	`+ Diagnostic = diagnostic,`
`145`	`147`	`};`
`146`	`148`	`}`
`147`	`149`
Original file line number	Diff line number	Diff line change
`@@ -314,7 +314,8 @@ public void InvalidHostShouldYieldError()`
`314`	`314`	`{`
`315`	`315`	`new OpenApiError("#/", "Invalid host")`
`316`	`316`	`},`
`317`		`- SpecificationVersion = OpenApiSpecVersion.OpenApi2_0`
	`317`	`+ SpecificationVersion = OpenApiSpecVersion.OpenApi2_0,`
	`318`	`+ Format = OpenApiConstants.Yaml`
`318`	`319`	`}, result.Diagnostic);`
`319`	`320`	`}`
`320`	`321`	`}`
Original file line number	Diff line number	Diff line change
`@@ -207,7 +207,7 @@ public async Task ParseDocumentWithWebhooksShouldSucceed()`
`207`	`207`	`};`
`208`	`208`
`209`	`209`	`// Assert`
`210`		`- Assert.Equivalent(new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_1 }, actual.Diagnostic);`
	`210`	`+ Assert.Equivalent(new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_1, Format = OpenApiConstants.Yaml }, actual.Diagnostic);`
`211`	`211`	`actual.Document.Should().BeEquivalentTo(expected, options => options.Excluding(x => x.Workspace).Excluding(y => y.BaseUri));`
`212`	`212`	`}`
`213`	`213`
`@@ -414,7 +414,7 @@ public async Task ParseDocumentsWithReusablePathItemInWebhooksSucceeds()`
`414`	`414`	`.Excluding(x => x.Workspace)`
`415`	`415`	`.Excluding(y => y.BaseUri));`
`416`	`416`	`Assert.Equivalent(`
`417`		`- new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_1 }, actual.Diagnostic);`
	`417`	`+ new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_1, Format = OpenApiConstants.Yaml }, actual.Diagnostic);`
`418`	`418`	`}`
`419`	`419`
`420`	`420`	`[Fact]`
Original file line number	Diff line number	Diff line change
`@@ -1934,6 +1934,7 @@ namespace Microsoft.OpenApi.Reader`
`1934`	`1934`	`{`
`1935`	`1935`	`public OpenApiDiagnostic() { }`
`1936`	`1936`	`public System.Collections.Generic.IList<Microsoft.OpenApi.OpenApiError> Errors { get; set; }`
	`1937`	`+ public string? Format { get; set; }`
`1937`	`1938`	`public Microsoft.OpenApi.OpenApiSpecVersion SpecificationVersion { get; set; }`
`1938`	`1939`	`public System.Collections.Generic.IList<Microsoft.OpenApi.OpenApiError> Warnings { get; set; }`
`1939`	`1940`	`public void AppendDiagnostic(Microsoft.OpenApi.Reader.OpenApiDiagnostic diagnosticToAdd, string? fileNameToAdd = null) { }`