Register x-oai specification extensions for OpenAPI 3.2 down-leveling

[mikekistler]

This PR registers seven x-oai-* specification extensions that are produced by the Microsoft.OpenApi library when serializing OpenAPI 3.2 features to OpenAPI 3.0 or 3.1 documents. These extensions allow round-tripping of 3.2 fields through older spec versions.

Extensions added

Extension	Object	3.2 native field
x-oai-additionalOperations	Path Item	additionalOperations
x-oai-name	Server	name
x-oai-deprecated	Security Scheme	deprecated
x-oai-itemSchema	Media Type	itemSchema
x-oai-itemEncoding	Media Type	itemEncoding
x-oai-prefixEncoding	Media Type	prefixEncoding
x-oai-deviceAuthorizationUrl	OAuth Flow	deviceAuthorizationUrl

All fall under the existing oai namespace which is reserved for uses defined by the OpenAPI Initiative.

Context

The Microsoft.OpenApi library uses the pattern of serializing OpenAPI 3.2 fields as x-oai-* extensions when the target version is 3.0 or 3.1. This enables tooling to preserve these values during round-trip processing even when the document uses an older OpenAPI version.

Source: https://github.com/microsoft/OpenAPI.NET/blob/main/src/Microsoft.OpenApi/Models/OpenApiPathItem.cs (and related model files)

[mikekistler]

Tagged @darrelmiller for review because Copilot told me:

• The x-oai-* extensions fall under the already-registered oai namespace (owned by DarrelMiller/OAI).
• You may want to coordinate with the OAI since x-oai-* is their reserved namespace — the PR might need their sign-off or be submitted by them directly.

[karenetheridge]

Given that Microsoft != OpenAPI Initiative, why was this namespace selected for these extensions?

[ralfhandl]

Given that Microsoft != OpenAPI Initiative, why was this namespace selected for these extensions?

Because the extensions are not MSFT-specific, they are OAS-specific:

These extensions allow round-tripping of 3.2 fields through older spec versions.

I see Mike acting as a TSC member registering useful OAI specification extensions, and the MSFT tool just happens to be the first to support them.

[ralfhandl]

In general:

• List all objects where new key words can appear (even if the MSFT tool doesn't support all of them yet)
• Mention the corresponding OAS 3.2 keyword

[ralfhandl]

Suggested change

	The `x-oai-additionalOperations` extension represents HTTP method operations that are not part of the standard set defined by the target OpenAPI version. For example, the HTTP QUERY method is not a standard operation in OpenAPI 3.0 or 3.1, so it is serialized under this extension.
	The `x-oai-additionalOperations` extension represents operations for HTTP methods that are not part of the standard set defined by the Path Item Object of the target OpenAPI version. For example, the HTTP QUERY method has no standard operation in OpenAPI 3.0 or 3.1, so it is serialized under this extension.

[ralfhandl]

Suggested change

	In OpenAPI 3.2, this becomes the native `deprecated` field on Security Scheme Objects.

[ralfhandl]

Suggested change

	In OpenAPI 3.2, this becomes the native `deviceAuthorization` field on OAuth Flow Objects.

[ralfhandl]

Suggested change

	objects: [ "mediaTypeObject" ]
	objects: [ "mediaTypeObject", "encodingObject" ]

Why are we using lowerCamelCase for the object names? The section headings in the prose specification use Separate Capitalized Words, and the section anchors use kebab-case.

[ralfhandl]

Suggested change

	In OpenAPI 3.2, this becomes the native `itemEncoding` field on Media Type Objects and Encoding Objects.