Skip to content
Status

CLI

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.

Where a default is listed as “new” or “legacy”, the generator picks the “new” value for SDKs created after the option was introduced and the “legacy” value for SDKs that already existed, so that regeneration does not introduce breaking changes. Existing SDKs can opt in to the new behavior by setting the option explicitly.

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

Additional dependencies

Section titled “Additional dependencies”
go:
  additionalDependencies:
    github.com/google/uuid: v1.6.0
Name
additionalDependencies
Required
false
Description
Add additional dependencies to include in the generated go.mod. Keys are module paths and values are module versions.
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"
  optionalMethodArguments: "pointers"
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. 0 will use input objects always. Must match the regex pattern /^\d+$/.
Default Value
4
methodArguments
Required
false
Description
Determines how arguments for SDK methods are generated. Options: "infer-optional-args" or "require-security-and-request".
Default Value
require-security-and-request
optionalMethodArguments
Required
false
Description
Determines how optional SDK method arguments are generated. pointers preserves positional pointer arguments, shared-options uses operation-qualified functional options with the shared per-request option type, and method-options uses operation-specific functional option types. Changing this value for an existing SDK is a breaking API change.
Default Value
pointers

Security configuration

Section titled “Security configuration”
go:
  envVarPrefix: SPEAKEASY
  flattenGlobalSecurity: true
Name
envVarPrefix
Required
false
Description
The environment variable prefix for security and global env variable overrides. If empty, these overrides will not be possible.
Default Value
flattenGlobalSecurity
Required
false
Description
Flatten the global security configuration if there is only a single option in the spec.
Default Value
true (new) / false (legacy)

Import management

Section titled “Import management”
go:
  imports:
    option: openapi
    paths:
      callbacks: models/callbacks
      errors: models/apierrors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks

The defaults below apply to new SDKs. Legacy SDKs default to pkg/models/shared, pkg/models/operations, pkg/models/sdkerrors, pkg/models/callbacks, and pkg/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/apierrors
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"
  enableSkipDeserialization: false
  clientServerStatusCodesAsErrors: true
  defaultErrorName: "APIError"
Name
responseFormat
Required
false
Description
Determines the shape of the response envelope that is returned from SDK methods. Must be envelope-http, envelope, or flat only.
Default Value
envelope-http (new) / envelope (legacy)
enableSkipDeserialization
Required
false
Description
Generate a WithSkipDeserialization() option that skips typed deserialization of successful JSON response bodies. The body is buffered and replayed on the HTTP response so callers can read the raw bytes via HTTPMeta.Response after the call returns. Error responses and non-JSON responses are always deserialized. Requires responseFormat: envelope-http.
Default Value
false
clientServerStatusCodesAsErrors
Required
false
Description
Whether to treat 4xx and 5xx status codes as errors.
Default Value
true
defaultErrorName
Required
false
Description
The name of the default error type used to represent API errors. Letters and numbers only.
Default Value
APIError (new) / SDKError (legacy)

Nullable, optional, and required field handling

Section titled “Nullable, optional, and required field handling”
go:
  nullableOptionalWrapper: true
  respectRequiredFields: false
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: optionalnullable.OptionalNullable[T]. Defaults to true for new Go SDKs and false for existing SDKs to avoid breaking changes.
Default Value
true (new) / false (legacy)
respectRequiredFields
Required
false
Description
Respect required fields in the spec when generating models.
Default Value
false

Request serialization

Section titled “Request serialization”
go:
  includeEmptyObjects: true
  multipartArrayFormat: "standard"
Name
includeEmptyObjects
Required
false
Description
Include empty objects in serialized request bodies and parameters. When false, optional fields are excluded when empty.
Default Value
true (new) / false (legacy)
multipartArrayFormat
Required
false
Description
Format for array field names in multipart form data. legacy appends [] to array field names (for example files[]). standard uses the field name as-is. Set to standard for RFC-compliant multipart/form-data handling; switching an existing SDK is a breaking change for APIs that expect the [] suffix.
Default Value
standard (new) / legacy (legacy)

Enums and unions

Section titled “Enums and unions”
go:
  unionStrategy: "populated-fields"
  unionGenerics: false
  forwardCompatibleEnumsByDefault: true
  forwardCompatibleUnionsByDefault: "tagged-and-untagged"
  inferUnionDiscriminators: true
  respectTitlesForPrimitiveUnionMembers: true
Name
unionStrategy
Required
false
Description
Strategy for deserializing union types. left-to-right tries each type in order of most required fields first and returns the first valid match. populated-fields tries all types and returns the one with the most matching fields (including optional), falling back to the biggest stringified size and then to left-to-right. Enabling forwardCompatibleEnumsByDefault forces populated-fields.
Default Value
populated-fields (new) / left-to-right (legacy)
unionGenerics
Required
false
Description
Generate a single generic New<Union>[T <Union>Member](val T) constructor per union type instead of per-member Create<Union><Member> factory functions. Falls back to per-member constructors for unions that generics cannot express.
Default Value
false
forwardCompatibleEnumsByDefault
Required
false
Description
Generate enums as open (forward-compatible) by default for response types, so unknown values from the API do not break deserialization. Enums with an explicit x-speakeasy-unknown-values extension or special patterns (days of week, months) are not affected.
Default Value
true (new) / false (legacy)
forwardCompatibleUnionsByDefault
Required
false
Description
Controls forward compatibility for unions in responses. tagged-and-untagged makes both discriminated and untagged unions open to unknown values with a raw JSON fallback. tagged-only makes only discriminated unions open. false disables forward compatibility. Individual unions can be overridden with x-speakeasy-unknown-values: allow/disallow.
Default Value
tagged-and-untagged (new) / false (legacy)
inferUnionDiscriminators
Required
false
Description
Infer union discriminators for oneOfs missing explicit OpenAPI discriminator mapping.
Default Value
true (new) / false (legacy)
respectTitlesForPrimitiveUnionMembers
Required
false
Description
Use title or x-speakeasy-name-override for primitive union member field names instead of type-based defaults.
Default Value
true (new) / false (legacy)

Naming, models, and miscellaneous

Section titled “Naming, models, and miscellaneous”
go:
  inputModelSuffix: "input"
  outputModelSuffix: "output"
  customCasings:
    mcp:
      initialism: true
  idiomaticMethodCollisionNames: true
  enableCustomCodeRegions: false
Name
inputModelSuffix
Required
false
Description
Suffix added to models with writeOnly fields that are generated as input models.
Default Value
input
outputModelSuffix
Required
false
Description
Suffix added to models with readOnly fields that are generated as output models.
Default Value
output
customCasings
Required
false
Description
Custom casing terms to preserve in generated PascalCase symbols. Use { initialism: true } to render the key in all caps, for example mcp: { initialism: true } renders MCP.
Default Value
{}
idiomaticMethodCollisionNames
Required
false
Description
Resolve field names that collide with generated struct methods (for example Error()) using idiomatic replacements (ErrorInfo) instead of a trailing underscore (Error_).
Default Value
true (new) / false (legacy)
enableCustomCodeRegions
Required
false
Description
Allow custom code to be inserted into the generated SDK.
Default Value
false

Nullable optional wrapper in depth

Section titled “Nullable optional wrapper in depth”

This section expands on nullableOptionalWrapper from the field handling section above.

When the nullable wrapper applies

Section titled “When the nullable wrapper 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().

Fix flags

Section titled “Fix flags”

Fix flags gate behavior changes to the generated SDK’s runtime. They default to true for new SDKs. For existing SDKs the generator adds them as false on the next regeneration so that behavior does not change silently; set them to true to opt in.

go:
  fixFlags:
    encodePathParams: true
    applyPathParamDefaults: true
Name
encodePathParams
Required
false
Description
Percent-encode path parameter values in generated URLs, so reserved characters such as / or : are sent as %2F and %3A instead of raw, and reject values containing . or .. segments. Set x-speakeasy-param-encoding-override: allowReserved on a path parameter in the spec to keep its reserved characters unencoded. Required for allowReserved support on query parameters.
Default Value
true (new) / false (legacy)
applyPathParamDefaults
Required
false
Description
Substitute the schema default for string path parameters that are passed as an empty string. Without this flag an empty path parameter is sent as an empty path segment.
Default Value
true (new) / false (legacy)