# Go configuration options
Source: https://speakeasy.com/docs/speakeasy-reference/generation/go-config

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



This section details the available configuration options for the Go SDK. All configuration is managed in the `gen.yaml` file under the `go` section.

## Version and general configuration

```yml
go:
  version: 1.2.3
  modulePath: "github.com/my-company/company-go-sdk"
  sdkPackageName: "company"
```

<Table
  data={[
    {
      name: "version",
      required: "true",
      default: "0.0.1",
      description: "The current version of the SDK.",
    },
    {
      name: "modulePath",
      required: "true",
      default: "github.com/my-company/company-go-sdk",
      description:
        "Root module path. Use sdkPackageName to configure the package clause for the root module package. [Go Module Path documentation](https://go.dev/ref/mod#module-path).",
    },
    {
      name: "sdkPackageName",
      required: "true",
      default: "company",
      description:
        "Root module package name written in the package clause. Determines the package naming in consuming code if the modulePath does not end with a valid identifier. [Go Packages documentation](https://go.dev/ref/spec#Packages).",
    },
    {
      name: "packageName",
      required: "false",
      default: "",
      description:
        "Legacy combined root module path and SDK package naming. Use sdkPackageAlias to update SDK package import aliases in documentation while preserving major version compatibility, otherwise migrate to modulePath and sdkPackageName. [Go Module Path documentation](https://go.dev/ref/mod#module-path).",
    },
    {
      name: "sdkPackageAlias",
      required: "false",
      default: "openapi",
      description:
        "Root module package import alias for documentation. Use this to preserve compatibility if the SDK has already had a stable major version release with modulePath, packageName, or sdkPackageName, as the package clause determines package naming in consuming code if the import path does not end in a valid identifier. [Go Packages documentation](https://go.dev/ref/spec#Packages).",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Additional dependencies

```yml
go:
  additionalDependencies:
    axios: "0.21.0"
```

<Table
  data={[
    {
      name: "additionalDependencies",
      required: "false",
      default: "{}",
      description:
        "Add additional dependencies to include in the generated `go.mod`.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Retractions

You can use retractions to mark specific versions of your Go module as unsuitable for use. Each retraction requires a version and can optionally include a comment explaining why the version was retracted.

```yml
go:
  retractions:
    - version: v1.0.0
      comment: Published accidentally
    - version: v1.0.1
```

<Table
  data={[
    {
      name: "version",
      required: "true",
      default: "",
      description: "The version to retract. Must be a valid semantic version.",
    },
    {
      name: "comment",
      required: "false",
      default: "",
      description: "Optional comment explaining why the version was retracted.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Method and parameter management

```yml
go
  maxMethodParams: 4
  methodArguments: "require-security-and-request"
```

<Table
  data={[
    {
      name: "[maxMethodParams](/docs/customize/methods)",
      required: "false",
      default: "4",
      description:
        'The maximum number of parameters a method can have before the resulting SDK endpoint is no longer "flattened" and an input object is created. `0` will use input objects always. Must match the regex pattern `/^\\d+$/`.',
    },
    {
      name: "methodArguments",
      required: "false",
      default: "require-security-and-request",
      description:
        'Determines how arguments for SDK methods are generated. Options: `"infer-optional-args"` or `"require-security-and-request"`.',
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Security configuration

```yml
go
  envVarPrefix: SPEAKEASY
  flattenGlobalSecurity: true
```

<Table
  data={[
    {
      name: "clientServerStatusCodesAsErrors",
      required: "false",
      default: "true",
      description: "Whether to treat `4xx` and `5xx` status codes as errors.",
    },
    {
      name: "[flattenGlobalSecurity](/docs/customize/authentication/overview)",
      required: "false",
      default: "newSDK",
      description:
        "Flatten the global security configuration if there is only a single option in the spec.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Import management

```yml
go
  imports:
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks
```

<Table
  data={[
    {
      path: "shared",
      default: "models/components",
      description:
        "The directory for shared components, such as reusable schemas, and data models.",
    },
    {
      path: "operations",
      default: "models/operations",
      description:
        "The directory where operation models (i.e., API endpoints) will be imported from.",
    },
    {
      path: "errors",
      default: "models/sdkerrors",
      description: "The directory where error models will be imported from.",
    },
    {
      path: "callbacks",
      default: "models/callbacks",
      description: "The directory where callback models will be imported from.",
    },
    {
      path: "webhooks",
      default: "models/webhooks",
      description: "The directory where webhook models will be imported from.",
    },
  ]}
  columns={[
    { key: "path", header: "Path" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Error and response handling

```yml
go:
  responseFormat: "envelope-http"
```

<Table
  data={[
    {
      name: "[responseFormat](/docs/customize/responses/responses)",
      required: "false",
      default: "envelope-http",
      description:
        "Determines the shape of the response envelope that is returned from SDK methods. Must be `envelope-http`, `envelope`, or `flat` only.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Nullable and optional field handling

```yml
go:
  nullableOptionalWrapper: true
```

<Table
  data={[
    {
      name: "nullableOptionalWrapper",
      required: "false",
      default: "newSDK",
      description:
        "When enabled, fields that are both optional and nullable in the source schema are generated using a wrapper type with explicit presence semantics: `optionalnullable.OptionalNullable[T]`. Defaults to `true` for new Go SDKs and `false` for existing SDKs to avoid breaking changes.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

### When it applies

The wrapper is generated only for fields that are:

- Optional (the property is not listed in the parent schema's `required` array)
- Nullable (the property `type` includes `"null"` in OpenAPI 3.1)

For example, the following JSON Schema (OpenAPI 3.1) defines an optional, nullable `nickname`:

```yaml
type: object
required:
  - id
properties:
  id:
    type: string
  nickname:
    type:
      - string
      - "null"
```

### Generated code

With `nullableOptionalWrapper: true`, the corresponding Go model uses a wrapper type:

```go
type Pet struct {
    ID       string                                    `json:"id"`
    Nickname optionalnullable.OptionalNullable[string] `json:"nickname,omitempty"`
}
```

Without the wrapper (when disabled for existing SDKs), the same field may be generated as a pointer type.

### Using the wrapper

Set values using helper constructors on `OptionalNullable` and retrieve values via `Get()`, which returns `(*T, bool)` — `ok` indicates presence, and a `nil` pointer indicates an explicit null value:

```go
// Set a present, non-null value
pet := shared.Pet{}
nickname := "Finn"
pet.Nickname = optionalnullable.From(&nickname)

// Read a value
if val, ok := pet.Nickname.Get(); ok {
    if val == nil {
        fmt.Println("nickname is explicitly null")
    } else {
        fmt.Println("nickname:", *val)
    }
} else {
    fmt.Println("nickname not set")
}
```

Enabling this flag changes the generated field type and how values are set and read. This is a breaking change for existing SDKs and requires migrating code that accessed those fields directly or through pointer checks to use `optionalnullable.From(...)` and `.Get()`.