# Schema: Migration from v3 This document maps v3 Schema APIs to their v4 equivalents. Simple renames and argument changes are covered in the summary table below. More complex migrations have dedicated sections with code examples. ## Migration types - **auto** — mechanical find-and-replace, safe to auto-apply - **semi-auto** — follows a clear pattern but needs structural changes - **manual** — requires case-by-case decisions, flag for human review - **removed** — no v4 equivalent ## Summary table | v3 API | v4 API | Migration type | | ----------------------------------------------- | ----------------------------------------------------------------------------- | ----------------- | | `asSchema(schema)` | `revealCodec(schema)` | rename | | `encodedSchema(schema)` | `toEncoded(schema)` | rename | | `typeSchema(schema)` | `toType(schema)` | rename | | `compose(schemaB)` | `decodeTo(schemaB)` | rename | | `annotations(ann)` | `annotate(ann)` | rename | | `decodingFallback` annotation | `catchDecoding(...)` | rename | | `parseJson()` | `UnknownFromJsonString` | rename | | `parseJson(schema)` | `fromJsonString(schema)` | rename | | `pattern(regex)` | `check(isPattern(regex))` | rename | | `nonEmptyString` | `isNonEmpty` | rename | | `BigIntFromSelf` | `BigInt` | rename | | `SymbolFromSelf` | `Symbol` | rename | | `URLFromSelf` | `URL` | rename | | `RedactedFromSelf` | `Redacted` | rename | | `Redacted` | `RedactedFromValue` | rename | | `EitherFromSelf` | `Result` | rename | | `TaggedError` | `TaggedErrorClass` | rename | | `decodeUnknown` | `decodeUnknownEffect` | rename | | `decode` | `decodeEffect` | rename | | `decodeUnknownEither` | `decodeUnknownExit` | rename | | `decodeEither` | `decodeExit` | rename | | `encodeUnknown` | `encodeUnknownEffect` | rename | | `encode` | `encodeEffect` | rename | | `encodeUnknownEither` | `encodeUnknownExit` | rename | | `encodeEither` | `encodeExit` | rename | | `Literal(null)` | `Null` | restructure | | `Literal("a", "b")` | `Literals(["a", "b"])` | variadic-to-array | | `pickLiteral("a", "b")` | `Literals(...).pick(["a", "b"])` | restructure | | `Union(A, B)` | `Union([A, B])` | variadic-to-array | | `Tuple(A, B)` | `Tuple([A, B])` | variadic-to-array | | `TemplateLiteral(A, B)` | `TemplateLiteral([A, B])` | variadic-to-array | | `TemplateLiteralParser(A, B)` | `TemplateLiteralParser(schema.parts)` | restructure | | `Record({ key, value })` | `Record(key, value)` | restructure | | `filter(predicate)` | `check(makeFilter(predicate))` | restructure | | `filter(refinement)` | `refine(refinement)` | restructure | | `UUID` | `String.check(isUUID())` | restructure | | `ULID` | `String.check(isULID())` | restructure | | `pick("a")` | `mapFields(Struct.pick(["a"]))` | restructure | | `omit("a")` | `mapFields(Struct.omit(["a"]))` | restructure | | `partial` | `mapFields(Struct.map(Schema.optional))` | restructure | | `partialWith({ exact: true })` | `mapFields(Struct.map(Schema.optionalKey))` | restructure | | `required(schema)` | `schema.mapFields(Struct.map(Schema.requiredKey))` | restructure | | `extend(structB)` | `mapFields(Struct.assign(fieldsB))` or `fieldsAssign(fieldsB)` | restructure | | `transform(from, to, { decode, encode })` | `from.pipe(decodeTo(to, SchemaTransformation.transform({ decode, encode })))` | restructure | | `transformOrFail(from, to, { decode, encode })` | `from.pipe(decodeTo(to, { decode: SchemaGetter.transformOrFail(...), ... }))` | restructure | | `transformLiteral(from, to)` | `Literal(from).transform(to)` | restructure | | `transformLiterals([0,"a"], [1,"b"])` | `Literals([0, 1]).transform(["a", "b"])` | restructure | | `attachPropertySignature("k", "v")` | `mapFields(f => ({...f, k: tagDefaultOmit("v")}))` | restructure | | `validate*` | removed (use `decode*` + `toType`) | removed | | `keyof` | — | removed | | `NonEmptyArrayEnsure` | — | removed | | `withDefaults` | — | removed | | `Data(schema)` | — | removed | | `optionalWith(schema, opts)` | varies by options (see [optionalWith](#optionalwith)) | manual | | `optionalToOptional` | see [optional field transformations](#optional-field-transformations) | manual | | `optionalToRequired` | see [optional field transformations](#optional-field-transformations) | manual | | `requiredToOptional` | see [optional field transformations](#optional-field-transformations) | manual | | `filterEffect` | see [filterEffect](#filtereffect) | manual | | `fromKey` | see [rename](#rename) | manual | | `rename({ a: "c" })` | see [rename](#rename) | manual | | `format(schema)` | see [format](#format) | manual | | `ParseResult.ArrayFormatter.formatError(error)` | see [ParseResult formatters](#parseresult-formatters) | manual | | `declare` | see [declare](#declare) | manual | ## Additional rename notes ### `*FromSelf` renames The following `*FromSelf` schemas have been renamed to drop the suffix: `DateFromSelf` → `Date`, `DurationFromSelf` → `Duration`, `ChunkFromSelf` → `Chunk`, `ReadonlyMapFromSelf` → `ReadonlyMap`, `ReadonlySetFromSelf` → `ReadonlySet`, `HashMapFromSelf` → `HashMap`, `HashSetFromSelf` → `HashSet`, `BigDecimalFromSelf` → `BigDecimal`, `CauseFromSelf` → `Cause`, `ExitFromSelf` → `Exit`, `OptionFromSelf` → `Option`, `RegExpFromSelf` → `RegExp` ### Filter renames All filters have been renamed with an `is` prefix and now use `check(...)` or `pipe(Schema.check(...))`: `greaterThan` → `isGreaterThan`, `greaterThanOrEqualTo` → `isGreaterThanOrEqualTo`, `lessThan` → `isLessThan`, `lessThanOrEqualTo` → `isLessThanOrEqualTo`, `between` → `isBetween`, `int` → `isInt`, `multipleOf` → `isMultipleOf`, `finite` → `isFinite`, `minLength` → `isMinLength`, `maxLength` → `isMaxLength`, `length` → `isLengthBetween` Note: `positive`, `negative`, `nonNegative`, `nonPositive` have been removed in v4. ### Utility renames `equivalence` → `toEquivalence`, `arbitrary` → `toArbitrary`, `pretty` → `toFormatter`, `standardSchemaV1` → `toStandardSchemaV1` ## Detailed migrations ### validate* removal **Migration: removed** The `validate`, `validateEither`, `validatePromise`, `validateSync`, and `validateOption` APIs have been removed. Use `Schema.decode*` + `Schema.toType` instead. ```ts import { Schema } from "effect" // v3: Schema.validateSync(Schema.String)(input) // v4: const validateSync = Schema.decodeSync(Schema.toType(Schema.String)) ``` ### Data removal **Migration: removed** `Schema.Data` has no v4 equivalent. Remove it. `Equal.equals` performs deep structural comparison on objects by default in v4, so `Schema.Data` is unnecessary. ### pickLiterals **Migration: auto** v3 ```ts import { Schema } from "effect" const schema = Schema.Literal("a", "b", "c").pipe(Schema.pickLiteral("a", "b")) ``` v4 ```ts import { Schema } from "effect" const schema = Schema.Literals(["a", "b", "c"]).pick(["a", "b"]) ``` ### TemplateLiteralParser **Migration: semi-auto** v3 ```ts import { Schema } from "effect" const schema = Schema.TemplateLiteral(Schema.String, ".", Schema.String) const parser = Schema.TemplateLiteralParser(Schema.String, ".", Schema.String) ``` v4 ```ts import { Schema } from "effect" const schema = Schema.TemplateLiteral([Schema.String, ".", Schema.String]) // use the `parts` property instead of repeating the template parts const parser = Schema.TemplateLiteralParser(schema.parts) ``` ### format **Migration: manual** **New imports:** `SchemaRepresentation` v3 ```ts import { Schema } from "effect" console.log(Schema.format(Schema.String)) // string ``` v4 ```ts import { Schema, SchemaRepresentation } from "effect" const doc = SchemaRepresentation.fromAST(Schema.String.ast) const multi = SchemaRepresentation.toMultiDocument(doc) const codeDoc = SchemaRepresentation.toCodeDocument(multi) console.log(codeDoc.codes[0].Type) // string ``` ### ParseResult formatters **Migration: manual** **New imports:** `SchemaIssue` In v4, schema parsing fails with `Schema.SchemaError`, which contains a nested `SchemaIssue` in its `issue` field. Use `SchemaIssue.makeFormatterStandardSchemaV1()(error.issue).issues` for the v3 `ParseResult.ArrayFormatter.formatError(error)` equivalent. v3 ```ts import { Either, ParseResult, Schema } from "effect" const Person = Schema.Struct({ name: Schema.String, age: Schema.Number }) const decode = Schema.decodeUnknownEither(Person) const result = decode({}) if (Either.isLeft(result)) { console.error("Decoding failed:") console.error(ParseResult.ArrayFormatter.formatErrorSync(result.left)) } /* Decoding failed: [ { _tag: 'Missing', path: [ 'name' ], message: 'is missing' } ] */ ``` v4 ```ts import { Schema, SchemaIssue } from "effect" const Person = Schema.Struct({ name: Schema.String, age: Schema.Number }) const decode = Schema.decodeUnknownSync(Person) try { decode({}) } catch (error) { if (error instanceof Error) { console.error("Decoding failed:") if (SchemaIssue.isIssue(error.cause)) { console.error(SchemaIssue.makeFormatterStandardSchemaV1()(error.cause).issues) } } } /* Decoding failed: [ { path: [ 'name' ], message: 'Missing key' } ] */ ``` ### Record **Migration: auto** v3 ```ts import { Schema } from "effect" const schema = Schema.Record({ key: Schema.String, value: Schema.Number }) ``` v4 ```ts import { Schema } from "effect" const schema = Schema.Record(Schema.String, Schema.Number) ``` ### pick / omit **Migration: semi-auto** **New imports:** `Struct` v3 ```ts import { Schema } from "effect" const picked = Schema.Struct({ a: Schema.String, b: Schema.Number }).pipe(Schema.pick("a")) const omitted = Schema.Struct({ a: Schema.String, b: Schema.Number }).pipe(Schema.omit("b")) ``` v4 ```ts import { Schema, Struct } from "effect" const picked = Schema.Struct({ a: Schema.String, b: Schema.Number }).mapFields(Struct.pick(["a"])) const omitted = Schema.Struct({ a: Schema.String, b: Schema.Number }).mapFields(Struct.omit(["b"])) ``` ### partial / partialWith **Migration: semi-auto** **New imports:** `Struct` - `Schema.partial` → `mapFields(Struct.map(Schema.optional))` (allows `undefined`) - `Schema.partialWith({ exact: true })` → `mapFields(Struct.map(Schema.optionalKey))` (exact) ```ts import { Schema, Struct } from "effect" const struct = Schema.Struct({ a: Schema.String, b: Schema.Number }) // v3: struct.pipe(Schema.partial) const withUndefined = struct.mapFields(Struct.map(Schema.optional)) // v3: struct.pipe(Schema.partialWith({ exact: true })) const exact = struct.mapFields(Struct.map(Schema.optionalKey)) ``` You can also make a subset of fields partial: ```ts import { Schema, Struct } from "effect" const schema = Schema.Struct({ a: Schema.String, b: Schema.Number }) .mapFields(Struct.mapPick(["a"], Schema.optional)) ``` ### required **Migration: semi-auto** **New imports:** `Struct` - `Schema.requiredKey`: makes `optionalKey` fields required; makes `optional` fields required as `T | undefined` - `Schema.required`: makes `optional` fields required (removes `undefined`) ```ts import { Schema, Struct } from "effect" const original = Schema.Struct({ a: Schema.optionalKey(Schema.String), b: Schema.optionalKey(Schema.Number) }) // v3: Schema.required(original) const schema = original.mapFields(Struct.map(Schema.requiredKey)) // { readonly a: string; readonly b: number; } ``` ### optional field transformations **Migration: manual** **New imports:** `SchemaGetter` `optionalToOptional`, `optionalToRequired`, and `requiredToOptional` are all replaced by `Schema.decodeTo` + `SchemaGetter.transformOptional`. The pattern: start with the encoded optionality (`optionalKey` or required), pipe to `decodeTo` with the decoded optionality, and provide `transformOptional` functions for decode/encode. **Example** (v3 `optionalToRequired`: setting `null` as default for missing field) v3 ```ts import { Option, Schema } from "effect" const schema = Schema.Struct({ a: Schema.optionalToRequired(Schema.String, Schema.NullOr(Schema.String), { decode: Option.getOrElse(() => null), encode: Option.liftPredicate((value) => value !== null) }) }) ``` v4 ```ts import { Option, Schema, SchemaGetter } from "effect" const schema = Schema.Struct({ a: Schema.optionalKey(Schema.String).pipe( Schema.decodeTo(Schema.NullOr(Schema.String), { decode: SchemaGetter.transformOptional(Option.orElseSome(() => null)), encode: SchemaGetter.transformOptional(Option.filter((value) => value !== null)) }) ) }) ``` **Example** (v3 `requiredToOptional`: empty string as missing value) v3 ```ts import { Option, Schema } from "effect" const schema = Schema.Struct({ a: Schema.requiredToOptional(Schema.String, Schema.String, { decode: Option.liftPredicate((s) => s !== ""), encode: Option.getOrElse(() => "") }) }) ``` v4 ```ts import { Option, Schema, SchemaGetter } from "effect" const schema = Schema.Struct({ a: Schema.String.pipe( Schema.decodeTo(Schema.optionalKey(Schema.String), { decode: SchemaGetter.transformOptional(Option.filter((value) => value !== "")), encode: SchemaGetter.transformOptional(Option.orElseSome(() => "")) }) ) }) ``` ### optionalWith **Migration: manual** **New imports:** `SchemaGetter`, `Predicate` (for nullable variants) #### Decision tree | v3 options | v4 pattern | | ------------------------------------------ | ----------------------------------------------------------------------- | | `{ exact: true }` | `optionalKey(schema)` | | `{ default }` | `schema.pipe(withDecodingDefault(...))` | | `{ exact: true, default }` | `schema.pipe(withDecodingDefaultKey(...))` | | `{ nullable: true }` | `optional(NullOr(schema))` + `decodeTo` + filter null | | `{ nullable: true, exact: true }` | `optionalKey(NullOr(schema))` + `decodeTo` + filter null | | `{ nullable: true, default }` | `optional(NullOr(schema))` + `decodeTo` + filter null + `orElseSome` | | `{ nullable: true, exact: true, default }` | `optionalKey(NullOr(schema))` + `decodeTo` + filter null + `orElseSome` | Key rules: - `exact: true` → use `optionalKey` instead of `optional` - `nullable: true` → wrap inner schema in `NullOr` and filter nulls via `Option.filter(Predicate.isNotNull)` - `default` → use `withDecodingDefault` (or `withDecodingDefaultKey` with `exact: true`) #### Example: `{ exact: true }` (simplest case) v3 ```ts import { Schema } from "effect" const schema = Schema.Struct({ a: Schema.optionalWith(Schema.NumberFromString, { exact: true }) }) ``` v4 ```ts import { Schema } from "effect" const schema = Schema.Struct({ a: Schema.optionalKey(Schema.NumberFromString) }) ``` #### Example: `{ default }` v3 ```ts import { Schema } from "effect" const schema = Schema.Struct({ a: Schema.optionalWith(Schema.String, { default: () => "" }) }) ``` v4 ```ts import { Effect, Schema } from "effect" const schema = Schema.Struct({ a: Schema.String.pipe(Schema.withDecodingDefault(Effect.succeed(""))) }) ``` #### Example: `{ exact: true, default }` v3 ```ts import { Schema } from "effect" const schema = Schema.Struct({ a: Schema.optionalWith(Schema.String, { exact: true, default: () => "" }) }) ``` v4 ```ts import { Effect, Schema } from "effect" const schema = Schema.Struct({ a: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(""))) }) ``` #### Example: `{ nullable: true, exact: true, default }` (most complex case) v3 ```ts import { Schema } from "effect" const schema = Schema.Struct({ a: Schema.optionalWith(Schema.NumberFromString, { nullable: true, default: () => -1, exact: true }) }) ``` v4 ```ts import { Option, Predicate, Schema, SchemaGetter } from "effect" const schema = Schema.Struct({ a: Schema.optionalKey(Schema.NullOr(Schema.NumberFromString)).pipe( Schema.decodeTo(Schema.Number, { decode: SchemaGetter.transformOptional((o) => o.pipe(Option.filter(Predicate.isNotNull), Option.orElseSome(() => -1)) ), encode: SchemaGetter.required() }) ) }) ``` ### pluck **Migration: manual** **New imports:** `SchemaGetter`, `Struct` v3 ```ts import { Schema } from "effect" const schema = Schema.Struct({ a: Schema.String, b: Schema.Number }).pipe(Schema.pluck("a")) ``` v4 ```ts import { Schema, SchemaGetter, Struct } from "effect" function pluck
(key: P) {
return (
schema: Schema.Struct<{ [K in P]: S }>
): Schema.decodeTo