Go "Undefined" Fields Finally Solved: A Practical Guide with omitzero

Struggling with missing or undefined fields in your Go applications? For years, Go developers have wrestled with the limitations of omitempty and the lack of a true "undefined" concept. Discover how the new omitzero tag in Go 1.24, combined with a clever wrapper type, provides a clean, unified, and practical solution to handle undefined values in your Go structs.

The Pain of Missing Fields in Go: Why omitempty Falls Short

Go doesn't have a built-in undefined value like some other languages. Instead, it relies on zero values. This creates challenges when working with JSON and databases because omitting fields is not possible. For a long time, developers have leaned on the omitempty struct tag to try and manage the absence of fields, but it has inherent limitations:

• Inconsistent Definition of "Empty": omitempty treats different data types differently, leading to confusion. A zero-length string is "empty," but a struct is never "empty."
• Unmarshaling Ambiguity: When receiving data, omitempty cannot differentiate between a missing field and a field explicitly set to its zero value.
• Handling Nullable Values: omitempty struggles to correctly handle nullable values where null is an accepted meaning.

omitempty forces you to consider many edge cases, turning your workflow into something error-prone.

Pointers to the Rescue? Addressing Missing Data (and New Problems)

The common workaround involves using pointers in combination with omitempty. This allows you to identify missing fields because nil pointers represent the absent values:

• Marshaling: Nil pointer will correctly disappear from your ouput.
• Unmarshaling: You can know the field wasn't present if the pointer is nil.

While this approach works in many cases, the pointer workaround introduces its own set of problems:

• Nullable Value Blind Spot: Again, you fall straight back to start when your service accepts null values.
• Nil-Checks Everywhere: Dereferencing requires a lot of code overhead.
• Error-Prone: Pointers increase program complexity.

The Elegant Solution: omitzero and the Undefined Type

Go 1.24 introduces omitzero, a simpler and more powerful tag. If a field has its zero value, omitzero omits the field during marshaling. This even goes for structs if all their members are zeroed out.

See how clean it is now to exclude zero time.Time values:

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

omitzero does not handle differentiating between undefined or null values, but it is a significant step in the direction. Let's see how it can be combined with a wrapper type!

Introducing the Undefined Wrapper: Distinguishing Absence from Zero

The Undefined wrapper leverages omitzero to provide a robust solution for handling potentially missing values:

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

Here's how it works:

• Val T: Holds the actual value of the field. The generic type T allows the wrapper to be used with any data type.
• Present bool: Indicates whether the field was present in the input data.

Marshaling and Unmarshaling Magic

The Undefined type implements the json.Marshaler and json.Unmarshaler interfaces to seamlessly integrate with Go's JSON handling:

• UnmarshalJSON: If the corresponding field is present in the JSON data, UnmarshalJSON unmarshals the value into Val and sets Present to true. If the field is absent, UnmarshalJSON is not called, and Present remains false.
• MarshalJSON: Marshals the underlying value (Val). The omitzero tag on the Undefined field ensures that the field is omitted if Present is false (meaning the field was initially undefined).
• IsZero(): Check if the value is zero.

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
}

Practical Benefits of the Undefined Solution

• Clear Distinction: Accurately differentiates between a missing field, a field with a zero value, and a field explicitly set to null.
• Unified Handling: Works consistently across all data types in Go.
• Simplified Logic: Reduces the need for verbose nil-checks and complex conditional logic.
• nullable value ready: The Present field signifies the presence of the data at all times without having to do error-prone checks.

Beyond JSON: Database Scanning and the Future

The Undefined type's logic can be extended to database interactions as well, allowing you to determine whether a field was explicitly selected from the database.

Real-World Implementation: The Goyave Framework

You can find a complete implementation of the Undefined type, along with other helpful tools, and features, in the Goyave framework.

Ready to say goodbye to omitempty headaches and embrace a cleaner approach to handling undefined fields in Go? Start leveraging omitzero and the Undefined type today!