Go's "Undefined" Problem Solved: A Practical Guide Using omitzero

Go developers have long grappled with the absence of a true "undefined" concept, relying on workarounds to manage optional fields, especially when dealing with JSON. The omitzero tag in Go 1.24 offers a simpler, cleaner approach to address this issue of differentiating between unset and zero values.

The Perils of omitempty: Why It Falls Short

omitempty has been the standard tool for handling optional fields, but it comes with limitations:

• Inconsistent "Empty" Definition: What constitutes an "empty" value varies across data types, leading to confusion.
• Unmarshaling Ambiguity: Distinguishing between a missing field and a field with its zero-value during unmarshaling is impossible with omitempty alone.
• Nullable Values: omitempty struggles with nullable values, where null is a valid, accepted value.

These problems make it difficult to represent the intent that a field was not provided when constructing APIs.

The Pointer Workaround: A Necessary Evil?

Pointers, combined with omitempty, are a common workaround. While they help with marshaling (nil fields disappear) and unmarshaling (nil means absent), they introduce:

• Complexity: Pointers necessitate frequent nil-checks and dereferencing, cluttering the code.
• Limited Scope: Pointers don't fully solve the nullable value dilemma, requiring extra logic.
• Error-Prone: The increased complexity of pointer management can introduce errors if not handled carefully.

omitzero to the Rescue: A Simpler Approach

Go 1.24 introduces the omitzero tag, which offers a more straightforward solution. If a field has its zero-value, it's omitted during marshaling.

type MyStruct struct {
	SomeTime time.Time `json:",omitzero"`
}

Now, 0001-01-01T00:00:00Z timestamps won't clutter your JSON output, creating cleaner APIs.

Introducing the Undefined Type: A Comprehensive Solution

The omitzero tag's ability to handle zero structs forms the basis for our Undefined type, providing a unified way to manage optional fields for robust API handling. This type resolves the remaining challenges:

• Marshaling nullable values.
• Differentiating between a zero value and an undefined value.
• Unmarshaling null and absent values correctly.

How the Undefined Type Works

type Undefined[T any] struct {
	Val     T
	Present bool
}

The Undefined struct leverages the zero-value behavior with omitzero to represent an optional value. If Present is true, the field exists; otherwise, it's considered undefined.

Implementing JSON Marshaler and Unmarshaler Interfaces

The UnmarshalJSON method sets Present to true when a value is present in the JSON. MarshalJSON marshals the underlying Val. IsZero returns true if Present is false, and the field will therefore be omitted, thanks to the omitzero struct tag.

func (u *Undefined[T]) UnmarshalJSON(data []byte) error {
	if err := json.Unmarshal(data, &u.Val); err != nil {
		return fmt.Errorf("Undefined: couldn't unmarshal JSON: %w", err)
	}
	u.Present = true
	return nil
}

func (u Undefined[T]) MarshalJSON() ([]byte, error) {
	data, err := json.Marshal(u.Val)
	if err != nil {
		return nil, fmt.Errorf("Undefined: couldn't JSON marshal: %w", err)
	}
	return data, nil
}

func (u Undefined[T]) IsZero() bool {
	return !u.Present
}

Benefits of Using the Undefined Type:

• Unified Handling: Works across all data types due to generics.
• Clear Distinction: Accurately differentiates between absent, null, and zero values.
• Simplified Code: Reduces nil-checks and dereferencing compared to using pointers directly.

Expanding the Solution: Database Scanning

The same logic can be applied to database scanning, enabling detection of selected vs. non-selected fields. This creates a consistent approach to managing optional data across the entire application. You can find a full implementation of the Undefined type in frameworks such as Goyave.

This approach provides a pragmatic solution for handling optional values in Go, resulting in more robust and expressive applications.