René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"OpenAPI 3.2: `oauth2MetadataUrl` Missing from `Microsoft.OpenApi.OpenApiSecurityScheme`","articleBody":"## Summary\n\n`Microsoft.OpenApi` can serialize OpenAPI **3.2** documents, but the **Security Scheme Object** is missing support for the OpenAPI 3.2 field:\n\n- `oauth2MetadataUrl` (type: `string`, format: `uri`, applies to `type: oauth2`)\n\nThis prevents consumers from producing spec-complete OpenAPI 3.2 documents when describing OAuth2 servers using RFC 8414 metadata.\n\n## Spec Reference\n\nOpenAPI 3.2.0 adds `oauth2MetadataUrl` to the Security Scheme Object. citeturn0search0turn0search10\nThe field is defined as a URL to the OAuth2 authorization server metadata (RFC 8414). citeturn0search5turn0search2\n\n## Current Behavior\n\n`OpenApiSecurityScheme` does not expose a property for `oauth2MetadataUrl`, and the serializer does not emit it for OpenAPI 3.2 output.\n\nEven when using `SerializeAsV32`, the switch over `SecuritySchemeType` only handles:\n\n- `apiKey`: `name`, `in`\n- `http`: `scheme`, `bearerFormat`\n- `oauth2`: `flows`\n- `openIdConnect`: `openIdConnectUrl`\n\nThere is no native way to model and serialize `oauth2MetadataUrl` other than vendor extensions.\n\n## Expected Behavior\n\nWhen `Type == SecuritySchemeType.OAuth2` and the target spec version is **OpenAPI 3.2+**, the library should allow setting and serializing:\n\n```yaml\ncomponents:\n  securitySchemes:\n    oauth:\n      type: oauth2\n      oauth2MetadataUrl: https://idp.example.com/.well-known/oauth-authorization-server\n      flows:\n        clientCredentials:\n          tokenUrl: https://idp.example.com/oauth/token\n          scopes: {}\n```\n\n## Proposed API Change\n\nAdd a nullable `Uri` property to `OpenApiSecurityScheme`:\n\n```csharp\npublic Uri? OAuth2MetadataUrl { get; set; }\n```\n\n### Serialization (OpenAPI 3.2+ only)\n\nIn `SerializeInternal(...)`, under `case SecuritySchemeType.OAuth2:` write the property **before/after** flows:\n\n```csharp\nif (version \u003e= OpenApiSpecVersion.OpenApi3_2)\n{\n    writer.WriteProperty(\"oauth2MetadataUrl\", OAuth2MetadataUrl?.ToString());\n}\nwriter.WriteOptionalObject(OpenApiConstants.Flows, Flows, callback);\n```\n\n### Parsing / Reading\n\nIf the library includes readers/deserializers for security schemes, they should also recognize `oauth2MetadataUrl` when parsing OpenAPI 3.2 documents into `OpenApiSecurityScheme`.\n\n## Why This Matters\n\nOAuth2 Authorization Server Metadata (RFC 8414) is widely used to publish endpoints and capabilities. OpenAPI 3.2 explicitly supports linking to that metadata; without this field, OpenAPI 3.2 documents generated with `Microsoft.OpenApi` cannot fully represent the spec-defined OAuth2 security scheme information. citeturn0search5turn0search7\n\n## Workarounds Today\n\n- Use `Extensions[\"x-oauth2MetadataUrl\"] = ...` (non-standard)\n- Put the URL in `description` (lossy / not machine-readable)\n\n## Request\n\nPlease add first-class support for `oauth2MetadataUrl` to `OpenApiSecurityScheme` and include it in OpenAPI 3.2 serialization/parsing for OAuth2 security schemes.\n\nThank you!\n","author":{"url":"https://github.com/mdaneri","@type":"Person","name":"mdaneri"},"datePublished":"2026-01-20T21:12:17.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/2694/OpenAPI.NET/issues/2694"}