Pull Request

Description

Fix the memory-allocation regression introduced by #3155 while preserving its full JSON pointer paths for nested schema references.

The new per-reference location construction exposed an existing imbalance in named-example location scopes: example locations accumulated across sibling operations, and each schema reference materialized that accumulated history. Balance those scopes and construct a location only when relative-pointer resolution needs it.

This is the independent main-branch port of the performance fixes in #3170, extended to the OpenAPI 3.2 reader available on main.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Other (please describe):

Related Issue(s)

Regression introduced by #3155. Corresponding 2.X fixes: #3170.

Changes Made

• Balance named-example location scopes with try/finally in the OpenAPI 3.0, 3.1, and 3.2 readers. Preserve example-specific diagnostic pointers and restore the caller's location when processing throws.
• Pass the parsing context to the shared reference-path helper; materialize its location only in the relative-pointer-resolution branch. Keep absolute-pointer comparison/caching behavior and the nested-reference fix unchanged.
• Add regression coverage for media-type and parameter examples across all three versions, including successful processing, propagated exceptions, and diagnostic errors.
• Refresh all description and empty-model benchmark reports in a separate chore commit.

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• All existing tests pass

Commands run from the new main-based worktree:

• dotnet test --project test\Microsoft.OpenApi.Readers.Tests\Microsoft.OpenApi.Readers.Tests.csproj -c Release - passed, 657 tests.
• dotnet test --project test\Microsoft.OpenApi.Tests\Microsoft.OpenApi.Tests.csproj -c Release -- --filter-class '*Reference*' - passed, 200 tests.
• dotnet build src\Microsoft.OpenApi\Microsoft.OpenApi.csproj -c Release --no-restore --nologo -v quiet - passed for netstandard2.0 and net8.0, zero warnings/errors.
• dotnet run -c Release, from performance\benchmark - passed, all 34 benchmarks completed: six description benchmarks and 28 empty-model benchmarks. Verified that every report contains measurements and that all empty-model allocation counts are unchanged.

Formatted the modified files in both changed projects using dotnet format. The full solution/coverage run and trimming validation were not run locally; CI performs those checks.

Checklist

• My code follows the code style of this project
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Versions applicability

• My change applies to the version 1.X of the library, if so PR link:
• My change applies to the version 2.X of the library, if so PR link: fix(v3): retain full JSON pointer path on OpenAPI 3.0 schema references (#3155) #3170
• My change applies to the version 3.X of the library, if so PR link: this PR, targeting main
• I have evaluated the applicability of my change against the other versions above.

See the contributing guidelines for more information about how patches are applied across multiple versions.

Additional Notes

No public API or documentation changes are required. Version 1.X applicability was not assessed as part of this main-targeted port.

Refreshed allocated memory per parse on .NET 8.0.34 / Windows ARM64:

These are cumulative managed allocations, not retained document size. Benchmark reports retain their actual machine/runtime metadata; timing comparisons against reports from other machines should not be interpreted as controlled speedup measurements.