Speakeasy Logo
Skip to Content
DocumentationSpeakeasyGeneration ConfigGo Configuration

Go configuration options

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

go:
  version: 1.2.3
  modulePath: "github.com/my-company/company-go-sdk"
  sdkPackageName: "company"
Name
version
Required
true
Default Value
0.0.1
Description
The current version of the SDK.
modulePath
Required
true
Default Value
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 .
sdkPackageName
Required
true
Default Value
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 .
packageName
Required
false
Default Value
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 .
sdkPackageAlias
Required
false
Default Value
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 .

Additional dependencies

go:
  additionalDependencies:
    axios: "0.21.0"
Name
additionalDependencies
Required
false
Default Value
{}
Description
Add additional dependencies to include in the generated
.

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.

go:
  retractions:
    - version: v1.0.0
      comment: Published accidentally
    - version: v1.0.1
Name
version
Required
true
Default Value
Description
The version to retract. Must be a valid semantic version.
comment
Required
false
Default Value
Description
Optional comment explaining why the version was retracted.

Method and parameter management

go
  maxMethodParams: 4
  methodArguments: "require-security-and-request"
Name
maxMethodParams
Required
false
Default Value
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.
will use input objects always. Must match the regex pattern
.
methodArguments
Required
false
Default Value
require-security-and-request
Description
Determines how arguments for SDK methods are generated. Options:
or
.

Security configuration

go
  envVarPrefix: SPEAKEASY
  flattenGlobalSecurity: true
Name
clientServerStatusCodesAsErrors
Required
false
Default Value
true
Description
Whether to treat
and
status codes as errors.
flattenGlobalSecurity
Required
false
Default Value
newSDK
Description
Flatten the global security configuration if there is only a single option in the spec.

Import management

go
  imports:
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks
Path
shared
Default Value
models/components
Description
The directory for shared components, such as reusable schemas, and data models.
operations
Default Value
models/operations
Description
The directory where operation models (i.e., API endpoints) will be imported from.
errors
Default Value
models/sdkerrors
Description
The directory where error models will be imported from.
callbacks
Default Value
models/callbacks
Description
The directory where callback models will be imported from.
webhooks
Default Value
models/webhooks
Description
The directory where webhook models will be imported from.

Error and response handling

go:
  responseFormat: "envelope-http"
Name
responseFormat
Required
false
Default Value
envelope-http
Description
Determines the shape of the response envelope that is returned from SDK methods. Must be
,
, or
only.

Nullable and optional field handling

go:
  nullableOptionalWrapper: true
Name
nullableOptionalWrapper
Required
false
Default Value
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:
. Defaults to
for new Go SDKs and
for existing SDKs to avoid breaking changes.

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:

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:

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:

// 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().

Last updated on