effect-schema-composition

Schema Composition Skill

Expert guidance for composing, transforming, and validating data with Effect Schema (v4).

Effect Source Reference

The Effect v4 source is available at ~/.cache/effect-v4/. Browse and read files there directly to look up APIs, types, and implementations.

Reference this for:

• Full Schema API: packages/effect/SCHEMA.md
• Schema source: packages/effect/src/Schema.ts
• SchemaTransformation source: packages/effect/src/SchemaTransformation.ts
• Migration guide: MIGRATION.md
• Effect source: packages/effect/src/

Core Concepts

The Schema Type

Every schema in Effect has the type signature Schema<Type, Encoded, Context> where:

• Type: The validated, decoded output type (what you get after successful decoding)
• Encoded: The raw input type (what you provide for decoding)
• Context: External dependencies required for encoding/decoding (often never)

Example:

import { Schema } from 'effect';

// Schema<number, string, never>
//        ^Type  ^Encoded ^Context
const NumberFromString = Schema.NumberFromString;

Decoding vs Encoding

• Decoding: Transform Encoded → Type (e.g., string "123" → number 123)
• Encoding: Transform Type → Encoded (e.g., number 123 → string "123")

Effect Schema follows "parse, don't validate" — schemas transform data into the desired format, not just check validity.

Schema.decodeTo — Chaining Transformations

Use Schema.decodeTo to chain schemas with different types at each stage. It connects the output type of one schema to the input type of another. This replaces the v3 Schema.compose.

When to Use:

• Multi-step transformations where each stage changes the type
• Connecting parsing and validation steps
• Building pipelines from Encoded → Intermediate → Type

Example — Schema composition (no transformation):

import { Schema, SchemaTransformation } from 'effect';

// Convert meters → kilometers → miles via schema composition
const KilometersFromMeters = Schema.Finite.pipe(
	Schema.decode(
		SchemaTransformation.transform({
			decode: (meters) => meters / 1000,
			encode: (kilometers) => kilometers * 1000
		})
	)
);

const MilesFromKilometers = Schema.Finite.pipe(
	Schema.decode(
		SchemaTransformation.transform({
			decode: (kilometers) => kilometers * 0.621371,
			encode: (miles) => miles / 0.621371
		})
	)
);

// Compose the two schemas — no explicit transformation needed
const MilesFromMeters = KilometersFromMeters.pipe(
	Schema.decodeTo(MilesFromKilometers)
);