Finally: Easy Solutions for Handling Undefined Fields in Go (with omitzero)

Struggling with undefined behavior in Go? For years, Go developers have wrestled with managing optional or nullable fields, especially when dealing with JSON. The new omitzero tag in Go 1.24 offers a cleaner way than the old omitempty workaround. This article shows you how to use omitzero and a custom wrapper type to handle truly undefined values in your Go applications.

The Pain of omitempty: A Go Developer's Headache

Go doesn't inherently have an "undefined" concept; it only has zero values. omitempty was meant to help with JSON serialization but quickly becomes a source of frustration.

• Inconsistent "Empty" Definition: omitempty treats slices, maps, pointers, structs, and strings differently, leading to unexpected behavior.
• Unmarshaling Ambiguity: You can't distinguish between a missing field in the JSON and a field with a zero value.
• Error-Prone: Relying on omitempty requires remembering numerous edge cases.

The Pointer Workaround: More Band-Aid Than Solution

The common workaround involves using pointers with omitempty. This allows you to treat nil as "undefined."

• Marshaling: nil pointer fields are correctly omitted due to omitempty.
• Unmarshaling: A nil pointer means the field was absent in the JSON.

However, this falls apart when you need to handle true nullable values that your service interprets as a valid piece of data.

• Nullable Value Issues: When unmarshaling, you still can't tell if a field is simply absent or explicitly set to null. When marshaling with omitempty, nil values are always omitted, preventing you from outputting the intended null.
• Code Clutter: Pointers introduce nil-checks and dereferencing, making your code less readable.

omitzero to the Rescue: A Simpler Approach to JSON Handling

Go 1.24 introduced omitzero, offering a more straightforward way to omit fields with their zero values.

• Simpler Logic: Fields are omitted only if they hold their zero value.
• Struct Support: Entire structs are considered zero if all their fields are zero.
• Example: SomeTime time.Time \json:",omitzero"`will ensure defaulttime.Time` values aren't serialized.

omitzero is a building block, but it does not entirely solve:

• Handling nullable values during marshaling
• Differentiating zero and undefined
• Differentiating null and absent

The Undefined Wrapper Type: A Complete Solution for Optional Values in Go

The omitzero tag helps define a struct that leverages the behavior of zero values and handles cases where data really is not defined, by not including it in the serialized data structure at all.

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

Here's how it works:

• Present Flag: If Present is true, the field is considered defined and not its zero value.
• JSON Marshaling:

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
}

The wrapper type ensures the underlying value Val and not the wrapper itself is serialized. Thanks to omitzero, it will be omitted upon serialization.

• JSON Unmarshaling:

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
}

If the input JSON contains the field, UnmarshalJSON is called, setting Present to true. If the field is absent, UnmarshalJSON is not called, and Present remains false.

• IsZero() Method:

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

This method helps the JSON library determine if a value is zero based on the Present status.

Benefits of the Undefined Type

• Handles Nullable Values: Distinguishes between truly absent fields and fields with explicit null values.
• Generic: Works with any data type due to the generic type parameter T.
• Clear Intent: Explicitly defines the concept of an "undefined" field in your Go structs.
• Clean Code: Eliminates the need for excessive nil-checks and pointer dereferencing.

Next Steps: Database Scanning and Beyond

The same Undefined logic can be applied to database interactions (e.g., using sql.Scanner) to determine whether a field was selected in a query.

Conclusion: A Practical Approach to Undefined Values in Go

By combining the new omitzero tag with the Undefined wrapper type, you gain a powerful and practical solution for handling optional and nullable values in your Go applications. This approach leads to cleaner, more maintainable code and eliminates the ambiguities associated with traditional omitempty workarounds.