Sync open source content 🐝 (from 0e3b439710632d865d36af29459a4bf056c97d56)

Author: beezythebot

docs/sdks/customize/data-model/oneof-schemas.mdx

@@ -456,6 +456,35 @@ Will result in these response types:
 ]}
 />
 
+## Discriminator display names
+
+When a `oneOf` schema uses a `discriminator` with mapping keys that contain special characters (e.g., `$login`, `$challenge`), the generated SDK identifiers can become unwieldy. For example, a `$login` key produces a Go function named `CreateRiskDollarLogin` because the `$` character is sanitized to `Dollar`.
+
+The `x-speakeasy-discriminator` extension provides clean display names for discriminator mapping keys while preserving the original values for JSON serialization.
+
+```yaml
+components:
+  schemas:
+    RiskAssessment:
+      oneOf:
+        - $ref: "#/components/schemas/LoginRiskRequest"
+        - $ref: "#/components/schemas/ChallengeRiskRequest"
+      discriminator:
+        propertyName: type
+        mapping:
+          $login: "#/components/schemas/LoginRiskRequest"
+          $challenge: "#/components/schemas/ChallengeRiskRequest"
+      x-speakeasy-discriminator:
+        $login: login
+        $challenge: challenge
+```
+
+In this example, the generated Go SDK uses `CreateRiskAssessmentLogin` and `CreateRiskAssessmentChallenge` as function names instead of `CreateRiskAssessmentDollarLogin` and `CreateRiskAssessmentDollarChallenge`. The wire values (`"$login"` and `"$challenge"`) remain unchanged during JSON serialization.
+
+The extension maps each discriminator mapping key to a display name. Only keys that need renaming must be included. Any key not listed in `x-speakeasy-discriminator` retains its original name for identifier generation.
+
+This extension is supported in Go, Terraform, and mock server targets.
+
 ### Splitting `oneOf` schema types
 
 By defining similar operations with aligned but different schemas, you can apply `x-speakeasy-type-override: any` for untyped operations and use `oneOf` to define stricter types in others. This allows you to use methods like `DoSomething(StrictObject{...})` alongside `DoSomethingUntyped({...})`, providing flexibility across SDK methods based on the required schema type.

docs/speakeasy-reference/extensions.mdx

@@ -35,7 +35,8 @@ import { Table } from "@/mdx/components";
     { extension: "x-speakeasy-mcp", description: "Customize how API operations are exposed as MCP tools with properties for disabled, name, title, scopes, description, and behavioral hints (destructiveHint, idempotentHint, openWorldHint, readOnlyHint)." },
     { extension: "x-speakeasy-overridable-scopes", description: "Allow end users to override OAuth 2.0 scopes at runtime for the `clientCredentials` flow by adding an optional `scopes` field to the security model." },
     { extension: "x-speakeasy-param-encoding-override", description: "When set with a value of `allowReserved`, path parameters will appear in a request URL with reserved characters `:/?#[]@!$&'()*+,;=` unencoded." },
-    { extension: "x-speakeasy-token-endpoint-additional-properties", description: "Define additional properties for OAuth token endpoint requests, allowing generated SDKs to handle custom fields like audience parameters." }
+    { extension: "x-speakeasy-token-endpoint-additional-properties", description: "Define additional properties for OAuth token endpoint requests, allowing generated SDKs to handle custom fields like audience parameters." },
+    { extension: "x-speakeasy-discriminator", description: "Provide clean display names for discriminator mapping keys that contain special characters, improving generated identifier names while preserving wire values." }
   ]}
   columns={[
     { key: "extension", header: "Extension" },