Agent skill

Schema

This skill should be used when the user asks about "Effect Schema", "Schema.Struct", "Schema.decodeUnknown", "data validation", "parsing", "Schema.transform", "Schema filters", "Schema annotations", "JSON Schema", "Schema.Class", "Schema branded types", "encoding", "decoding", "Schema.parseJson", or needs to understand how Effect handles data validation and transformation.

View SKILL.md on GitHub Repository

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/schema

SKILL.md

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.

typescript

// ❌ 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.

typescript

// ❌ 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:

typescript

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.

typescript

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:

typescript

// 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:

typescript

// ❌ 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):

typescript

// ✅ 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):

typescript

// ❌ 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:

typescript

// ❌ 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

typescript

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)

typescript

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)

typescript

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

Struct Schemas

typescript

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

typescript

// 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

typescript

// 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

typescript

// 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

typescript

// 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

typescript

// ❌ 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

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

Common Patterns

typescript

// 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

typescript

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)

typescript

// 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

typescript

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

typescript

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

typescript

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

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

Annotations

typescript

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

typescript

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

typescript

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

typescript

import { JSONSchema } from "effect"

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

Common Patterns

API Response Validation

typescript

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

const UserResponse = ApiResponse(User)

Form Validation

typescript

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

typescript

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

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

Don't

Don't use optional properties for state - Use tagged unions instead
Don't use plain Struct for domain entities - Use Schema.Class
Don't validate manually - Use Schema.is() with Match
Don't mix branded types - Each ID type should be distinct
NEVER access ._tag directly - Use Match.tag or Schema.is() instead
NEVER extract ._tag as a type - e.g., type Tag = Foo["_tag"] is forbidden
NEVER use ._tag in predicates - Use Schema.is(Variant) with .some()/.filter()
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

Maintainer

majiayu000 Core maintainer

Source details

Full Name: majiayu000/claude-skill-registry
Branch: main
Path in repo: skills/data/schema
License: MIT License

Featured Tools

Join Our Newsletter

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Schema in Effect

Overview

Schema Best Practices

1. Tagged Unions Over Optional Properties

2. Class-Based Schemas Over Struct Schemas

3. Schema.is() with Match Patterns

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

Basic Schemas

Decoding and Encoding

Decoding (External → Internal)

Encoding (Internal → External)

Struct Schemas

Array and Record

Union and Discriminated Unions

Transformations

Schema.transform

Built-in Transformations

JSON Parsing with Schema.parseJson

Why Schema.parseJson over JSON.parse

Schema.parseJson Benefits

Common Patterns

In Effect Programs

Filters (Validation)

Branded Types

Class-Based Schemas

Tagged Errors with Schema

Annotations

Error Messages

Custom Messages

Formatting Errors

JSON Schema Export

Common Patterns

API Response Validation

Form Validation

Recursive Schemas

Best Practices Summary

Do

Don't

Additional Resources

Recommended Agent Skills

agent-ops-spec

agent-ops-state

agent-ops-spec

agent-ops-testing

agent-ops-testing

agent-ops-state