Missing Key Messages

There’s a specific kind of error that annotate doesn’t cover: a missing key. When a required key is absent from the input object, the error isn’t about the value being wrong (there is no value), it’s about the key itself being missing.

You customize this with annotateKey, not annotate:

1
import { Schema } from "effect";
2

3
const LoginForm = Schema.Struct({
4
  username: Schema.String.annotateKey({
5
    messageMissingKey: "Username is required",
6
  }),
7
  password: Schema.String.annotateKey({
8
    messageMissingKey: "Password is required",
9
  }),
10
});
11

12
const result = Schema.decodeUnknownExit(LoginForm)({});
13
console.log(String(result));

Output:

1
Failure(Cause([Fail(SchemaError(Username is required
2
  at ["username"]))]))

Without the messageMissingKey annotation, the error would just say “Missing key”, which is technically correct, but not helpful for a user staring at a login form.

annotateKey vs annotate

This is a subtle but important distinction:

• annotate targets the value. It fires when a value is present but has the wrong type. If someone types “abc” into an age field, annotate({ message: "Age must be a number" }) provides the error.
• annotateKey targets the key. It fires when the key is entirely absent from the input. If someone leaves the age field blank and the form omits the key entirely, annotateKey({ messageMissingKey: "Age is required" }) provides the error.

You’ll often want both on the same field:

1
import { Schema } from "effect";
2

3
const schema = Schema.Struct({
4
  age: Schema.Number.annotate({ message: "Age must be a number" }) // value is wrong type
5
    .annotateKey({ messageMissingKey: "Age is required" }), // key is missing
6
});

Now age has a custom message for both error scenarios: missing key and wrong type.