Go

The go format generates Go struct definitions with JSON tags from OpenAPI schemas.

Basic Example

OpenAPI Schema:

components:
  schemas:
    User:
      type: object
      description: A user in the system
      required:
        - id
        - email
      properties:
        id:
          type: string
          description: Unique identifier for the user
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time

Generated Go:

// Generated by an automated build step. Do not edit.

package types

import "time"

// A user in the system
type User struct {
	// Unique identifier for the user
	ID        string     `json:"id"`
	Email     string     `json:"email"`
	Name      *string    `json:"name,omitempty"`
	CreatedAt *time.Time `json:"createdAt,omitempty"`
}

Configuration

{
  "outputs": [
    {
      "path": "./internal/types/api.go",
      "format": "go",
      "contents": ["api:*"],
      "options": {
        "package": "types"
      }
    }
  ]
}

Options

package

Type: string
Default: "types"

The Go package name for the generated file.

"options": {
  "package": "models"
}

package models

type User struct {
    // ...
}

Type Mapping

OpenAPI Type	OpenAPI Format	Go Type
string	-	string
string	date	string
string	date-time	time.Time
string	email	string
string	uuid	string
string	byte	[]byte
integer	-	int
integer	int32	int32
integer	int64	int64
number	-	float64
number	float	float32
number	double	float64
boolean	-	bool
array	-	[]T
object	-	struct
object	(no properties)	map[string]any

Required vs Optional Fields

Required fields use value types, optional fields use pointers:

type User struct {
	ID   string  `json:"id"`           // Required
	Name *string `json:"name,omitempty"` // Optional
}

The omitempty tag is added for optional fields to exclude them from JSON when nil.

Nullable Fields

Nullable fields also use pointers:

properties:
  nickname:
    type: string
    nullable: true

type User struct {
	Nickname *string `json:"nickname,omitempty"`
}

JSON Tags

All fields include JSON tags with:

• Field name in original case from OpenAPI
• omitempty for optional/nullable fields

type User struct {
	FirstName *string `json:"firstName,omitempty"`
}

Enums

With generateEnums: true:

type UserRole string

const (
	UserRoleAdmin UserRole = "admin"
	UserRoleUser  UserRole = "user"
	UserRoleGuest UserRole = "guest"
)

With generateEnums: false:

type UserRole string

Date/Time Handling

The date-time format maps to time.Time:

properties:
  createdAt:
    type: string
    format: date-time

import "time"

type User struct {
	CreatedAt *time.Time `json:"createdAt,omitempty"`
}

The time package is automatically imported when needed.

References

References become type references:

type Post struct {
	Author User `json:"author"`
}

Composition

allOf (Embedding)

allOf:
  - $ref: '#/components/schemas/BaseEntity'
  - type: object
    properties:
      name:
        type: string

type Product struct {
	BaseEntity
	Name *string `json:"name,omitempty"`
}

oneOf / anyOf

Go doesn't have native union types. These generate interface types:

type Pet any // Union: Dog | Cat

For proper union handling, consider using discriminator patterns or custom unmarshaling.

Comments

Schema and property descriptions become Go comments:

// A user in the system
type User struct {
	// Unique identifier for the user
	ID string `json:"id"`
}

Usage Examples

JSON Marshaling

import (
	"encoding/json"
	"myapp/internal/types"
)

func main() {
	user := types.User{
		ID:    "123",
		Email: "user@example.com",
	}
	
	data, err := json.Marshal(user)
	if err != nil {
		panic(err)
	}
	
	fmt.Println(string(data))
	// {"id":"123","email":"user@example.com"}
}

JSON Unmarshaling

func parseUser(data []byte) (*types.User, error) {
	var user types.User
	if err := json.Unmarshal(data, &user); err != nil {
		return nil, err
	}
	return &user, nil
}

HTTP Handler

import (
	"encoding/json"
	"net/http"
	"myapp/internal/types"
)

func GetUser(w http.ResponseWriter, r *http.Request) {
	user := types.User{
		ID:    "123",
		Email: "user@example.com",
	}
	
	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(user)
}

Limitations

No Namespaces

Go format doesn't support namespaces. Use separate packages instead:

"outputs": [
  { 
    "path": "./internal/types/users/types.go",
    "format": "go",
    "contents": ["users:*"],
    "options": { "package": "users" }
  },
  {
    "path": "./internal/types/products/types.go",
    "format": "go",
    "contents": ["products:*"],
    "options": { "package": "products" }
  }
]

Validation

Generated structs are for serialization only. For validation, use:

• go-playground/validator
• ozzo-validation
• Custom validation logic

Union Types

Go lacks native union types. Options:

• Use any (loses type safety)
• Implement custom UnmarshalJSON
• Use discriminator fields

Best Practices

Package Organization

internal/
  types/
    api/
      types.go     # Generated
      helpers.go   # Custom helpers
    types.go       # Re-exports

Custom Methods

Add methods in a separate file to avoid overwriting:

// internal/types/api/helpers.go
package api

func (u *User) FullName() string {
	if u.Name != nil {
		return *u.Name
	}
	return u.Email
}

Validation Tags

Add validation after generation:

// Extend generated types with validation
type ValidatedUser struct {
	User
}

func (u *ValidatedUser) Validate() error {
	if u.Email == "" {
		return errors.New("email is required")
	}
	return nil
}

See Also

• Configuration Options
• Python Format - Alternative backend format
• TypeScript Format - Frontend types