schema

Schema in Effect

Overview

Effect Schema provides:

• Type-safe validation - Runtime checks with TypeScript inference
• Bidirectional transformation - Decode from external, encode for output
• Composable schemas - Build complex types from primitives
• Error messages - Detailed, customizable validation errors
• Interop - JSON Schema, Pretty Printing, Arbitrary generation

Schema Best Practices

1. Tagged Unions Over Optional Properties

AVOID optional properties. USE tagged unions instead. This makes states explicit and enables exhaustive pattern matching.

// ❌ BAD: Optional properties hide state complexity
const User = Schema.Struct({
  id: Schema.String,
  name: Schema.String,
  email: Schema.optional(Schema.String),
  verifiedAt: Schema.optional(Schema.Date),
  suspendedReason: Schema.optional(Schema.String),
});
// Unclear: Can a user be both verified AND suspended? What if email is missing?

// ✅ GOOD: Tagged union makes states explicit
const User = Schema.Union(
  Schema.Struct({
    _tag: Schema.Literal("Unverified"),
    id: Schema.String,
    name: Schema.String,
  }),
  Schema.Struct({
    _tag: Schema.Literal("Active"),
    id: Schema.String,
    name: Schema.String,
    email: Schema.String,
    verifiedAt: Schema.Date,
  }),
  Schema.Struct({
    _tag: Schema.Literal("Suspended"),
    id: Schema.String,
    name: Schema.String,
    email: Schema.String,
    suspendedReason: Schema.String,
  }),
);
// Clear: Each state has exactly the fields it needs

Why tagged unions:

• No impossible states (suspended user always has a reason)
• Exhaustive matching catches missing cases
• Self-documenting state machine
• Works perfectly with Match.tag

2. Class-Based Schemas Over Struct Schemas

PREFER Schema.Class over Schema.Struct. Classes give you methods, Schema.is() type guards, and better ergonomics.

// ❌ AVOID: Plain Struct (no methods, no Schema.is() support)
const UserStruct = Schema.Struct({
  id: Schema.String,
  firstName: Schema.String,
  lastName: Schema.String,
  email: Schema.String,
});
type User = Schema.Schema.Type<typeof UserStruct>;

// ✅ PREFER: Class-based Schema
class User extends Schema.Class<User>("User")({
  id: Schema.String,
  firstName: Schema.String,
  lastName: Schema.String,
  email: Schema.String,
}) {
  get fullName() {
    return `${this.firstName} ${this.lastName}`;
  }

  get emailDomain() {
    return this.email.split("@")[1];
  }

  withEmail(email: string) {
    return new User({ ...this, email });
  }
}

// Usage:
const user = Schema.decodeUnknownSync(User)(data);
console.log(user.fullName); // "John Doe"
console.log(Schema.is(User)(user)); // true - use Schema.is() for type checks

For tagged unions with classes:

class Unverified extends Schema.TaggedClass<Unverified>()("Unverified", {
  id: Schema.String,
  name: Schema.String,
}) {}

class Active extends Schema.TaggedClass<Active>()("Active", {
  id: Schema.String,
  name: Schema.String,
  email: Schema.String,
  verifiedAt: Schema.Date,
}) {
  get isRecent() {
    return Date.now() - this.verifiedAt.getTime() < 86400000;
  }
}

class Suspended extends Schema.TaggedClass<Suspended>()("Suspended", {
  id: Schema.String,
  name: Schema.String,
  suspendedReason: Schema.String,
}) {}

const User = Schema.Union(Unverified, Active, Suspended);
type User = Schema.Schema.Type<typeof User>;

3. Schema.is() with Match Patterns

USE Schema.is() as type guards in Match.when patterns. This combines Schema validation with Match's exhaustive checking.

import { Schema, Match } from "effect";

// Define schemas
class Circle extends Schema.TaggedClass<Circle>()("Circle", {
  radius: Schema.Number,
}) {
  get area() {
    return Math.PI * this.radius ** 2;
  }
}

class Rectangle extends Schema.TaggedClass<Rectangle>()("Rectangle", {
  width: Schema.Number,
  height: Schema.Number,
}) {
  get area() {
    return this.width * this.height;
  }
}

const Shape = Schema.Union(Circle, Rectangle);
type Shape = Schema.Schema.Type<typeof Shape>;

// Use Schema.is() in Match patterns
const describeShape = (shape: Shape) =>
  Match.value(shape).pipe(
    Match.when(Schema.is(Circle), (c) => `Circle with radius ${c.radius}`),
    Match.when(Schema.is(Rectangle), (r) => `${r.width}x${r.height} rectangle`),
    Match.exhaustive,
  );

// Schema.is() also works for runtime type checking
const processUnknown = (input: unknown) => {
  if (Schema.is(Circle)(input)) {
    console.log(`Circle area: ${input.area}`);
  }
};

Schema.is() vs Match.tag:

// Match.tag - when you already know it's the union type
const handleUser = (user: User) =>
  Match.value(user).pipe(
    Match.tag("Active", (u) => sendEmail(u.email)),
    Match.tag("Suspended", (u) => logSuspension(u.suspendedReason)),
    Match.tag("Unverified", () => sendVerificationReminder()),
    Match.exhaustive,
  );

// Schema.is() - when validating unknown data or need class features
const handleUnknown = (input: unknown) =>
  Match.value(input).pipe(
    Match.when(Schema.is(Active), (u) => u.isRecent), // Can use class methods
    Match.when(Schema.is(Suspended), () => false),
    Match.orElse(() => false),
  );

NEVER access ._tag directly:

// ❌ FORBIDDEN - direct ._tag access
if (user._tag === "Active") { ... }
const isActive = user._tag === "Active"

// ❌ FORBIDDEN - ._tag in type definitions
type UserTag = User["_tag"]  // Never extract _tag as a type

// ❌ FORBIDDEN - ._tag in array predicates
const hasActive = users.some((u) => u._tag === "Active")
const activeUsers = users.filter((u) => u._tag === "Active")
const activeCount = users.filter((u) => u._tag === "Active").length

// ✅ REQUIRED - Schema.is() as array predicate
const hasActive = users.some(Schema.is(Active))
const activeUsers = users.filter(Schema.is(Active))
const activeCount = users.filter(Schema.is(Active)).length

// ✅ REQUIRED - use Match.tag or Schema.is()
const handleUser = Match.type<User>().pipe(
  Match.tag("Active", (u) => ...),
  Match.exhaustive
)

// ✅ REQUIRED - Schema.is() for type guards
const isActive = Schema.is(Active)
if (isActive(user)) { ... }

4. Never Use Schema.Any or Schema.Unknown for Type Weakening

Schema.Any and Schema.Unknown are ONLY permitted when the value is genuinely unconstrained at the domain level. Using them to avoid writing a proper schema is type weakening and defeats the purpose of Schema-first modeling.

Semantically correct uses (ALLOWED):

// ✅ Error `cause` capturing arbitrary caught exceptions - the value is genuinely unknown
class NetworkError extends Schema.TaggedError<NetworkError>()("NetworkError", {
  url: Schema.String,
  cause: Schema.Unknown,
}) {}

// ✅ A generic container that truly accepts any value (e.g., a cache, event metadata)
class CacheEntry extends Schema.Class<CacheEntry>("CacheEntry")({
  key: Schema.String,
  value: Schema.Unknown, // Cache genuinely stores arbitrary data
  ttl: Schema.Number,
}) {}

// ✅ Schema.parseJson without a target schema to get raw parsed JSON
const RawJson = Schema.parseJson(); // Produces Schema<unknown>
// This is fine as an intermediate step before further validation

Type weakening (FORBIDDEN):

// ❌ FORBIDDEN: Lazy schema definition - write the actual shape
const UserResponse = Schema.Struct({
  data: Schema.Unknown, // What is "data"? Define it!
});

// ❌ FORBIDDEN: Avoiding nested schema definition
const ApiResponse = Schema.Struct({
  body: Schema.Any, // Write the actual body schema
});

// ❌ FORBIDDEN: Using Schema.Unknown for "I'll validate later"
const input: Schema.Schema<unknown> = Schema.Unknown;
// Define the correct schema upfront

// ❌ FORBIDDEN: Using Schema.Any to bypass type checking
const config = Schema.Struct({
  settings: Schema.Any, // Define the settings shape!
});

How to fix type-weakened schemas:

// ❌ Before: type-weakened
const ApiResponse = Schema.Struct({
  data: Schema.Unknown,
  meta: Schema.Any,
});

// ✅ After: properly typed
class ApiResponse extends Schema.Class<ApiResponse>("ApiResponse")({
  data: Schema.Struct({
    users: Schema.Array(User),
    total: Schema.Number,
  }),
  meta: Schema.Struct({
    page: Schema.Number,
    perPage: Schema.Number,
    requestId: Schema.String,
  }),
}) {}

Rule of thumb: If you can describe the shape of the data, you MUST define a proper schema. Schema.Unknown is only for values that are genuinely opaque (caught exceptions, plugin payloads from unknown sources, serialized blobs you pass through without inspecting). Schema.Any should almost never appear in application code.

Basic Schemas

import { Schema } from "effect";

// Primitives
const str = Schema.String;
const num = Schema.Number;
const bool = Schema.Boolean;
const bigint = Schema.BigInt;

// Literals
const status = Schema.Literal("pending", "active", "completed");

// Enums
enum Color {
  Red,
  Green,
  Blue,
}
const color = Schema.Enums(Color);

Decoding and Encoding

Decoding (External → Internal)

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.Number,
});

// Sync decode (throws on error)
const person = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 });

// Effect-based decode
const person = yield * Schema.decodeUnknown(Person)(input);

// Either result
const result = Schema.decodeUnknownEither(Person)(input);

Encoding (Internal → External)

const encoded = Schema.encodeSync(Person)(person);
const encoded = yield * Schema.encode(Person)(person);

Struct Schemas

const User = Schema.Struct({
  id: Schema.Number,
  name: Schema.String,
  email: Schema.String,
  createdAt: Schema.Date,
});

// Optional fields
const UserWithOptional = Schema.Struct({
  id: Schema.Number,
  name: Schema.String,
  nickname: Schema.optional(Schema.String),
});

// Optional with default
const UserWithDefault = Schema.Struct({
  id: Schema.Number,
  role: Schema.optional(Schema.String).pipe(Schema.withDefault(() => "user")),
});

Array and Record

// Array
const Numbers = Schema.Array(Schema.Number);
const Users = Schema.Array(User);

// Non-empty array
const NonEmptyStrings = Schema.NonEmptyArray(Schema.String);

// Record
const StringRecord = Schema.Record({
  key: Schema.String,
  value: Schema.Number,
});

Union and Discriminated Unions

// Simple union
const StringOrNumber = Schema.Union(Schema.String, Schema.Number);

// Discriminated union (recommended)
const Shape = Schema.Union(
  Schema.Struct({
    _tag: Schema.Literal("Circle"),
    radius: Schema.Number,
  }),
  Schema.Struct({
    _tag: Schema.Literal("Rectangle"),
    width: Schema.Number,
    height: Schema.Number,
  }),
);

Transformations

Schema.transform

// String ↔ Number
const NumberFromString = Schema.transform(Schema.String, Schema.Number, {
  decode: (s) => parseFloat(s),
  encode: (n) => String(n),
});

// Usage: "42" decodes to 42, 42 encodes to "42"

Built-in Transformations

// String to Number
const num = Schema.NumberFromString;

// String to Date
const date = Schema.DateFromString;

// Parse JSON string
const jsonData = Schema.parseJson(
  Schema.Struct({
    name: Schema.String,
  }),
);

JSON Parsing with Schema.parseJson

NEVER use JSON.parse() directly. Always use Schema.parseJson to combine JSON parsing with schema validation in one step.

Why Schema.parseJson over JSON.parse

// ❌ BAD: JSON.parse gives you `any` and can throw
const data = JSON.parse(jsonString); // type: any, throws on invalid JSON

// ❌ BAD: Even with Schema, this is two separate failure points
const parsed = JSON.parse(jsonString); // Can throw!
const validated = Schema.decodeUnknownSync(MySchema)(parsed);

// ✅ GOOD: Schema.parseJson handles both in one type-safe step
const MyData = Schema.parseJson(
  Schema.Struct({
    name: Schema.String,
    count: Schema.Number,
  }),
);

// Sync version - throws ParseError (not generic Error)
const data = Schema.decodeUnknownSync(MyData)('{"name": "test", "count": 42}');

// Effect version - typed error handling
const program = Schema.decodeUnknown(MyData)(jsonString);
// Effect<{ name: string, count: number }, ParseError, never>

Schema.parseJson Benefits

1. Single failure point - Invalid JSON or invalid structure both produce ParseError
2. Type safety - Result is fully typed, never any
3. Effect integration - Works seamlessly with Effect error handling
4. Detailed errors - ParseError includes path and validation details

Common Patterns

// API response parsing
const ApiResponse = Schema.parseJson(
  Schema.Struct({
    success: Schema.Boolean,
    data: Schema.Struct({
      id: Schema.String,
      name: Schema.String,
    }),
  }),
);

// With optional reviver schema for complex decoding
const WithDate = Schema.parseJson(
  Schema.Struct({
    createdAt: Schema.Date, // Automatically handles ISO date strings
  }),
);

// Nested JSON (JSON string containing JSON string)
const NestedConfig = Schema.parseJson(
  Schema.Struct({
    settings: Schema.parseJson(
      Schema.Struct({
        theme: Schema.String,
      }),
    ),
  }),
);

In Effect Programs

import { Effect, Schema } from "effect";

const ConfigSchema = Schema.parseJson(
  Schema.Struct({
    apiKey: Schema.String,
    endpoint: Schema.String,
    retries: Schema.Number,
  }),
);

const loadConfig = (jsonString: string) =>
  Effect.gen(function* () {
    const config = yield* Schema.decodeUnknown(ConfigSchema)(jsonString);
    return config;
  });

// Errors are typed and can be handled with Effect.catchTag
const program = loadConfig(rawJson).pipe(
  Effect.catchTag("ParseError", (e) => Effect.fail(new ConfigurationError({ cause: e }))),
);

Filters (Validation)

// String constraints
const Email = Schema.String.pipe(Schema.pattern(/^[^@]+@[^@]+\.[^@]+$/), Schema.annotations({ identifier: "Email" }));

const Username = Schema.String.pipe(Schema.minLength(3), Schema.maxLength(20), Schema.pattern(/^[a-z0-9_]+$/));

// Number constraints
const Age = Schema.Number.pipe(Schema.int(), Schema.between(0, 150));

const PositiveNumber = Schema.Number.pipe(Schema.positive());

// Custom filter
const EvenNumber = Schema.Number.pipe(
  Schema.filter((n) => n % 2 === 0, {
    message: () => "Expected even number",
  }),
);

Branded Types

const UserId = Schema.String.pipe(Schema.brand("UserId"));
type UserId = Schema.Schema.Type<typeof UserId>;
// type UserId = string & Brand<"UserId">

const OrderId = Schema.Number.pipe(Schema.int(), Schema.positive(), Schema.brand("OrderId"));

Class-Based Schemas

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.String,
  email: Schema.String,
}) {
  get displayName() {
    return `${this.name} (${this.email})`;
  }
}

// Decode creates Person instance
const person = Schema.decodeUnknownSync(Person)({
  id: 1,
  name: "Alice",
  email: "alice@example.com",
});
console.log(person.displayName); // "Alice (alice@example.com)"

Tagged Errors with Schema

class UserNotFound extends Schema.TaggedError<UserNotFound>()("UserNotFound", { userId: Schema.String }) {}

class ValidationError extends Schema.TaggedError<ValidationError>()("ValidationError", {
  errors: Schema.Array(Schema.String),
}) {}

Annotations

const User = Schema.Struct({
  id: Schema.Number.pipe(
    Schema.annotations({
      identifier: "UserId",
      title: "User ID",
      description: "Unique user identifier",
      examples: [1, 2, 3],
    }),
  ),
  email: Schema.String.pipe(
    Schema.annotations({
      identifier: "Email",
      description: "User email address",
    }),
  ),
});

Error Messages

Custom Messages

const Password = Schema.String.pipe(
  Schema.minLength(8, {
    message: () => "Password must be at least 8 characters",
  }),
  Schema.pattern(/[A-Z]/, {
    message: () => "Password must contain uppercase letter",
  }),
  Schema.pattern(/[0-9]/, {
    message: () => "Password must contain a number",
  }),
);

Formatting Errors

import { TreeFormatter, ArrayFormatter } from "effect/ParseResult";

const result = Schema.decodeUnknownEither(User)(input);
Either.match(result, {
  onLeft: (error) => {
    // Tree format
    console.log(TreeFormatter.formatErrorSync(error));

    // Array format
    console.log(ArrayFormatter.formatErrorSync(error));
  },
  onRight: () => {
    // Valid input, no errors to format
  },
});

JSON Schema Export

import { JSONSchema } from "effect";

const jsonSchema = JSONSchema.make(User);
// Produces JSON Schema compatible output

Common Patterns

API Response Validation

const ApiResponse = <A>(dataSchema: Schema.Schema<A>) =>
  Schema.Struct({
    success: Schema.Boolean,
    data: dataSchema,
    timestamp: Schema.DateFromString,
  });

const UserResponse = ApiResponse(User);

Form Validation

const RegistrationForm = Schema.Struct({
  username: Schema.String.pipe(Schema.minLength(3), Schema.maxLength(20)),
  email: Schema.String.pipe(Schema.pattern(emailRegex)),
  password: Schema.String.pipe(Schema.minLength(8)),
  confirmPassword: Schema.String,
}).pipe(Schema.filter((form) => (form.password === form.confirmPassword ? undefined : "Passwords must match")));

Recursive Schemas

interface Category {
  name: string;
  subcategories: readonly Category[];
}

const Category: Schema.Schema<Category> = Schema.Struct({
  name: Schema.String,
  subcategories: Schema.Array(Schema.suspend(() => Category)),
});

Best Practices Summary

Do

1. Use tagged unions over optional properties - Make states explicit
2. Use Schema.Class/TaggedClass over Struct - Get methods and Schema.is() type guards
3. Use Schema.is() in Match patterns - Combine validation with matching
4. Brand IDs and sensitive types - Prevent mixing up values
5. Annotate for documentation - Descriptions flow to JSON Schema
6. Transform at boundaries - Parse external data early

Don't

1. Don't use optional properties for state - Use tagged unions instead
2. Don't use plain Struct for domain entities - Use Schema.Class
3. Don't validate manually - Use Schema.is() with Match
4. Don't mix branded types - Each ID type should be distinct
5. NEVER access ._tag directly - Use Match.tag or Schema.is() instead
6. NEVER extract ._tag as a type - e.g., type Tag = Foo["_tag"] is forbidden
7. NEVER use ._tag in predicates - Use Schema.is(Variant) with .some()/.filter()
8. NEVER use Schema.Any or Schema.Unknown to avoid writing a proper schema - These are only permitted when the value is genuinely unconstrained (e.g., caught exception causes, opaque plugin payloads). If you can describe the data shape, define a real schema.

Additional Resources

For comprehensive Schema documentation, consult ${CLAUDE_PLUGIN_ROOT}/references/llms-full.txt.

Search for these sections:

• "Introduction to Effect Schema" for overview
• "Basic Usage" for getting started
• "Transformations" for bidirectional transforms
• "Filters" for validation rules
• "Class APIs" for class-based schemas
• "Error Formatters" for error handling