Schema Annotations

Schema AST nodes can carry optional metadata called annotations. Use the .annotate(...) method or Schema.annotate(...) for the decoded side, Schema.annotateEncoded(...) for the encoded side, and Schema.annotateKey(...) for a struct field or tuple element.

Example (Using Annotations to Customize Schema)

1
import { Schema } from "effect"
2

3
// Define a Password schema, starting with a string type
4
const Password = Schema.String
5
  // Add a custom error message for non-string values
6
  .annotate({ message: "not a string" })
7
  .pipe(
8
    // Enforce non-empty strings and provide a custom error message
9
    Schema.check(
10
      Schema.isNonEmpty({ message: "required" }),
11
      // Restrict the string length to 10 characters or fewer
12
      // with a custom error message for exceeding length
13
      Schema.makeFilter((s) =>
14
        s.length <= 10 ? undefined : "must be at most 10 characters long",
15
      ),
16
    ),
17
  )
18
  .annotate({
19
    // Add a unique identifier for the schema
20
    identifier: "Password",
21
    // Provide a title for the schema
22
    title: "password",
23
    // Include a description explaining what this schema represents
24
    description: "A password is a secret string used to authenticate a user",
25
    // Add examples for better clarity
26
    examples: ["1Ki77y", "jelly22fi$h"],
27
    // Include any additional documentation
28
    documentation: `...technical information on Password schema...`,
29
  })

Built-in Annotations

The available annotations depend on the kind of schema node. These are the most common ones:

Annotation	Scope	Description
`identifier`	schema	Stable name used by schema interpreters, including JSON Schema references and expected-value messages.
`expected`	schema or check	Human-readable description used by the default error formatter.
`title`	schema or key	Short display title, also understood by JSON Schema tooling.
`description`	schema or key	Longer documentation for the represented value.
`documentation`	schema or key	Additional developer-facing documentation.
`examples`	schema or key	Example decoded values; this is metadata and does not validate them.
`default`	schema or key	A documented default value; it does not change decoding or construction behavior.
`message`	schema or check	Replaces the default message for matching failures.
`messageMissingKey`	key	Replaces the error message when a required key is absent.
`messageUnexpectedKey`	schema	Replaces the message for excess keys when `onExcessProperty` is `"error"`.
`parseOptions`	schema	Overrides parse options for that schema node.
`toJsonSchema`	check	Describes a custom check to the JSON Schema interpreter.
`toArbitrary`	schema or declaration	Customizes Arbitrary generation.
`toFormatter`	declaration	Defines Formatter behavior for a custom declaration.
`toEquivalence`	declaration	Defines Equivalence behavior for a custom declaration.
`toCodecJson`	declaration	Defines how a custom declaration is represented by the JSON codec interpreter.

Concurrency Parse Option

For schemas like Struct, Array, or Union that contain multiple effectful schemas, the concurrency parse option controls how many parsing effects may run concurrently.

type Concurrency = number | "unbounded" | undefined

Here’s a shorter version presented in a table:

Value	Description
`number`	Limits the maximum number of concurrent tasks.
`"unbounded"`	All tasks run concurrently with no limit.
`undefined`	At most one task runs at a time (the default).

Example (Sequential Execution)

In this example, we define three tasks that simulate asynchronous operations with different durations. Since no concurrency is specified, the tasks are executed sequentially, one after the other.

1
import { Schema, SchemaGetter } from "effect"
2
import type { Duration } from "effect"
3
import { Effect } from "effect"
4

5
// Simulates an async task
6
const item = (id: number, duration: Duration.Input) =>
7
  Schema.String.pipe(
8
    Schema.decode({
9
      decode: SchemaGetter.checkEffect(() =>
10
        Effect.gen(function* () {
11
          yield* Effect.sleep(duration)
12
          console.log(`Task ${id} done`)
13
          return true
14
        }),
15
      ),
16
      encode: SchemaGetter.passthrough(),
17
    }),
18
  )
19

20
const Sequential = Schema.Tuple([
21
  item(1, "30 millis"),
22
  item(2, "10 millis"),
23
  item(3, "20 millis"),
24
])
25

26
Effect.runPromise(Schema.decodeEffect(Sequential)(["a", "b", "c"]))
27
/*
28
Output:
29
Task 1 done
30
Task 2 done
31
Task 3 done
32
*/

Example (Concurrent Execution)

By passing { concurrency: "unbounded" } to the interpreter, the tasks can run concurrently instead of waiting for one another.

1
import { Schema, SchemaGetter } from "effect"
2
import type { Duration } from "effect"
3
import { Effect } from "effect"
4

5
// Simulates an async task
6
const item = (id: number, duration: Duration.Input) =>
7
  Schema.String.pipe(
8
    Schema.decode({
9
      decode: SchemaGetter.checkEffect(() =>
10
        Effect.gen(function* () {
11
          yield* Effect.sleep(duration)
12
          console.log(`Task ${id} done`)
13
          return true
14
        }),
15
      ),
16
      encode: SchemaGetter.passthrough(),
17
    }),
18
  )
19

20
const Concurrent = Schema.Tuple([
21
  item(1, "30 millis"),
22
  item(2, "10 millis"),
23
  item(3, "20 millis"),
24
])
25

26
Effect.runPromise(
27
  Schema.decodeEffect(Concurrent, { concurrency: "unbounded" })([
28
    "a",
29
    "b",
30
    "c",
31
  ]),
32
)
33
/*
34
Output:
35
Task 2 done
36
Task 3 done
37
Task 1 done
38
*/

Handling Decoding Errors with Fallbacks

Schema.catchDecoding lets you recover from a decoding issue with fallback logic.

type DecodingFallback<T> = (
  issue: SchemaIssue.Issue,
) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue>

This annotation enables you to specify fallback behavior when decoding fails, making it possible to recover gracefully from errors.

Example (Basic Fallback)

In this basic example, when decoding fails (e.g., the input is null), the fallback value is returned instead of an error.

1
import { Schema } from "effect"
2
import { Effect } from "effect"
3

4
// Schema with a fallback value
5
const schema = Schema.String.pipe(
6
  Schema.catchDecoding(() => Effect.succeedSome("<fallback>")),
7
)
8

9
console.log(Schema.decodeUnknownSync(schema)("valid input"))
10
// Output: valid input
11

12
console.log(Schema.decodeUnknownSync(schema)(null))
13
// Output: <fallback>

Example (Advanced Fallback with Logging)

In this advanced example, when a decoding error occurs, the schema logs the issue and then returns a fallback value. This demonstrates how you can incorporate logging and other side effects during error handling.

1
import { Schema } from "effect"
2
import { Effect } from "effect"
3

4
// Schema with logging and fallback
5
const schemaWithLog = Schema.String.pipe(
6
  Schema.catchDecoding((issue) =>
7
    Effect.gen(function* () {
8
      // Log the error issue
9
      yield* Effect.log(issue._tag)
10
      // Simulate a delay
11
      yield* Effect.sleep(10)
12
      // Return a fallback value
13
      return yield* Effect.succeedSome("<fallback>")
14
    }),
15
  ),
16
)
17

18
// Run the effectful fallback logic
19
Effect.runPromise(Schema.decodeUnknownEffect(schemaWithLog)(null)).then(
20
  console.log,
21
)
22
/*
23
Output:
24
timestamp=... level=INFO fiber=#0 message=InvalidType
25
<fallback>
26
*/

Custom Annotations

In addition to built-in annotations, you can define custom annotations to meet specific requirements. For instance, here’s how to create a deprecated annotation:

Example (Defining a Custom Annotation)

1
import { Schema } from "effect"
2

3
// Define a unique identifier for your custom annotation
4
const DeprecatedId = Symbol.for(
5
  "some/unique/identifier/for/your/custom/annotation",
6
)
7

8
// Apply the custom annotation to the schema
9
const MyString = Schema.String.annotate({ [DeprecatedId]: true })

To make your new custom annotation type-safe, you can use a module augmentation. In the next example, we want our custom annotation to be a boolean.

Example (Adding Type Safety to Custom Annotations)

1
import { Schema } from "effect"
2

3
const DeprecatedId = Symbol.for(
4
  "some/unique/identifier/for/your/custom/annotation",
5
)
6

7
// Module augmentation
8
declare module "effect/Schema" {
9
  namespace Annotations {
10
    interface Annotations {
11
      [DeprecatedId]?: boolean
12
    }
13
  }
14
}
15

16
const MyString = Schema.String.annotate({
17
  // @errors: 2418
18
  [DeprecatedId]: "bad value",
19
})

You can retrieve custom annotations using the Schema.resolveAnnotations helper function.

Example (Retrieving a Custom Annotation)

1
import { Schema } from "effect"
2

13 collapsed lines
3
const DeprecatedId = Symbol.for(
4
  "some/unique/identifier/for/your/custom/annotation",
5
)
6

7
declare module "effect/Schema" {
8
  namespace Annotations {
9
    interface Annotations {
10
      [DeprecatedId]?: boolean
11
    }
12
  }
13
}
14

15
const MyString = Schema.String.annotate({ [DeprecatedId]: true })
16

17
// Helper function to check if a schema is marked as deprecated
18
const isDeprecated = (schema: Schema.Top): boolean =>
19
  Schema.resolveAnnotations(schema)?.[DeprecatedId] ?? false
20

21
console.log(isDeprecated(Schema.String))
22
// Output: false
23

24
console.log(isDeprecated(MyString))
25
// Output: true