Add support for document $self property (OAI 3.2.0)

[Copilot]

Summary

This PR implements support for the $self property added in OpenAPI 3.2.0, which provides a URI identifying the document itself. As specified in the OAI 3.2.0 specification, this property is serialized as a standard field in v3.2+ and as an extension (x-oai-$self) in earlier versions.

Changes

Property Definition

• Added Self property (Uri?) to OpenApiDocument class
• Added $self constant to OpenApiConstants
• Updated copy constructor to handle the new property

Serialization

The property serializes differently based on the OpenAPI version:

OpenAPI 3.2.0+

openapi: 3.2.0
$self: https://example.org/api/openapi.json
info:
  title: My API
  version: 1.0.0
paths: {}

OpenAPI 3.1.x and 3.0.x

openapi: 3.1.2
info:
  title: My API
  version: 1.0.0
paths: {}
x-oai-$self: https://example.org/api/openapi.json

Deserialization

• v3.2: Added deserialization support for native $self field via V32 deserializer
• v3.1: Added deserialization support for x-oai-$self extension via V31 deserializer (extension is properly extracted into the Self property and not left in the extensions dictionary)
• v3.0: Reads from x-oai-$self extension via V3 deserializer

Testing

Serialization Tests

• 3 tests in OpenApiDocumentTests.cs covering all OpenAPI versions (3.0, 3.1, 3.2)

Deserialization Tests

• V32: 2 tests for native $self property (YAML and JSON formats)
• V31: 1 test for x-oai-$self extension with verification that the property is moved to Self and not left in Extensions
• Created corresponding sample files for all deserialization tests

All 1281 tests pass with no regressions.

Notes

This implementation focuses on the property itself and does not include reference resolution updates, as specified in the issue requirements.

Fixes #8

Original prompt

---

This section details on the original issue you should resolve

<issue_title>add support for document $self property</issue_title>
<issue_description>OAI 3.2.0 adds a new $self property to the document object.

This property should be a Uri? and serialization/deserialization should be updated to account for the new property.

When serializing to OAI 3.1.0 or lower, the property should be prefixed with x-oai- as an exension.

We will NOT implement the updates to references resolution as part of this issue.</issue_description>

<agent_instructions>make sure you also update the public api export.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes #8

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[baywet]

@copilot You forgot to implement the deserialization changes in the following files:

• src/Microsoft.OpenApi/Reader/V31/OpenApiDocumentDeserializer.cs
• src/Microsoft.OpenApi/Reader/V32/OpenApiDocumentDeserializer.cs

Also move the unit tests introduced in test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentSelfPropertyTests.cs to test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs

[Copilot]

@copilot You forgot to implement the deserialization changes in the following files:

• src/Microsoft.OpenApi/Reader/V31/OpenApiDocumentDeserializer.cs
• src/Microsoft.OpenApi/Reader/V32/OpenApiDocum...

Done. Added deserialization support to both V31 and V32 deserializers and moved the tests to OpenApiDocumentTests.cs.

Changes in commit 82a4229:

• V32 deserializer: Added $self fixed field for native property support
• V31 deserializer: Added x-oai-$self pattern field handler for backward compatibility
• Moved all 3 test methods to OpenApiDocumentTests.cs
• Deleted OpenApiDocumentSelfPropertyTests.cs

All 1278 tests pass.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• example.org926f4f21-88e7-4dc5-bf88-6c529bb77844
  • Triggering command: /usr/share/dotnet/dotnet exec --runtimeconfig /home/REDACTED/work/OpenAPI.NET/OpenAPI.NET/test/Microsoft.OpenApi.Hidi.Tests/bin/Release/net8.0/Microsoft.OpenApi.Hidi.Tests.runtimeconfig.json --depsfile /home/REDACTED/work/OpenAPI.NET/OpenAPI.NET/test/Microsoft.OpenApi.Hidi.Tests/bin/Release/net8.0/Microsoft.OpenApi.Hidi.Tests.deps.json /home/REDACTED/work/OpenAPI.NET/OpenAPI.NET/test/Microsoft.OpenApi.Hidi.Tests/bin/Release/net8.0/testhost.dll --port 42661 --endpoint 127.0.0.1:042661 --role client --parentprocessid 4003 --telemetryoptedin false (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[baywet]

@copilot add additional unit tests for the deserialization of the new property.

[Copilot]

@copilot add additional unit tests for the deserialization of the new property.

Done. Added 3 deserialization unit tests in commit 91d3626:

V32 Tests (native $self property):

• ParseDocumentWithSelfPropertyFromYamlWorks - Tests YAML deserialization
• ParseDocumentWithSelfPropertyFromJsonWorks - Tests JSON deserialization

V31 Test (x-oai-$self extension):

• ParseDocumentWithSelfExtensionWorks - Tests YAML deserialization with extension, verifies property is moved to Self and not left in Extensions

Created corresponding sample files for testing. All 1281 tests pass.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• example.org926f4f21-88e7-4dc5-bf88-6c529bb77844
  • Triggering command: /usr/share/dotnet/dotnet exec --runtimeconfig /home/REDACTED/work/OpenAPI.NET/OpenAPI.NET/test/Microsoft.OpenApi.Hidi.Tests/bin/Release/net8.0/Microsoft.OpenApi.Hidi.Tests.runtimeconfig.json --depsfile /home/REDACTED/work/OpenAPI.NET/OpenAPI.NET/test/Microsoft.OpenApi.Hidi.Tests/bin/Release/net8.0/Microsoft.OpenApi.Hidi.Tests.deps.json /home/REDACTED/work/OpenAPI.NET/OpenAPI.NET/test/Microsoft.OpenApi.Hidi.Tests/bin/Release/net8.0/testhost.dll --port 42641 --endpoint 127.0.0.1:042641 --role client --parentprocessid 3974 --telemetryoptedin false (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)