Package optional provides Field[T], a value that is unset, null,
or set. It works with encoding/json, encoding/json/v2, and
database/sql, and has no dependencies.
go get github.com/tapp-ai/optionalRequires Go 1.24 or later.
A JSON key or a database column can be in three states. A partial update (an
HTTP PATCH, a JSON Merge Patch, a
SQL UPDATE of some columns) has to tell them apart:
| Request body | Meaning | Field[string] |
|---|---|---|
{} |
Leave the nickname alone | unset |
{"nickname": null} |
Clear the nickname | null |
{"nickname": ""} |
Set the nickname to "" |
set to "" |
Common Go types lose one of these states:
| Type | {} |
null |
"" |
|---|---|---|---|
string |
"" |
"" |
"" |
*string |
nil |
nil |
&"" |
optional.Field[string] |
unset | null | set to "" |
Declare request fields as Field[T] and tag them with omitzero:
type UpdateUser struct {
Name optional.Field[string] `json:"name,omitzero"`
Nickname optional.Field[string] `json:"nickname,omitzero"`
Age optional.Field[int] `json:"age,omitzero"`
}Decode, then apply each field according to its state:
var req UpdateUser
err := json.Unmarshal([]byte(`{"nickname":null,"age":41}`), &req)
if name, ok := req.Name.Get(); ok {
user.Name = name
}
switch req.Nickname.State() {
case optional.StateNull:
user.Nickname = nil
case optional.StateSet:
user.Nickname = req.Nickname.Ptr()
}Encoding gives back the same body, {"nickname":null,"age":41}. The unset
Name field is left out because of omitzero.
Build values with Of, Null, or the zero value:
optional.Of("Ann") // set to "Ann"
optional.Of(0) // set to 0, not null
optional.Null[string]() // null
optional.Field[string]{} // unset
optional.FromPtr(user.Nickname) // set to *p, or null when p is nil| Unset | Null | Set to v |
|
|---|---|---|---|
State() |
StateUnset |
StateNull |
StateSet |
IsUnset() / IsZero() |
true |
false |
false |
IsNull() |
false |
true |
false |
IsSet() |
false |
false |
true |
Get() |
zero, false |
zero, false |
v, true |
GetOr(fallback) |
fallback |
fallback |
v |
Ptr() |
nil |
nil |
pointer to a copy of v |
String() |
"unset" |
"null" |
v formatted with %v |
Map(f, fn) |
unset | null | Of(fn(v)) |
Field[T] is a small value type. Copying it copies the value, and two fields
compare with == when T is comparable.
When you switch on State(), the
exhaustive linter reports a
missing case.
Field is meant for data that crosses a boundary: request and response bodies,
database rows, messages. For a function result that may be missing, return
(T, bool) or *T.
Field |
Encoded with omitzero |
Encoded without it |
|---|---|---|
| unset | key left out | null |
| null | null |
null |
set to v |
v |
v |
| Input | Decoded Field |
|---|---|
| key absent | unset (the decoder never touches it) |
null |
null |
| any other value | set, or an error if the value doesn't decode into T |
A set field whose value is a nil pointer, slice, map, or interface encodes as
null, so it decodes as null. JSON can't tell the two apart. To mean "clear
this", use Null[T]() rather than Of[*T](nil).
omitzero calls IsZero(), which is true only for an unset field. Use it on
every Field. omitempty is wrong in both JSON packages:
encoding/jsonnever omits a struct, so an unset field is written asnull.encoding/json/v2omits any value that encodes asnull, so an explicit null disappears.
On Go 1.27 and later, Field also implements MarshalJSONTo and
UnmarshalJSONFrom. encoding/json/v2 uses them, and so does encoding/json,
which runs on v2 from Go 1.27. On earlier versions, or with
GOEXPERIMENT=nojsonv2, both packages use MarshalJSON and UnmarshalJSON.
The two pairs behave the same, and CI tests every combination.
Field[T] implements sql.Scanner and driver.Valuer.
| Operation | Result |
|---|---|
Scan SQL NULL |
null |
Scan a value |
set. Values convert the way database/sql converts into a plain T (for example int64 to int); one that can't convert returns an error. |
Value of a set field |
its value. A T that implements driver.Valuer is used as is. |
Value of a null field |
SQL NULL |
Value of an unset field |
error ErrUnset |
Value returns ErrUnset for an unset field because SQL can't say "not
given". Writing NULL would silently clear a column the caller never meant to
touch. To build a partial UPDATE, leave out columns whose field IsUnset().
Query builders that skip zero values by reflection, such as goqu's
omitempty tag, skip unset fields automatically.
As with JSON, a set field holding a nil pointer writes NULL and scans back as
null.
go test -race ./...
GOEXPERIMENT=nojsonv2 go test -race ./...
go test -run='^$' -fuzz=FuzzJSON -fuzztime=1mFuzzJSON checks that every JSON codec round-trips what it decodes, and that
encoding/json and encoding/json/v2 decode a Field the same way.