Sync open source content 🐝 (from 5a9255a4a3172a6abd31216835ab1dab25fcde4c)

Author: beezythebot

docs/customize/data-model/enums.mdx

@@ -37,6 +37,23 @@ Resulting enum values will be `FOO_LOWER`, `FOO_MIXED`, and `FOO_UPPER`.
 
 If unique names cannot be resolved, a validation error will prompt you to resolve conflicts, potentially using the `x-speakeasy-enums` extension.
 
+The recommended approach is to use the map format, which prevents length mismatch errors:
+
+```yaml
+schema:
+  type: integer
+  enum:
+    - 1
+    - 2
+    - 3
+  x-speakeasy-enums:
+    1: NOT_STARTED
+    2: IN_PROGRESS
+    3: COMPLETE
+```
+
+Alternatively, you can use the array format, but ensure the order in the enum array corresponds exactly to the custom names in the `x-speakeasy-enums` array:
+
 ```yaml
 schema:
   type: integer
@@ -50,8 +67,6 @@ schema:
     - COMPLETE
 ```
 
-Ensure the order in the enum array corresponds to the custom names in the `x-speakeasy-enums` array.
-
 ## Enum class naming
 
 Use the `x-speakeasy-name-override` attribute to customize enum class names:
@@ -279,7 +294,7 @@ Native enums need to be
 imported from within the SDK but benefit from having members with clear names
 and documentation on each. This is particularly useful when you define enums
 that do not map well to spoken language, such as `enum: ["+", "_", "*", "!"]`.
-Using the `x-speakeasy-enums` extension will allow you to customise the name of
+Using the `x-speakeasy-enums` extension will allow you to customize the name of
 each native enum member.
 
 In TypeScript and Python, native enums are nominally typed, which means that
@@ -305,9 +320,9 @@ components:
         - 2
         - 3
       x-speakeasy-enums:
-        - Red
-        - Green
-        - Blue
+        1: Red
+        2: Green
+        3: Blue
 ```
 
 In this case, the `BackgroundColor` enum will be generated as a native enum in

docs/speakeasy-reference/extensions.mdx

@@ -14,7 +14,7 @@ import { Table } from "@/mdx/components";
     { extension: "x-speakeasy-group", description: "Defines custom namespaces when adding this property to any operation in the OpenAPI spec. If added, the tags for that method will be ignored" },
     { extension: "x-speakeasy-ignore", description: "Exclude certain methods from your SDK with this extension." },
     { extension: "x-speakeasy-include", description: "Can be used to force the generation of an unused or orphaned schema from the `components` section inside the main document." },
-    { extension: "x-speakeasy-enums", description: "Use this extension to control generated enum members by providing alternative names for each value in the enum field." },
+    { extension: "x-speakeasy-enums", description: "Use this extension to control generated enum members by providing alternative names for each value in the enum field. The recommended map format prevents length mismatch errors that can occur with the array format." },
     { extension: "x-speakeasy-enum-format", description: "Customize how the enum type is generated for the schema, either `enum` for a native enum type or `union` for a union of values." },
     { extension: "x-speakeasy-retries", description: "Enable retries globally or on a per-request basis. A backoff strategy is applied to specified status codes." },
     { extension: "x-speakeasy-pagination", description: "Use to customize offset- or cursor-based pagination rules for each API operation." },

openapi/schemas/enums.md

@@ -166,29 +166,9 @@ In this `oneOf` solution, the client has to supply the label and the value, defe
 
 If you are using OpenAPI 3.0 or want to use `enum`, you can use an extension attribute to give labels to enum values. Different code generators and OpenAPI tools use different extension names. Below are examples using the Speakeasy extension field:
 
-### Array Format (Full Coverage)
+### Map Format (Recommended)
 
-The traditional array format provides names for all enum values in order:
-
-```yaml
-components:
-  schemas:
-    CupSize:
-      description: Size of the cup to order, represented by a numeric code with a corresponding label.
-      type: integer
-      enum:
-        - 10
-        - 20
-        - 50
-      x-speakeasy-enums:
-        - Small
-        - Medium
-        - Large
-```
-
-### Map Format (Full or Partial Coverage)
-
-The map format allows you to specify custom names for specific enum values. This is useful when you want to provide names for only some values or when the enum values don't follow a predictable pattern:
+The map format is the recommended approach for `x-speakeasy-enums` as it prevents length mismatch errors and allows flexible naming of enum values. You can specify custom names for specific enum values without worrying about array ordering:
 
 ```yaml
 components:
@@ -231,6 +211,28 @@ components:
 
 Both string and integer enums support the map format. When using partial coverage, enum values without explicit mappings will use their original values as names in the generated code.
 
+### Array Format (Alternative)
+
+The array format provides names for all enum values in order, but requires that the array length matches the enum values exactly to prevent errors:
+
+```yaml
+components:
+  schemas:
+    CupSize:
+      description: Size of the cup to order, represented by a numeric code with a corresponding label.
+      type: integer
+      enum:
+        - 10
+        - 20
+        - 50
+      x-speakeasy-enums:
+        - Small
+        - Medium
+        - Large
+```
+
+**Note**: The array format requires the order in the enum array to correspond exactly to the custom names in the `x-speakeasy-enums` array. If the lengths don't match, this will cause errors. For this reason, the map format is recommended as the safer approach.
+
 Or you can use a simple text description to prioritize human understanding over tooling support:
 
 ```yaml