Schema to Standard Schema

The Schema.standardSchemaV1 API allows you to generate a Standard Schema v1 object from an Effect Schema.

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
//
9
//      ┌─── StandardSchemaV1<{ readonly name: string; }>
10
//      ▼
11
const standardSchema = Schema.standardSchemaV1(schema)

Sync vs Async Validation

The Schema.standardSchemaV1 API creates a schema whose validate method attempts to decode and validate the provided input synchronously. If the underlying Schema includes any asynchronous components (e.g., asynchronous message resolutions or checks), then validation will necessarily return a Promise instead.

Example (Handling Synchronous and Asynchronous Validation)

1
import { Effect, Schema } 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.standardSchemaV1(sync)
16

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

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

46
// Generate a Standard Schema V1 object
47
const asyncStandardSchema = Schema.standardSchemaV1(async)
48

49
// Validate asynchronously
50
print(asyncStandardSchema["~standard"].validate({ name: "" }))
51
/*
52
Output:
53
Promise {
54
  "issues": [
55
    {
56
      "path": [
57
        "name"
58
      ],
59
      "message": "Expected a non empty string, actual \"\""
60
    }
61
  ]
62
}
63
*/

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 } from "effect"
2

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

10
// Generate a Standard Schema V1 object
11
const defectStandardSchema = Schema.standardSchemaV1(defect)
12

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