Handling Optional and Nullable Fields | Effect Schema

JavaScript and TypeScript represent the absence of data in several distinct ways. When working with objects, missing fields typically fall into one of three specific categories:

Key omission: The key does not exist on the object at all.
Present but undefined: The key exists, but its value is explicitly undefined.
Present but null: The key exists, but its value is explicitly null.

Effect Schema provides specific APIs for each of these cases, allowing you to be precise about which forms of absence your application should accept.

Making Fields Optional

The simplest way to make a field optional is optionalKey. It creates an exact optional property, meaning the key can be omitted from the object entirely, but if it is present, it must match the schema’s type.

1
import { Schema } from "effect";
2

3
const UserSchema = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.optionalKey(Schema.Number),
6
});
7

8
// Type: { readonly name: string; readonly age?: number }
9
type User = typeof UserSchema.Type;
10

11
const decode = Schema.decodeUnknownSync(UserSchema);
12

13
// age is omitted — valid
14
console.log(decode({ name: "John" }));
15

16
// age is present — valid
17
console.log(decode({ name: "John", age: 24 }));
18

19
// age is present but wrong type — error
20
try {
21
  decode({ name: "John", age: "twenty four" });
22
} catch (error) {
23
  if (error instanceof Error) {
24
    console.log("Error:", error.message);
25
  }
26
}
27

28
// age is present but wrong type — error
29
try {
30
  decode({ name: "John", age: undefined });
31
} catch (error) {
32
  if (error instanceof Error) {
33
    console.log("Error:", error.message);
34
  }
35
}

Output:

1
{ name: 'John' }
2
{ name: 'John', age: 24 }
3
Error: Expected number, got "twenty four"
4
  at ["age"]
5
Error: Expected number, got undefined
6
  at ["age"]

The age key can be absent, but if it’s there, it must be a number. Any other data type will result in a decoding failure.

Making Fields Optional with Undefined

Oftentimes you want a field that can be omitted or explicitly set to undefined. The optional function handles this case.

optional is equivalent to optionalKey(UndefinedOr(schema)). It creates a field that accepts three states: the key is absent, the key is present with undefined, or the key is present with a valid value.

1
import { Schema } from "effect";
2

3
const UserSchema = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.optional(Schema.Number),
6
});
7

8
// Type: { readonly name: string; readonly age?: number | undefined }
9
type User = typeof UserSchema.Type;
10

11
const decode = Schema.decodeUnknownSync(UserSchema);
12

13
// age is omitted — valid
14
console.log(decode({ name: "Steve" }));
15

16
// age is explicitly undefined — valid
17
console.log(decode({ name: "Steve", age: undefined }));
18

19
// age is present — valid
20
console.log(decode({ name: "Steve", age: 30 }));

Output:

1
{ name: 'Steve' }
2
{ name: 'Steve', age: undefined }
3
{ name: 'Steve', age: 30 }

Mapping Optional Fields to Option

In the previous sections, we learnt how to represent optional fields as missing keys or undefined values. While Effect Schema lets us distinguish between missing keys and undefined values precisely, they are not always the most convenient shapes to work with in application code. In many cases, it is easier to convert all of these cases into a single representation: Option. Option is an Effect data type with only two possibilities: Some(value), which means a value is present, and None, which means it is absent. The key benefit of Option is that absence becomes explicit. Every consumer of the value must handle the None case.

Effect Schema provides two functions that transform optional fields into Option values during decoding.

`OptionFromOptionalKey`

OptionFromOptionalKey decodes a field that may be absent (an exact optional key) into an Option:

If the key is missing, the decoded value is Option.none().
If the key is present, the decoded value is Option.some(value).

1
import { Option, Schema } from "effect";
2

3
const UserSchema = Schema.Struct({
4
  name: Schema.String,
5
  nickname: Schema.OptionFromOptionalKey(Schema.String),
6
});
7

8
// Type: { readonly name: string; readonly nickname: Option.Option<string> }
9
type User = typeof UserSchema.Type;
10

11
const decode = Schema.decodeUnknownSync(UserSchema);
12

13
// Key is absent — None
14
const aron = decode({ name: "Aron" });
15
console.log(aron.nickname); // { _id: 'Option', _tag: 'None' }
16
console.log(Option.isNone(aron.nickname)); // true
17

18
// Key is present — Some
19
const bob = decode({ name: "Bob", nickname: "Bobby" });
20
console.log(bob.nickname); // { _id: 'Option', _tag: 'Some', value: 'Bobby' }
21
console.log(Option.getOrElse(bob.nickname, () => "no nickname")); // Bobby

`OptionFromOptional`

OptionFromOptional is the broader variant. It decodes a field that may be absent or explicitly undefined into an Option:

If the key is missing, the decoded value is Option.none().
If the value is undefined, the decoded value is Option.none().
Otherwise, the decoded value is Option.some(value).

1
import { Schema } from "effect";
2

3
const UserSchema = Schema.Struct({
4
  name: Schema.String,
5
  nickname: Schema.OptionFromOptional(Schema.String),
6
});
7

8
const decode = Schema.decodeUnknownSync(UserSchema);
9

10
// Key is absent - None
11
console.log(decode({ name: "Anne" }).nickname);
12

13
// Value is undefined - None
14
console.log(decode({ name: "Bob", nickname: undefined }).nickname);
15

16
// Value is present - Some
17
console.log(decode({ name: "Charlie", nickname: "Chuck" }).nickname);

Output:

1
{ _id: 'Option', _tag: 'None' }
2
{ _id: 'Option', _tag: 'None' }
3
{ _id: 'Option', _tag: 'Some', value: 'Chuck' }

Nullable and Nullish Types

APIs commonly use null to represent empty values, and some systems use both null and undefined. Effect Schema provides three helpers for these cases.

`NullOr`

NullOr creates a schema that accepts either the wrapped type or null:

1
import { Schema } from "effect";
2

3
const UserSchema = Schema.Struct({
4
  name: Schema.String,
5
  bio: Schema.NullOr(Schema.String),
6
});
7

8
// Type: { readonly name: string; readonly bio: string | null }
9
type User = typeof UserSchema.Type;
10

11
const decode = Schema.decodeUnknownSync(UserSchema);
12

13
console.log(decode({ name: "Hemanta", bio: "Hello!" }));
14
console.log(decode({ name: "Hemanta", bio: null }));

Output:

1
{ name: 'Hemanta', bio: 'Hello!' }
2
{ name: 'Hemanta', bio: null }

The bio field is still required — you must provide the key. But the value can either be a string or null.

`UndefinedOr`

UndefinedOr creates a schema that either accepts the wrapped type or undefined.

1
import { Schema } from "effect";
2

3
const UserSchema = Schema.Struct({
4
  name: Schema.String,
5
  bio: Schema.UndefinedOr(Schema.String),
6
});
7

8
// Type: { readonly name: string; readonly bio: string | undefined }
9
type User = typeof UserSchema.Type;
10

11
const decode = Schema.decodeUnknownSync(UserSchema);
12

13
console.log(decode({ name: "Hemanta", bio: "Hello!" }));
14
console.log(decode({ name: "Hemanta", bio: undefined }));

Output:

1
{ name: 'Hemanta', bio: 'Hello!' }
2
{ name: 'Hemanta', bio: undefined }

Note that UndefinedOr on its own does not make the key optional. The bio key must still be present in the input. It just allows undefined as a valid value. If you want the key to be omissible as well, use optional, which combines optionalKey with UndefinedOr.

`NullishOr`

NullishOr accepts the wrapped type, null or undefined.

1
import { Schema } from "effect";
2

3
const UserSchema = Schema.Struct({
4
  name: Schema.String,
5
  bio: Schema.NullishOr(Schema.String),
6
});
7

8
// Type: { readonly name: string; readonly bio: string | null | undefined }
9
type User = typeof UserSchema.Type;
10

11
const decode = Schema.decodeUnknownSync(UserSchema);
12

13
console.log(decode({ name: "Hemanta", bio: "Hello!" }));
14
console.log(decode({ name: "Hemanta", bio: null }));
15
console.log(decode({ name: "Hemanta", bio: undefined }));

Output:

1
{ name: 'Hemanta', bio: 'Hello!' }
2
{ name: 'Hemanta', bio: null }
3
{ name: 'Hemanta', bio: undefined }

This is common when consuming APIs that don’t distinguish between null and undefined.

Mapping Nullable Fields to Option

The previous section mapped optional fields (missing keys and undefined values) into Option. The same idea applies to nullable fields. Instead of working with string | null in your application code, you can decode the value into an Option, collapsing null into None and keeping valid values as Some.

`OptionFromNullOr`

OptionFromNullOr decodes a required field whose value might be null:

null becomes Option.none().
Any other valid value becomes Option.some(value).

1
import { Option, Schema } from "effect";
2

3
const UserSchema = Schema.Struct({
4
  name: Schema.String,
5
  bio: Schema.OptionFromNullOr(Schema.String),
6
});
7

8
// Type: { readonly name: string; readonly bio: Option.Option<string> }
9
type User = typeof UserSchema.Type;
10

11
const decode = Schema.decodeUnknownSync(UserSchema);
12

13
// null - None
14
const anne = decode({ name: "Anne", bio: null });
15
console.log(Option.isNone(anne.bio)); // true
16

17
// string - Some
18
const bob = decode({ name: "Bob", bio: "Hello!" });
19
console.log(Option.getOrElse(bob.bio, () => "no bio")); // Hello!

Quick Reference

Function	What it does
`optionalKey`	Key can be omitted, but if present, must match the type
`optional`	Key can be omitted or set to `undefined`
`NullOr`	Value can be the type or `null`
`UndefinedOr`	Value can be the type or `undefined`
`NullishOr`	Value can be the type, `null`, or `undefined`
`OptionFromOptionalKey`	Missing key becomes `None`, present value becomes `Some`
`OptionFromOptional`	Missing key or `undefined` becomes `None`, present value becomes `Some`
`OptionFromNullOr`	`null` becomes `None`, present value becomes `Some`

Making Fields Optional

Making Fields Optional with Undefined

Mapping Optional Fields to Option

OptionFromOptionalKey

OptionFromOptional

Nullable and Nullish Types

NullOr

UndefinedOr

NullishOr

Mapping Nullable Fields to Option

OptionFromNullOr

Quick Reference

Stay in the loop

`OptionFromOptionalKey`

`OptionFromOptional`

`NullOr`

`UndefinedOr`

`NullishOr`

`OptionFromNullOr`