Skip to content

x-oapi-codegen-only-honour-go-name

Prevent automatic capitalization of field names, allowing creation of unexported (lowercase) fields.

Overview

By default, oapi-codegen automatically capitalizes field names to make them exported (public) in Go. When you use x-go-name to specify a custom field name, it still gets capitalized via the schemaNameToTypeName() transformation.

The x-oapi-codegen-only-honour-go-name extension bypasses this automatic capitalization, using the exact name specified in x-go-name without any transformations. This allows you to create unexported (lowercase) fields in generated structs.

Warning

This is an advanced extension. Unexported fields cannot be accessed from other packages and will not be marshaled/unmarshaled by default JSON encoders.

Example

openapi: "3.0.0"
info:
  version: 1.0.0
  title: x-oapi-codegen-only-honour-go-name
components:
  schemas:
    TypeWithUnexportedField:
      description: A struct will be output where one of the fields is not exported
      properties:
        name:
          type: string
        id:
          type: string
          # NOTE that there is an explicit usage of a lowercase character
          x-go-name: accountIdentifier
          x-oapi-codegen-extra-tags:
            json: "-"
          x-oapi-codegen-only-honour-go-name: true

Generated Code

From here, we get a struct with an unexported field:

// TypeWithUnexportedField A struct will be output where one of the fields is not exported
type TypeWithUnexportedField struct {
    Name              *string `json:"name,omitempty"`
    accountIdentifier *string `json:"-"`
}

Notice that accountIdentifier starts with a lowercase letter, making it unexported (private to the package).

How It Works

Without x-oapi-codegen-only-honour-go-name: true: - x-go-name: accountIdentifier → gets capitalized → AccountIdentifier (exported)

With x-oapi-codegen-only-honour-go-name: true: - x-go-name: accountIdentifier → used as-is → accountIdentifier (unexported)

Use Cases

This extension is useful when you need:

  • Internal-only fields: Fields that should only be accessible within the same package
  • Implementation details: Fields that are part of internal logic but not part of the public API
  • Custom marshaling: Fields that require custom JSON marshaling logic (hence json:"-")
  • Package encapsulation: Enforcing strict boundaries between packages

Full Example

You can see this in more detail in the example code.

  • x-go-name - Override the generated name of a field or type (this extension modifies its behavior)
  • x-go-json-ignore - Ignore fields when (un)marshaling JSON (commonly used together)
  • x-oapi-codegen-extra-tags - Generate arbitrary struct tags (often used with json:"-")