Standard Schema Integration

Standard Schema Integration

Historically, libraries and frameworks didn’t know how to talk to schema libraries natively. For example, If you wanted to use Zod to validate a form in React Hook Form, you couldn’t just hand the Zod schema to the form. You had to download a separate translation package (an adapter or resolver) that sat between your schema and the framework. The same was true for Effect Schema, Valibot, ArkType, and every other schema library.

This created friction. Every combination of “schema library + consumer library” needed its own adapter. If you used Effect Schema with React Hook Form, you needed one adapter. If you switched to TanStack Form, you needed a different one. The adapters added dependencies, introduced version compatibility issues, and sometimes lagged behind the libraries they connected.

Standard Schema is a specification that solves this problem. The creators of the major validation libraries agreed on a common interface that any schema library can implement. The interface is minimal: a ~standard property on every schema with a validate method that accepts unknown input and returns either { value } on success or { issues } on failure.

The issues array is the key part for error handling. Each issue has a message (string) and an optional path (array of property keys). This is the universal error shape. Regardless of whether the schema was built with Zod, Valibot, or Effect Schema, the consumer always gets the same { message, path } structure.

On the consumer side, libraries like TanStack Form, TanStack Router, and React Hook Form now accept Standard Schema directly. They call schema["~standard"].validate(input) internally and get back a standardized result.

Effect Schema implements Standard Schema v1. As a result, you no longer need adapters or resolvers when integrating Effect Schema with libraries and frameworks that are Standard Schema compliant. You hand your schema to the form library, and it just works.

Converting to Standard Schema

To convert an Effect Schema to a Standard Schema, you use Schema.toStandardSchemaV1:

1
import { Schema } from "effect";
2

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

8
const standardSchema = Schema.toStandardSchemaV1(UserSchema);
9

10
console.log("Standard Schema: ", standardSchema);

Output:

1
Standard Schema:  {
2
  fields: {
3
    name: {
4
      ast: [String],
5
      rebuild: [Function (anonymous)],
6
      makeUnsafe: [Function (anonymous)]
7
    },
8
    age: {
9
      ast: [Number],
10
      rebuild: [Function (anonymous)],
11
      makeUnsafe: [Function (anonymous)]
12
    }
13
  },
14
  mapFields: [Function: mapFields],
15
  ast: Objects {
16
    '~effect/Schema': '~effect/Schema',
17
    annotations: undefined,
18
    checks: undefined,
19
    encoding: undefined,
20
    context: undefined,
21
    _tag: 'Objects',
22
    propertySignatures: [ [PropertySignature], [PropertySignature] ],
23
    indexSignatures: []
24
  },
25
  rebuild: [Function (anonymous)],
26
  makeUnsafe: [Function (anonymous)],
27
  '~standard': { version: 1, vendor: 'effect', validate: [Function: validate] }
28
}

The consuming library calls standardSchema["~standard"].validate(input) internally and gets back the { issues: [...] } shape. You don’t need to write any formatting code. The protocol handles it.

Using the Formatter Directly

Sometimes you’re not plugging into a form library. Maybe you’re building an API endpoint and want to return structured errors in the Standard Schema format. In that case, you can use the formatter directly with SchemaIssue.makeFormatterStandardSchemaV1:

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

3
const User = Schema.Struct({
4
  name: Schema.NonEmptyString,
5
  age: Schema.Number.check(Schema.isGreaterThan(0)),
6
});
7

8
const result = Schema.decodeUnknownExit(User)(
9
  { name: "", age: -5 },
10
  { errors: "all" },
11
);
12

13
if (result._tag === "Failure") {
14
  const fail = result.cause.reasons[0];
15
  if (fail._tag === "Fail") {
16
    const formatted = SchemaIssue.makeFormatterStandardSchemaV1()(
17
      fail.error.issue,
18
    );
19
    console.log(JSON.stringify(formatted, null, 2));
20
  }
21
}

Output:

1
{
2
  "issues": [
3
    {
4
      "path": [
5
        "name"
6
      ],
7
      "message": "Expected a value with a length of at least 1, got \"\""
8
    },
9
    {
10
      "path": [
11
        "age"
12
      ],
13
      "message": "Expected a value greater than 0, got -5"
14
    }
15
  ]
16
}

Let’s trace through what’s happening step by step:

1. Schema.decodeUnknownExit runs the validation and returns an Exit object.
2. We check that it’s a Failure (validation failed).
3. result.cause.reasons is the flat array of reasons. For Schema errors, there is one Fail reason containing the SchemaError.
4. fail.error is the SchemaError. We access .issue to get the raw issue tree.
5. SchemaIssue.makeFormatterStandardSchemaV1() creates a formatter function. We call it with the issue (not the SchemaError).
6. The formatter walks the nested issue tree and flattens it into an array of { message, path } objects.

The result is clean, structured data that any UI can work with. No parsing strings, no regex matching. Just iterate over the issues array and display each one.