Schema to Standard Schema

Schema.toStandardSchemaV1 exposes an Effect schema through the Standard Schema V1 interface. The resulting object can be passed to libraries that support the standard while retaining the original Effect schema APIs.

Example (Generating a Standard Schema V1)

1
import { Schema } from "effect"
2

3
const schema = Schema.Struct({
4
  name: Schema.String,
5
})
6

7
// Convert an Effect schema into a Standard Schema V1 object
8
const standardSchema = Schema.toStandardSchemaV1(schema)
9

10
standardSchema["~standard"].vendor // => "effect"

Sync vs Async Validation

The Standard Schema validate method first attempts to decode synchronously. If decoding encounters an asynchronous transformation or check, it returns a Promise instead.

Example (Handling Synchronous and Asynchronous Validation)

1
import { Effect, Schema, SchemaGetter } from "effect"
2

3
// Utility function to display sync and async results
4
const print = <T>(t: T) =>
5
  t instanceof Promise
6
    ? t.then((x) => console.log("Promise", JSON.stringify(x, null, 2)))
7
    : console.log("Value", JSON.stringify(t, null, 2))
8

9
// Define a synchronous schema
10
const sync = Schema.Struct({
11
  name: Schema.String,
12
})
13

14
// Generate a Standard Schema V1 object
15
const syncStandardSchema = Schema.toStandardSchemaV1(sync)
16

17
// Validate synchronously
18
print(syncStandardSchema["~standard"].validate({ name: null }))
19
syncStandardSchema["~standard"].validate({ name: null }) // => { issues: [{ path: ["name"], message: "Expected string" }] }
20
/*
21
Output:
22
{
23
  "issues": [
24
    {
25
      "path": [
26
        "name"
27
      ],
28
      "message": "Expected string"
29
    }
30
  ]
31
}
32
*/
33

34
// Define an asynchronous schema with a transformation
35
const async = sync.pipe(
36
  Schema.decodeTo(
37
    Schema.Struct({
38
      name: Schema.NonEmptyString,
39
    }),
40
    {
41
      // Simulate an asynchronous validation delay
42
      decode: SchemaGetter.transformOrFail((x) =>
43
        Effect.sleep("100 millis").pipe(Effect.as(x)),
44
      ),
45
      encode: SchemaGetter.passthrough(),
46
    },
47
  ),
48
)
49

50
// Generate a Standard Schema V1 object
51
const asyncStandardSchema = Schema.toStandardSchemaV1(async)
52

53
// Validate asynchronously
54
print(asyncStandardSchema["~standard"].validate({ name: "" }))
55
await asyncStandardSchema["~standard"].validate({ name: "" }) // => { issues: [{ path: ["name"], message: "Expected a value with a length of at least 1" }] }
56
/*
57
Output:
58
Promise {
59
  "issues": [
60
    {
61
      "path": [
62
        "name"
63
      ],
64
      "message": "Expected a value with a length of at least 1"
65
    }
66
  ]
67
}
68
*/

Defects

If an unexpected defect occurs during validation, it is reported as a single issue without a path. This ensures that unexpected errors do not disrupt schema validation but are still captured and reported.

Example (Handling Defects)

1
import { Effect, Schema, SchemaGetter } from "effect"
2

3
// Define a schema with a defect in the decode function
4
const defect = Schema.String.pipe(
5
  Schema.decodeTo(Schema.String, {
6
    // Simulate an internal failure
7
    decode: SchemaGetter.transformOrFail(() => Effect.die("Boom!")),
8
    encode: SchemaGetter.passthrough(),
9
  }),
10
)
11

12
// Generate a Standard Schema V1 object
13
const defectStandardSchema = Schema.toStandardSchemaV1(defect)
14

15
// Validate input, triggering a defect
16
console.log(defectStandardSchema["~standard"].validate("a"))
17
/*
18
Output:
19
{ issues: [ { message: 'Error: Boom!' } ] }
20
*/

Standard Schema failures use the same formatter described in Error Formatters. Pass leafHook, checkHook, or parseOptions to Schema.toStandardSchemaV1 to customize its output.