Skip to content

fix: aligns exception and diagnostics behaviour across the API surface #3078

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 18 commits into
base: main
Choose a base branch
from
Draft

fix: aligns exception and diagnostics behaviour across the API surface #3078

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
ef390a8
Initial plan
Copilot Sep 10, 2026
3b67916
fix(reader): document parser-level exceptions
Copilot Sep 10, 2026
d5b8c30
fix(reader): document parser exceptions with exception tags
Copilot Sep 11, 2026
a350880
test(reader): cover empty factory inputs
Copilot Sep 11, 2026
23d99b9
fix(reader): return diagnostics for empty factory inputs
Copilot Sep 11, 2026
ef16deb
style(reader): format diagnostic handling changes
Copilot Sep 11, 2026
f07d8a2
test(reader): align empty input expectations
Copilot Sep 11, 2026
4f0a022
fix(reader): return diagnostic for empty streams
Copilot Sep 11, 2026
9d85c49
style(reader): format empty stream tests
Copilot Sep 11, 2026
a53b3f2
chore: applies review suggestion
baywet Sep 11, 2026
83e8420
chore: applies review suggestion
baywet Sep 11, 2026
aed0226
tests: Rename test method for clarity
baywet Sep 11, 2026
909c1ab
tests: Rename test method to LoadEmptyMemoryStreamReturnsDiagnostic
baywet Sep 11, 2026
4459bd5
chore: formatting
baywet Sep 11, 2026
53acb46
chore: formatting
baywet Sep 11, 2026
5dac4d1
docs: Update XML remarks for OpenApiModelFactory
baywet Sep 11, 2026
a46ac25
fix(reader): return diagnostics for null JSON roots
Copilot Sep 11, 2026
62c0de4
chore: addresses review feedback
baywet Sep 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
fix(reader): document parser exceptions with exception tags 
Co-authored-by: baywet <[email protected]>
  • Loading branch information
@baywet
Copilot and baywet authored Sep 11, 2026
commit d5b8c30aae9206b352713492ea383e25246aa854
12 changes: 6 additions & 6 deletions src/Microsoft.OpenApi.YamlReader/OpenApiYamlReader.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,9 @@ 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.
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
/// </remarks>
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
Comment thread
baywet marked this conversation as resolved.
Outdated
public async Task<ReadResult> ReadAsync(Stream input,
Uri location,
OpenApiReaderSettings settings,
Expand Down Expand Up @@ -100,9 +100,9 @@ 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.
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
/// </remarks>
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
public ReadResult Read(MemoryStream input,
Uri location,
OpenApiReaderSettings settings)
Expand Down Expand Up @@ -203,9 +203,9 @@ 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.
/// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>.
/// </remarks>
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a fragment is created.</exception>
public T? ReadFragment<T>(MemoryStream input,
OpenApiSpecVersion version,
OpenApiDocument openApiDocument,
Expand Down
15 changes: 9 additions & 6 deletions src/Microsoft.OpenApi/Interfaces/IOpenApiReader.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,10 @@ public interface IOpenApiReader
/// <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.
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
/// </remarks>
Comment thread
baywet marked this conversation as resolved.
Comment thread
baywet marked this conversation as resolved.
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
Comment thread
baywet marked this conversation as resolved.
Outdated
Task<ReadResult> ReadAsync(Stream input, Uri location, OpenApiReaderSettings settings, CancellationToken cancellationToken = default);

/// <summary>
Expand All @@ -36,9 +37,10 @@ public interface IOpenApiReader
/// <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.
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
/// </remarks>
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
ReadResult Read(MemoryStream input, Uri location, OpenApiReaderSettings settings);

/// <summary>
Expand All @@ -51,9 +53,10 @@ public interface IOpenApiReader
/// <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.
/// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>.
/// </remarks>
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a fragment is created.</exception>
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a fragment is created.</exception>
T? ReadFragment<T>(MemoryStream input, OpenApiSpecVersion version, OpenApiDocument openApiDocument, out OpenApiDiagnostic diagnostic, OpenApiReaderSettings? settings = null) where T : IOpenApiElement;
}
}
20 changes: 12 additions & 8 deletions src/Microsoft.OpenApi/Models/OpenApiDocument.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -311,7 +311,7 @@
/// <summary>
/// Serialize <see cref="OpenApiDocument"/> to OpenAPI object V2.0.
/// </summary>
public void SerializeAsV2(IOpenApiWriter writer)

Check warning on line 314 in src/Microsoft.OpenApi/Models/OpenApiDocument.cs

View workflow job for this annotation

GitHub Actions / Build 

Refactor this method to reduce its Cognitive Complexity from 31 to the 15 allowed.
{
Utils.CheckArgumentNull(writer);

Expand Down Expand Up @@ -460,7 +460,7 @@
return server.ReplaceServerUrlVariables([]);
}

private static void WriteHostInfoV2(IOpenApiWriter writer, IList<OpenApiServer>? servers)

Check warning on line 463 in src/Microsoft.OpenApi/Models/OpenApiDocument.cs

View workflow job for this annotation

GitHub Actions / Build 

Refactor this method to reduce its Cognitive Complexity from 21 to the 15 allowed.
{
if (servers == null || !servers.Any())
{
Expand Down Expand Up @@ -522,14 +522,14 @@
UriFormat.SafeUnescaped,
StringComparison.OrdinalIgnoreCase) ==
0 && u.IsAbsoluteUri)
.Select(u => u!.Scheme)

Check warning on line 525 in src/Microsoft.OpenApi/Models/OpenApiDocument.cs

View workflow job for this annotation

GitHub Actions / Build 

Remove this null-forgiving operator; the compiler already knows this expression is not null here.
.Distinct()
.ToList();

// schemes
writer.WriteOptionalCollection(OpenApiConstants.Schemes, schemes, (w, s) =>
{
if (!string.IsNullOrEmpty(s) && s is not null)

Check warning on line 532 in src/Microsoft.OpenApi/Models/OpenApiDocument.cs

View workflow job for this annotation

GitHub Actions / Build 

Change this condition so that it does not always evaluate to 'True'.
Comment thread
baywet marked this conversation as resolved.
Dismissed
Comment thread
baywet marked this conversation as resolved.
Dismissed
{
w.WriteValue(s);
}
Expand Down Expand Up @@ -593,7 +593,7 @@

return ConvertByteArrayToString(hash ?? []);

async Task WriteDocumentAsync(TextWriter writer, CancellationToken token)

Check warning on line 596 in src/Microsoft.OpenApi/Models/OpenApiDocument.cs

View workflow job for this annotation

GitHub Actions / Build 

Remove this unused method parameter 'token'.
{
var openApiJsonWriter = new OpenApiJsonWriter(writer, new() { Terse = true });
SerializeAsV31(openApiJsonWriter);
Expand Down Expand Up @@ -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)

Check warning on line 624 in src/Microsoft.OpenApi/Models/OpenApiDocument.cs

View workflow job for this annotation

GitHub Actions / Build 

Refactor this method to reduce its Cognitive Complexity from 24 to the 15 allowed.
{
if (reference == null)
{
Expand Down Expand Up @@ -733,9 +733,10 @@
/// <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.
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
/// </remarks>
Comment thread
baywet marked this conversation as resolved.
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
Comment thread
baywet marked this conversation as resolved.
Outdated
public static ReadResult Load(MemoryStream stream,
string? format = null,
OpenApiReaderSettings? settings = null)
Expand All @@ -751,9 +752,10 @@
/// <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.
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
/// </remarks>
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
public static async Task<ReadResult> LoadAsync(string url, OpenApiReaderSettings? settings = null, CancellationToken token = default)
{
return await OpenApiModelFactory.LoadAsync(url, settings, token).ConfigureAwait(false);
Expand All @@ -768,9 +770,10 @@
/// <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.
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
/// </remarks>
Comment thread
baywet marked this conversation as resolved.
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
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);
Expand All @@ -785,9 +788,10 @@
/// <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.
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
/// </remarks>
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
/// <exception cref="OpenApiReaderException">Thrown when syntax-level YAML errors are detected before a <see cref="ReadResult"/> is created.</exception>
public static ReadResult Parse(string input,
string? format = null,
OpenApiReaderSettings? settings = null)
Expand Down Expand Up @@ -890,10 +894,10 @@

private static OpenApiOperation? GetOperationByIdFromPathItems(IDictionary<string, IOpenApiPathItem> pathItems, string operationId)
{
foreach (var pathItem in pathItems.Values)

Check warning on line 897 in src/Microsoft.OpenApi/Models/OpenApiDocument.cs

View workflow job for this annotation

GitHub Actions / Build 

Loop should be simplified by calling Select(pathItem => pathItem.Operations))
{
if (pathItem.Operations is null) continue;
foreach (var operation in pathItem.Operations.Values)

Check warning on line 900 in src/Microsoft.OpenApi/Models/OpenApiDocument.cs

View workflow job for this annotation

GitHub Actions / Build 

Loops should be simplified using the "Where" LINQ method
{
if (string.Equals(operation.OperationId, operationId, StringComparison.Ordinal))
return operation;
Expand Down
12 changes: 6 additions & 6 deletions src/Microsoft.OpenApi/Reader/OpenApiJsonReader.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ public class OpenApiJsonReader : IOpenApiReader
/// <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.
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
/// </remarks>
Comment thread
baywet marked this conversation as resolved.
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
Comment thread
baywet marked this conversation as resolved.
Outdated
public ReadResult Read(MemoryStream input,
Uri location,
OpenApiReaderSettings settings)
Expand Down Expand Up @@ -128,9 +128,9 @@ public ReadResult Read(JsonNode jsonNode,
/// <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.
/// OpenAPI semantic errors are returned in the <see cref="ReadResult.Diagnostic"/>.
/// </remarks>
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a <see cref="ReadResult"/> is created.</exception>
public async Task<ReadResult> ReadAsync(Stream input,
Uri location,
OpenApiReaderSettings settings,
Expand Down Expand Up @@ -164,9 +164,9 @@ 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.
/// OpenAPI semantic errors are returned in the <paramref name="diagnostic"/>.
/// </remarks>
Comment thread
baywet marked this conversation as resolved.
/// <exception cref="System.Text.Json.JsonException">Thrown when syntax-level JSON errors are detected before a fragment is created.</exception>
public T? ReadFragment<T>(MemoryStream input,
OpenApiSpecVersion version,
OpenApiDocument openApiDocument,
Expand Down
Loading