Learn Build status updates of commit 0d65d84:

✅ Validation status: passed

For more details, please refer to the build report.

@baywet Great to see this documentation published. The taxonomy of Reference Objects vs JSON Schema $ref is the right framing.

A few observations on the broader page (not specific to this PR's diff):

1. Missing: $ref siblings in 3.1

The biggest gap. OpenAPI 3.0 ignores siblings next to $ref; 3.1 allows them and they take precedence over target values via the existing Reference.X ?? Target?.X getters. Users transitioning from 3.0 to 3.1 need to know this. It belongs in the "JSON Schema $refs in OpenAPI descriptions" section.

2. Version comparison table

A quick-reference table showing what's supported across 3.0 / 3.1 / 3.2 would help users scanning for their target version: $ref siblings, $anchor resolution, $dynamicRef/$dynamicAnchor, relative $id, external fragments, etc.

3. $dynamicAnchor/$dynamicRef section header

The body text is accurate ("exposed as properties... but dynamic reference resolution is not currently implemented"), but the section header [Not currently supported] is misleading. It implies the keywords aren't handled at all. Since #2896, they're fully parsed, stored, and round-tripped through serialization. Consider [Resolution not yet implemented] or similar to distinguish from "not supported at all." This section will also need updating once #2913 (resolution) merges.

Thank you for the comments!

1. Missing: $ref siblings in 3.1

Would you mind starting a PR to address this please?

Thank you for the comments!

1. Missing: $ref siblings in 3.1

Would you mind starting a PR to address this please?

@baywet I was gonna, but then discovered another issue (microsoft/OpenAPI.NET#2919).

Ya know, I'll still open the PR as draft, with the current status, and include in the description what will change once the issue is addressed.