Skip to content

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

Section titled “Version and general configuration”
go:
  version: 1.2.3
  modulePath: "github.com/my-company/company-go-sdk"
  sdkPackageName: "company"
Name
version
Required
true
Description
The current version of the SDK.
Default Value
0.0.1
modulePath
Required
true
Description
Root module path. Use sdkPackageName to configure the package clause for the root module package. Go Module Path documentation.
Default Value
github.com/my-company/company-go-sdk
sdkPackageName
Required
true
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.
Default Value
company
packageName
Required
false
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.
Default Value
sdkPackageAlias
Required
false
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.
Default Value
openapi

Additional dependencies

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

Retractions

Section titled “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
Description
The version to retract. Must be a valid semantic version.
Default Value
comment
Required
false
Description
Optional comment explaining why the version was retracted.
Default Value

Method and parameter management

Section titled “Method and parameter management”
go
  maxMethodParams: 4
  methodArguments: "require-security-and-request"
Name
maxMethodParams
Required
false
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
.
Default Value
4
methodArguments
Required
false
Description
Determines how arguments for SDK methods are generated. Options:
or
.
Default Value
require-security-and-request

Security configuration

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

Import management

Section titled “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

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

Nullable and optional field handling

Section titled “Nullable and optional field handling”
go:
  nullableOptionalWrapper: true
Name
nullableOptionalWrapper
Required
false
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.
Default Value
newSDK

When it applies

Section titled “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

Section titled “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

Section titled “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().