feat: adds support for external anchor and relative id

[Vincent Biret (baywet)]

follow up to #145

[learn-build-service-prod]

Learn Build status updates of commit 0d65d84:

✅ Validation status: passed

File	Status	Preview URL	Details
OpenAPI/OpenAPI.NET/references-openapi.md	✅Succeeded

For more details, please refer to the build report.

[Abdullah Alaqeel (aqeelat)]

Vincent Biret (@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.

[Vincent Biret (baywet)]

Thank you for the comments!

1. Missing: $ref siblings in 3.1

Would you mind starting a PR to address this please?

[Abdullah Alaqeel (aqeelat)]

Thank you for the comments!

1. Missing: $ref siblings in 3.1

Would you mind starting a PR to address this please?

Vincent Biret (@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.

[learn-build-service-prod]

Learn Build status updates of commit f01ab39:

✅ Validation status: passed

File	Status	Preview URL	Details
OpenAPI/OpenAPI.NET/references-openapi.md	✅Succeeded

For more details, please refer to the build report.

[learn-build-service-prod]

Learn Build status updates of commit 877d002:

✅ Validation status: passed

File	Status	Preview URL	Details
OpenAPI/OpenAPI.NET/references-openapi.md	✅Succeeded

For more details, please refer to the build report.

[learn-build-service-prod]

Learn Build status updates of commit ab68318:

✅ Validation status: passed

File	Status	Preview URL	Details
OpenAPI/OpenAPI.NET/references-openapi.md	✅Succeeded

For more details, please refer to the build report.