fix(reader): document parser-level exceptions

Co-authored-by: baywet <[email protected]>
Copilot · Sep 10, 2026 · Sep 10, 2026 · Sep 11, 2026 · Sep 11, 2026 · Sep 11, 2026
commit 3b67916f28950423e7335a1fa02f3c7f7ca3a525
@@ -1,15 +1,15 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+using System;
 using System.IO;
-using System.Text.Json.Nodes;
+using System.Text;
 using System.Text.Json;
+using System.Text.Json.Nodes;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.OpenApi.Reader;
 using SharpYaml;
-using System;
-using System.Text;
 
 namespace Microsoft.OpenApi.YamlReader
 {
@@ -58,6 +58,10 @@ public OpenApiYamlReader(OpenApiYamlReaderSettings settings)
         }
 
         /// <inheritdoc/>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public async Task<ReadResult> ReadAsync(Stream input,
                                                 Uri location,
                                                 OpenApiReaderSettings settings,
@@ -68,8 +72,8 @@ public async Task<ReadResult> ReadAsync(Stream input,
             if (input is MemoryStream memoryStream)
             {
                 return ReadCore(memoryStream, location, settings, cancellationToken);
-            } 
-            else 
+            }
+            else
             {
                 using var preparedStream = new MemoryStream();
                 try
@@ -95,6 +99,10 @@ await CopyToMemoryStreamAsync(
         }
 
         /// <inheritdoc/>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public ReadResult Read(MemoryStream input,
                                Uri location,
                                OpenApiReaderSettings settings)
@@ -118,7 +126,7 @@ private ReadResult ReadCore(MemoryStream input,
 // this represents net core, net5 and up
                 using var stream = new StreamReader(input, default, true, -1, settings.LeaveStreamOpen);
 #else
-// the implementation differs and results in a null reference exception in NETFX
+                // the implementation differs and results in a null reference exception in NETFX
                 using var stream = new StreamReader(input, Encoding.UTF8, true, 4096, settings.LeaveStreamOpen);
 #endif
                 jsonNode = LoadJsonNodesFromYamlDocument(stream, cancellationToken);
@@ -194,6 +202,10 @@ public static ReadResult Read(JsonNode jsonNode, Uri location, OpenApiReaderSett
         }
 
         /// <inheritdoc/>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>. Syntax-level YAML
+        /// errors can throw before a fragment is created.
+        /// </remarks>
         public T? ReadFragment<T>(MemoryStream input,
                                  OpenApiSpecVersion version,
                                  OpenApiDocument openApiDocument,

@@ -22,6 +22,10 @@ public interface IOpenApiReader
         /// <param name="settings"> The OpenApi reader settings.</param>
         /// <param name="cancellationToken">Propagates notification that an operation should be cancelled.</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         Task<ReadResult> ReadAsync(Stream input, Uri location, OpenApiReaderSettings settings, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -31,6 +35,10 @@ public interface IOpenApiReader
         /// <param name="location">Location of where the document that is getting loaded is saved</param>
         /// <param name="settings"></param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         ReadResult Read(MemoryStream input, Uri location, OpenApiReaderSettings settings);
 
         /// <summary>
@@ -42,6 +50,10 @@ public interface IOpenApiReader
         /// <param name="diagnostic">Returns diagnostic object containing errors detected during parsing.</param>
         /// <param name="settings">The OpenApiReader settings.</param>
         /// <returns>Instance of newly created IOpenApiElement.</returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a fragment is created.
+        /// </remarks>
         T? ReadFragment<T>(MemoryStream input, OpenApiSpecVersion version, OpenApiDocument openApiDocument, out OpenApiDiagnostic diagnostic, OpenApiReaderSettings? settings = null) where T : IOpenApiElement;
     }
 }
@@ -79,8 +79,8 @@ public void RegisterComponents()
         /// <summary>
         /// A list of tags used by the specification with additional metadata.
         /// </summary>
-        public ISet<OpenApiTag>? Tags 
-        { 
+        public ISet<OpenApiTag>? Tags
+        {
             get
             {
                 return _tags;
@@ -125,14 +125,14 @@ public ISet<OpenApiTag>? Tags
         /// <summary>
         /// Parameter-less constructor
         /// </summary>
-        public OpenApiDocument() 
+        public OpenApiDocument()
         {
             Workspace = new OpenApiWorkspace();
             BaseUri = new(OpenApiConstants.BaseRegistryUri + Guid.NewGuid());
             Info = new OpenApiInfo();
             Paths = new OpenApiPaths();
         }
-                
+
         /// <summary>
         /// Initializes a copy of an an <see cref="OpenApiDocument"/> object
         /// </summary>
@@ -527,14 +527,14 @@ private static void WriteHostInfoV2(IOpenApiWriter writer, IList<OpenApiServer>?
                     .ToList();
 
                 // schemes
-                writer.WriteOptionalCollection(OpenApiConstants.Schemes, schemes, (w, s) => 
+                writer.WriteOptionalCollection(OpenApiConstants.Schemes, schemes, (w, s) =>
                 {
-                    if(!string.IsNullOrEmpty(s) && s is not null)
+                    if (!string.IsNullOrEmpty(s) && s is not null)
                     {
                         w.WriteValue(s);
                     }
                 });
-            }            
+            }
         }
 
         /// <summary>
@@ -732,6 +732,10 @@ private static bool TryGetPlainNameFragment(string reference, out string fragmen
         /// <param name="format">The OpenAPI format to use during parsing.</param>
         /// <param name="settings">The OpenApi reader settings.</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public static ReadResult Load(MemoryStream stream,
                                       string? format = null,
                                       OpenApiReaderSettings? settings = null)
@@ -746,6 +750,10 @@ public static ReadResult Load(MemoryStream stream,
         /// <param name="settings">The OpenApi reader settings.</param>
         /// <param name="token">The cancellation token</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public static async Task<ReadResult> LoadAsync(string url, OpenApiReaderSettings? settings = null, CancellationToken token = default)
         {
             return await OpenApiModelFactory.LoadAsync(url, settings, token).ConfigureAwait(false);
@@ -759,6 +767,10 @@ public static async Task<ReadResult> LoadAsync(string url, OpenApiReaderSettings
         /// <param name="settings">The OpenApi reader settings.</param>
         /// <param name="cancellationToken">Propagates information about operation cancelling.</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public static async Task<ReadResult> LoadAsync(Stream stream, string? format = null, OpenApiReaderSettings? settings = null, CancellationToken cancellationToken = default)
         {
             return await OpenApiModelFactory.LoadAsync(stream, format, settings, cancellationToken).ConfigureAwait(false);
@@ -772,6 +784,10 @@ public static async Task<ReadResult> LoadAsync(Stream stream, string? format = n
         /// <param name="format"></param>
         /// <param name="settings"></param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public static ReadResult Parse(string input,
                                        string? format = null,
                                        OpenApiReaderSettings? settings = null)
@@ -930,7 +946,7 @@ public override void Visit(IOpenApiSchema schema)
                 {
                     Schemas.Add(id, schema);
                 }
-            } 
+            }
             base.Visit(schema);
         }
     }

@@ -1,13 +1,13 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+using System;
 using System.IO;
-using System.Text.Json.Nodes;
+using System.Linq;
 using System.Text.Json;
+using System.Text.Json.Nodes;
 using System.Threading;
 using System.Threading.Tasks;
-using System.Linq;
-using System;
 
 namespace Microsoft.OpenApi.Reader
 {
@@ -23,6 +23,10 @@ public class OpenApiJsonReader : IOpenApiReader
         /// <param name="location">Location of where the document that is getting loaded is saved</param>
         /// <param name="settings">The Reader settings to be used during parsing.</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public ReadResult Read(MemoryStream input,
                                Uri location,
                                OpenApiReaderSettings settings)
@@ -60,6 +64,10 @@ public ReadResult Read(MemoryStream input,
         /// <param name="location">Location of where the document that is getting loaded is saved</param>
         /// <param name="settings">The Reader settings to be used during parsing.</param>
         /// <returns></returns>
+        /// <remarks>
+        /// Use this overload when JSON has already been parsed into a <see cref="JsonNode"/>. OpenAPI semantic
+        /// errors are returned in the <see cref="ReadResult.Diagnostic"/>.
+        /// </remarks>
         public ReadResult Read(JsonNode jsonNode,
                                Uri location,
                                OpenApiReaderSettings settings)
@@ -91,7 +99,7 @@ public ReadResult Read(JsonNode jsonNode,
             if (document is not null && settings.RuleSet is not null && settings.RuleSet.Rules.Any())
             {
                 var openApiErrors = document.Validate(settings.RuleSet);
-                if(openApiErrors is not null)
+                if (openApiErrors is not null)
                 {
                     foreach (var item in openApiErrors.OfType<OpenApiValidatorError>())
                     {
@@ -101,7 +109,7 @@ public ReadResult Read(JsonNode jsonNode,
                     {
                         diagnostic.Warnings.Add(item);
                     }
-                }                
+                }
             }
             diagnostic.Format = OpenApiConstants.Json;
             return new()
@@ -119,6 +127,10 @@ public ReadResult Read(JsonNode jsonNode,
         /// <param name="settings">The Reader settings to be used during parsing.</param>
         /// <param name="cancellationToken">Propagates notifications that operations should be cancelled.</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public async Task<ReadResult> ReadAsync(Stream input,
                                                 Uri location,
                                                 OpenApiReaderSettings settings,
@@ -151,6 +163,10 @@ public async Task<ReadResult> ReadAsync(Stream input,
         }
 
         /// <inheritdoc/>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>. Syntax-level JSON
+        /// errors can throw before a fragment is created.
+        /// </remarks>
         public T? ReadFragment<T>(MemoryStream input,
                                  OpenApiSpecVersion version,
                                  OpenApiDocument openApiDocument,

@@ -24,6 +24,10 @@ public static class OpenApiModelFactory
         /// <param name="settings"> The OpenApi reader settings.</param>
         /// <param name="format">The OpenAPI format.</param>
         /// <returns>An OpenAPI document instance.</returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public static ReadResult Load(MemoryStream stream,
                                       string? format = null,
                                       OpenApiReaderSettings? settings = null)
@@ -59,6 +63,10 @@ public static ReadResult Load(MemoryStream stream,
         /// <param name="settings">The OpenApiReader settings.</param>
         /// <returns>Instance of newly created IOpenApiElement.</returns>
         /// <returns>The OpenAPI element.</returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a fragment is created.
+        /// </remarks>
         public static T? Load<T>(MemoryStream input, OpenApiSpecVersion version, string? format, OpenApiDocument openApiDocument, out OpenApiDiagnostic diagnostic, OpenApiReaderSettings? settings = null) where T : IOpenApiElement
         {
             format ??= InspectStreamFormat(input);
@@ -73,6 +81,10 @@ public static ReadResult Load(MemoryStream stream,
         /// <param name="settings"> The OpenApi reader settings.</param>
         /// <param name="token">The cancellation token</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public static async Task<ReadResult> LoadAsync(string url, OpenApiReaderSettings? settings = null, CancellationToken token = default)
         {
             settings ??= DefaultReaderSettings.Value;
@@ -94,6 +106,10 @@ public static async Task<ReadResult> LoadAsync(string url, OpenApiReaderSettings
         /// <param name="token"></param>
         /// <returns>Instance of newly created IOpenApiElement.</returns>
         /// <returns>The OpenAPI element.</returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned by the reader diagnostic. Syntax-level JSON or YAML errors can throw
+        /// before a fragment is created.
+        /// </remarks>
         public static async Task<T?> LoadAsync<T>(string url, OpenApiSpecVersion version, OpenApiDocument openApiDocument, OpenApiReaderSettings? settings = null, CancellationToken token = default) where T : IOpenApiElement
         {
             settings ??= DefaultReaderSettings.Value;
@@ -112,6 +128,10 @@ public static async Task<ReadResult> LoadAsync(string url, OpenApiReaderSettings
         /// <param name="cancellationToken">Propagates notification that operations should be cancelled.</param>
         /// <param name="format">The Open API format</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public static async Task<ReadResult> LoadAsync(Stream input, string? format = null, OpenApiReaderSettings? settings = null, CancellationToken cancellationToken = default)
         {
 #if NET6_0_OR_GREATER
@@ -159,6 +179,10 @@ public static async Task<ReadResult> LoadAsync(Stream input, string? format = nu
         /// <param name="settings"></param>
         /// <param name="token"></param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned by the reader diagnostic. Syntax-level JSON or YAML errors can throw
+        /// before a fragment is created.
+        /// </remarks>
         public static async Task<T?> LoadAsync<T>(Stream input,
                                                  OpenApiSpecVersion version,
                                                  OpenApiDocument openApiDocument,
@@ -192,6 +216,10 @@ public static async Task<ReadResult> LoadAsync(Stream input, string? format = nu
         /// <param name="format">The Open API format</param>
         /// <param name="settings">The OpenApi reader settings.</param>
         /// <returns>An OpenAPI document instance.</returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a <see cref="ReadResult"/> is created.
+        /// </remarks>
         public static ReadResult Parse(string input,
                                        string? format = null,
                                        OpenApiReaderSettings? settings = null)
@@ -220,6 +248,10 @@ public static ReadResult Parse(string input,
         /// <param name="format">The Open API format</param>
         /// <param name="settings">The OpenApi reader settings.</param>
         /// <returns>An OpenAPI document instance.</returns>
+        /// <remarks>
+        /// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>. Syntax-level JSON or YAML
+        /// errors can throw before a fragment is created.
+        /// </remarks>
         public static T? Parse<T>(string input,
                                  OpenApiSpecVersion version,
                                  OpenApiDocument openApiDocument,
@@ -437,7 +469,7 @@ private static async Task<MemoryStream> CopyToMemoryStreamAsync(Stream input, Ca
 #endif
             bufferStream.Position = 0;
             return bufferStream;
-        } 
+        }
 
         private static async Task<(Stream, string)> PrepareStreamForReadingAsync(Stream input, string? format, CancellationToken token = default)
         {