# The gen.yaml file reference
Source: https://speakeasy.com/docs/speakeasy-reference/generation/gen-yaml

import { Callout } from "@/mdx/components";



<Callout title="Tip" type="info">

For most use cases, the `speakeasy configure` command is the recommended means of interacting with the Speakeasy `gen.yaml` file. The `speakeasy configure` command has subcommands for configuring sources, targets, GitHub workflow setups, and package publications. All new targets created using `speakeasy quickstart` automatically generate workflow files in the `.speakeasy/` folder in the root of the target directory.

</Callout>

The `gen.yaml` file has several sections:

- The `generation` section is essential for SDK configuration
- The `management` and `features` sections are maintained by Speakeasy and should not be edited
- The final section is for language-specific configuration (for more information, see the language-specific configuration docs)

## Generation

### configVersion

The currently supported version of the Speakeasy `gen.yaml` configuration file is `2.0.0`. Older versions will be automatically upgraded when encountered.

```yaml
configVersion: 2.0.0
```

### generation

The `generation` section of the `gen.yaml` file supports configuration that is relevant to all SDK targets. If a value isn&apos;t configured here, and it has a default value, then that value will be added automatically on the next generation. For more information about SDK generation and targets, see our [core concepts documentation](/docs/sdks/core-concepts#sdk-generation).

```yaml
generation:
  sdkClassName: speakeasybar
  maintainOpenAPIOrder: true
  usageSnippets:
    optionalPropertyRendering: withExample
  devContainers:
    enabled: true
    schemaPath: "path/to/schema"
  useClassNamesForArrayFields: true
  fixes:
    nameResolutionDec2023: true
    parameterOrderingFeb2024: true
    requestResponseComponentNamesFeb2024: true
    securityFeb2025: true
  auth:
    OAuth2ClientCredentialsEnabled: true
  inferSSEOverload: true
```

### sdkClassName

Defines the class name of the main imported class in the generated SDK.

```yaml
  sdkClassName: speakeasybar
```

### maintainOpenAPIOrder

Determines whether the parameters, properties, operations, etc., are maintained in the same order they appear in the OpenAPI document. If set to `false`, these elements are sorted alphabetically.

```yaml
  maintainOpenAPIOrder: true
```

### usageSnippets

The options for `optionalPropertyRendering` include `always`, `never`, and `withExample`, which renders optional properties only when an example is present in the OpenAPI document.

```yaml
  usageSnippets:
    optionalPropertyRendering: withExample
```

### devContainers

Enables or disables the use of development containers, and specifies the schema path. For more information about development containers and SDK sandboxes, see our [SDK sandbox documentation](/docs/manage/sdk-sandbox).

```yaml
  devContainers:
    enabled: true
    schemaPath: "path/to/schema"
```

### useClassNamesForArrayFields

When set to true, array fields use class names instead of child schema types.

```yaml
  useClassNamesForArrayFields: true
```

### fixes

Includes specific fixes or features to be applied during SDK generation to avoid breaking changes.

- `nameResolutionDec2023`: **Disabling not recommended**. Enables changes introduced in December 2023 for improved name resolution, defaults to `true` for new SDKs. For older SDKs, setting `true` is recommended, but will be a breaking change.
- `parameterOrderingFeb2024`: **Disabling not recommended**. Enables changes introduced in February 2024 to respect the order of parameters in the OpenAPI document where possible, defaults to `true` for new SDKs. For older SDKs, setting `true` is recommended, but will be a breaking change.
- `requestResponseComponentNamesFeb2024`: **Disabling not recommended**. Enables changes introduced in February 2024 to use the name of parent request/response components where possible, defaults to `true` for new SDKs. For older SDKs, setting `true` is recommended, but will be a breaking change.
- `securityFeb2025`: **Disabling not recommended**. Enables changes introduced in February 2025 to the security handling at both the global and operation level, particularly needed to enable per-operation OAuth2 flows. Defaults to `true` for new SDKs. For older SDKs, setting `true` is recommended, but will be a breaking change.

```yaml
  fixes:
    nameResolutionDec2023: true
    parameterOrderingFeb2024: true
    requestResponseComponentNamesFeb2024: true
    securityFeb2025: true
```

### auth

- `OAuth2ClientCredentialsEnabled`: Enables the generation of code for handling OAuth 2.0 client credentials for authentication, where possible. **Business and Enterprise plans only**.
- `hoistGlobalSecurity`: When `true` (default), Speakeasy identifies the most commonly used operation-level security scheme and hoists it to global security if no global security is defined. Set to `false` to disable this behavior.

For detailed information about authentication configuration, see our [guide to customizing security and authentication](/docs/customize/authentication/configuration).

```yaml
  auth:
    OAuth2ClientCredentialsEnabled: true
    hoistGlobalSecurity: true
```

#### Disable security hoisting

Set `hoistGlobalSecurity` to `false` to opt out:

```yaml
auth:
  hoistGlobalSecurity: false
```

### inferSSEOverload

Enables the generation of method overloads for Python SDKs to provide better type safety for Server-Sent Events (SSE) operations. When set to `true` (default), Speakeasy will automatically create overloaded methods for operations that meet specific criteria:

- The operation has a request body
- The request body contains a `stream` field (boolean type)
- The operation has exactly two responses: one `text/event-stream` and one `application/json`

This feature is currently Python-specific, with support for other languages planned for future releases.

```yaml
  inferSSEOverload: true
```

### baseServerUrl

Used to declare the base server URL. It overrides the `servers` field in the OpenAPI document if present, or provides a server URL if the `servers` field is absent.

```yaml
  baseServerUrl: "speakeasy.bar/public/api/"
```

### requestBodyFieldName

Changes the field name of the request body parameter from using a flattened request object name to using a generic name. When set to `body`, the request body parameter will be named `body` instead of using the flattened request object name. This provides a more consistent and predictable parameter naming convention across your SDK methods.

```yaml
  requestBodyFieldName: body
```

### mockServer

Disables the generation and use of a mock HTTP server with generated tests.

```yaml
  mockServer:
    disabled: true
```

### schemas

Configuration for how OpenAPI schemas are processed during SDK generation.

#### allOfMergeStrategy

Controls how `allOf` constructs in OpenAPI schemas are merged. For detailed information about merge strategies, see the [allOf schemas documentation](/docs/customize/data-model/allof-schemas).

- `deepMerge` (default for new SDKs): Recursively merges nested properties within objects, preserving properties from all schemas in the `allOf` array.
- `shallowMerge` (legacy behavior): Replaces entire property blocks when merging, which can result in lost properties from earlier schemas.

```yaml
  schemas:
    allOfMergeStrategy: deepMerge
```

### multipartArrayFormat

Controls how arrays are serialized in multipart/form-data requests. This option determines whether array field names include brackets (`[]`) or use the RFC 7578-compliant approach of repeating the same field name.

- `legacy` (default for existing SDKs): Appends `[]` to array field names (e.g., `files[]`). This maintains backward compatibility with existing SDKs but is non-compliant with RFC 7578.
- `standard` (default for new SDKs): Uses the RFC 7578-compliant format by repeating the same field name for each array element (e.g., multiple `files` fields). This is the correct multipart/form-data encoding according to RFC 7578 Section 4.3.

```yaml
  multipartArrayFormat: standard
```

**Migration note**: Changing from `legacy` to `standard` is a breaking change. APIs expecting field names with `[]` suffixes will need to be updated to handle the RFC-compliant format.

### versioningStrategy

Controls how SDK versions are determined during generation. For more information about SDK versioning, see our [SDK versioning documentation](/docs/sdks/manage/versioning).

- `automatic` (default): Automatically bumps the SDK version based on changes to the OpenAPI spec, configuration, or generator version.
- `manual`: Uses the version specified in `gen.yaml` as-is without automatic bumping. Use this when you want full control over SDK versioning.

```yaml
  versioningStrategy: manual
```

When set to `manual`, the SDK version will only change when you explicitly update the `version` field in your language-specific configuration or use `speakeasy bump` commands.