fix: aligns exception and diagnostics behaviour across the API surface

src/Microsoft.OpenApi.YamlReader/OpenApiYamlReader.cs

@@ -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,9 @@ public OpenApiYamlReader(OpenApiYamlReaderSettings settings)
         }
 
         /// <inheritdoc/>
+        /// <remarks>
+        /// OpenAPI semantic and parser errors are returned in the <see cref="ReadResult.Diagnostic"/>.
+        /// </remarks>
         public async Task<ReadResult> ReadAsync(Stream input,
                                                 Uri location,
                                                 OpenApiReaderSettings settings,
@@ -68,8 +71,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 +98,9 @@ await CopyToMemoryStreamAsync(
         }
 
         /// <inheritdoc/>
+        /// <remarks>
+        /// OpenAPI semantic and parser errors are returned in the <see cref="ReadResult.Diagnostic"/>.
+        /// </remarks>
         public ReadResult Read(MemoryStream input,
                                Uri location,
                                OpenApiReaderSettings settings)
@@ -118,7 +124,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 +200,9 @@ public static ReadResult Read(JsonNode jsonNode, Uri location, OpenApiReaderSett
         }
 
         /// <inheritdoc/>
+        /// <remarks>
+        /// OpenAPI semantic and parser errors are returned in the <paramref name="diagnostic"/>.
+        /// </remarks>
         public T? ReadFragment<T>(MemoryStream input,
                                  OpenApiSpecVersion version,
                                  OpenApiDocument openApiDocument,

src/Microsoft.OpenApi/Interfaces/IOpenApiReader.cs

@@ -22,6 +22,9 @@ 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 and parser errors are returned in the <see cref="ReadResult.Diagnostic"/>.
+        /// </remarks>
         Task<ReadResult> ReadAsync(Stream input, Uri location, OpenApiReaderSettings settings, CancellationToken cancellationToken = default);
 
         /// <summary>
@@ -31,6 +34,9 @@ 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 and parser errors are returned in the <see cref="ReadResult.Diagnostic"/>.
+        /// </remarks>
         ReadResult Read(MemoryStream input, Uri location, OpenApiReaderSettings settings);
 
         /// <summary>
@@ -42,6 +48,9 @@ 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 and parser errors are returned in the <paramref name="diagnostic"/>.
+        /// </remarks>
         T? ReadFragment<T>(MemoryStream input, OpenApiSpecVersion version, OpenApiDocument openApiDocument, out OpenApiDiagnostic diagnostic, OpenApiReaderSettings? settings = null) where T : IOpenApiElement;
     }
 }

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -79,8 +79,8 @@
         /// <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 @@
         /// <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>
@@ -311,7 +311,7 @@
         /// <summary>
         /// Serialize <see cref="OpenApiDocument"/> to OpenAPI object V2.0.
         /// </summary>
         public void SerializeAsV2(IOpenApiWriter writer)
         {
             Utils.CheckArgumentNull(writer);
 
@@ -460,7 +460,7 @@
             return server.ReplaceServerUrlVariables([]);
         }
 
         private static void WriteHostInfoV2(IOpenApiWriter writer, IList<OpenApiServer>? servers)
         {
             if (servers == null || !servers.Any())
             {
@@ -522,19 +522,19 @@
                                 UriFormat.SafeUnescaped,
                                 StringComparison.OrdinalIgnoreCase) ==
                             0 && u.IsAbsoluteUri)
                     .Select(u => u!.Scheme)
                     .Distinct()
                     .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>
@@ -593,7 +593,7 @@
 
             return ConvertByteArrayToString(hash ?? []);
 
             async Task WriteDocumentAsync(TextWriter writer, CancellationToken token)
             {
                 var openApiJsonWriter = new OpenApiJsonWriter(writer, new() { Terse = true });
                 SerializeAsV31(openApiJsonWriter);
@@ -621,7 +621,7 @@
         /// <summary>
         /// Load the referenced <see cref="IOpenApiReferenceable"/> object from a <see cref="BaseOpenApiReference"/> object
         /// </summary>
         internal IOpenApiReferenceable? ResolveReference(BaseOpenApiReference? reference, bool useExternal, IOpenApiSchema? parentSchema)
         {
             if (reference == null)
             {
@@ -732,6 +732,9 @@
         /// <param name="format">The OpenAPI format to use during parsing.</param>
         /// <param name="settings">The OpenApi reader settings.</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic and parser errors are returned in the <see cref="ReadResult.Diagnostic"/>.
+        /// </remarks>
         public static ReadResult Load(MemoryStream stream,
                                       string? format = null,
                                       OpenApiReaderSettings? settings = null)
@@ -746,6 +749,9 @@
         /// <param name="settings">The OpenApi reader settings.</param>
         /// <param name="token">The cancellation token</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic and parser errors are returned in the <see cref="ReadResult.Diagnostic"/>.
+        /// </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 +765,9 @@
         /// <param name="settings">The OpenApi reader settings.</param>
         /// <param name="cancellationToken">Propagates information about operation cancelling.</param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic and parser errors are returned in the <see cref="ReadResult.Diagnostic"/>.
+        /// </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 +781,9 @@
         /// <param name="format"></param>
         /// <param name="settings"></param>
         /// <returns></returns>
+        /// <remarks>
+        /// OpenAPI semantic and parser errors are returned in the <see cref="ReadResult.Diagnostic"/>; a null or empty input string throws <see cref="ArgumentException"/>.
+        /// </remarks>
         public static ReadResult Parse(string input,
                                        string? format = null,
                                        OpenApiReaderSettings? settings = null)
@@ -930,7 +942,7 @@
                 {
                     Schemas.Add(id, schema);
                 }
-            } 
+            }
             base.Visit(schema);
         }
     }

src/Microsoft.OpenApi/Reader/OpenApiJsonReader.cs

@@ -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,9 @@
         /// <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 and parser errors are returned in the <see cref="ReadResult.Diagnostic"/>.
+        /// </remarks>
         public ReadResult Read(MemoryStream input,
                                Uri location,
                                OpenApiReaderSettings settings)
@@ -32,16 +35,16 @@
 
             JsonNode? jsonNode;
             var diagnostic = new OpenApiDiagnostic();
             settings ??= new OpenApiReaderSettings();
 
             // Parse the JSON text in the stream into JsonNodes
             try
             {
                 jsonNode = JsonNode.Parse(input) ?? throw new InvalidOperationException($"Cannot parse input stream, {nameof(input)}.");
             }
-            catch (JsonException ex)
+            catch (Exception ex) when (ex is JsonException or InvalidOperationException)
             {
-                diagnostic.Errors.Add(new OpenApiError($"#line={ex.LineNumber}", $"Please provide the correct format, {ex.Message}"));
+                diagnostic.Errors.Add(CreateOpenApiError(ex, true));
                 diagnostic.Format = OpenApiConstants.Json;
                 return new ReadResult
                 {
@@ -60,6 +63,10 @@
         /// <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 +98,7 @@
             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 +108,7 @@
                     {
                         diagnostic.Warnings.Add(item);
                     }
-                }                
+                }
             }
             diagnostic.Format = OpenApiConstants.Json;
             return new()
@@ -119,6 +126,9 @@
         /// <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 and parser errors are returned in the <see cref="ReadResult.Diagnostic"/>.
+        /// </remarks>
         public async Task<ReadResult> ReadAsync(Stream input,
                                                 Uri location,
                                                 OpenApiReaderSettings settings,
@@ -136,9 +146,9 @@
                 jsonNode = await JsonNode.ParseAsync(input, cancellationToken: cancellationToken).ConfigureAwait(false) ??
                     throw new InvalidOperationException($"failed to parse input stream, {nameof(input)}");
             }
-            catch (JsonException ex)
+            catch (Exception ex) when (ex is JsonException or InvalidOperationException)
             {
-                diagnostic.Errors.Add(new OpenApiError($"#line={ex.LineNumber}", $"Please provide the correct format, {ex.Message}"));
+                diagnostic.Errors.Add(CreateOpenApiError(ex, true));
                 diagnostic.Format = OpenApiConstants.Json;
                 return new ReadResult
                 {
@@ -151,7 +161,10 @@
         }
 
         /// <inheritdoc/>
+        /// <remarks>
+        /// OpenAPI semantic and parser errors are returned in the <paramref name="diagnostic"/>.
+        /// </remarks>
         public T? ReadFragment<T>(MemoryStream input,
                                  OpenApiSpecVersion version,
                                  OpenApiDocument openApiDocument,
                                  out OpenApiDiagnostic diagnostic,
@@ -167,16 +180,26 @@
             {
                 jsonNode = JsonNode.Parse(input) ?? throw new InvalidOperationException($"Failed to parse stream, {nameof(input)}");
             }
-            catch (JsonException ex)
+            catch (Exception ex) when (ex is JsonException or InvalidOperationException)
             {
-                diagnostic = new();
-                diagnostic.Errors.Add(new($"#line={ex.LineNumber}", ex.Message));
+                diagnostic = new()
+                {
+                    Format = OpenApiConstants.Json,
+                };
+                diagnostic.Errors.Add(CreateOpenApiError(ex, false));
                 return default;
             }
 
             return ReadFragment<T>(jsonNode, version, openApiDocument, out diagnostic);
         }
 
+        private static OpenApiError CreateOpenApiError(Exception ex, bool includeFormatHint)
+        {
+            return ex is JsonException jsonException
+                ? new OpenApiError($"#line={jsonException.LineNumber}", includeFormatHint ? $"Please provide the correct format, {jsonException.Message}" : jsonException.Message)
+                : new OpenApiError(null, ex.Message);
+        }
+
         /// <inheritdoc/>
         public T? ReadFragment<T>(JsonNode input,
          OpenApiSpecVersion version,