Model Domain with Sealed Traits

You know that moment when a Python if/elif chain grows out of control, and you're never quite sure if you covered every case? Or when a bug slips through because a new status was added to the database but the code wasn't updated? That's the problem we're solving today. In Scala, sealed traits give you a type-safe way to model a closed set of possibilities — like an enum on steroids — so the compiler itself enforces that your code handles every case. For Python developers, this is like having a linter that's also your design partner, catching missing logic before it ever ships.

The problem this lesson solves

Python's flexibility is a double-edged sword. When you model a domain — say, payment statuses, user roles, or UI states — you often reach for simple strings or integer constants. That works fine in a small script, but as your system grows, you hit real pain:

• Typos are silent killers. if status == "PROCESSED" vs if status == "PROCESSING" — one wrong letter and the logic silently doesn't run.
• No exhaustiveness checking. You write an if/elif chain for three states, then a fourth status appears in the database. Your code quietly defaults to an else branch or throws a runtime error.
• No place to attach behavior. When each state needs different fields or methods, you end up with dictionaries of tuples and a mess of conditionals scattered throughout your codebase.

enum.Enum in Python helps with constants, but it still doesn't force you to handle all cases. The compiler can't verify that you've covered every possible value. That's where sealed traits come in — they bring exhaustiveness and type safety into your domain model, catching bugs at compile time instead of at 3 AM in production.

Core concept / mental model

Think of a sealed trait as a closed family. The parent trait is like a family name, and the case objects or case classes are the children. The word sealed means the family is closed: only the children you list can exist. No one outside your file can extend the trait to add a new member.

If Python's enum is like a list of allowed strings, a sealed trait is more like a Union type with a guest list. The compiler knows the exact members, so when you pattern match, it can check that you've covered them all.

Here's a mental picture:

sealed trait OrderStatus          // family name
  ├── case object Draft            // child 1
  ├── case object Pending          // child 2
  └── case object Shipped          // child 3

Because OrderStatus is sealed, Scala knows that Draft, Pending, and Shipped are the only possible values. That knowledge is what powers exhaustive pattern matching.

How it works step by step

Step 1: Declare the sealed trait

You start with sealed trait and then define the members right below it. These members are usually case object if they have no data, or case class if they carry data.

sealed trait OrderStatus

object OrderStatus {
  case object Draft
extends OrderStatus
  case object Pending extends OrderStatus
  case object Shipped extends OrderStatus
}

Note: In Scala, the members can be defined outside the trait but must be in the same file. Usually they're placed inside the companion object for clarity, but that's a convention, not a requirement.

Step 2: Pattern match on the sealed trait

Now you can write a function that pattern matches, and the compiler can verify exhaustiveness.

import OrderStatus._

def displayName(status: OrderStatus): String = status match {
  case Draft   => "Draft"
  case Pending => "Pending"
  case Shipped => "Shipped"
}

If you forget a case, the compiler will warn you with a non-fatal warning that can be turned into an error with -Xfatal-warnings. That's your safety net.

Step 3: Carry data with case classes

When a state has data, use a case class. For example, a Shipped order needs a tracking number, while Draft has none.

sealed trait OrderStatus

object OrderStatus {
  case object Draft extends OrderStatus
  case object Pending extends OrderStatus
  final case class Shipped(tracking: String) extends OrderStatus
}

Now the pattern match can extract the tracking number.

Hands-on walkthrough

Let's build a simple domain: an order status that has two states with data and one without. You'll see how sealed traits make your code safer and more expressive.

Example 1: A basic sealed trait for payment methods

sealed trait PaymentMethod

object PaymentMethod {
  case object Cash extends PaymentMethod
  final case class Card(lastFour: String) extends PaymentMethod
  final case class PayPal(email: String) extends PaymentMethod
}

import PaymentMethod._

def describe(payment: PaymentMethod): String = payment match {
  case Cash          => "Pay with cash"
  case Card(lastFour) => s"Pay by card ending $lastFour"
  case PayPal(email)  => s"Pay via PayPal to $email"
}

println(describe(Card("1234")))
// Output: Pay by card ending 1234

If you remove the PayPal case from the match, the compiler will warn: match may not be exhaustive. That's the exhaustiveness checking in action.

Example 2: Modeling a UI state machine

sealed trait UiState

object UiState {
  case object Loading extends UiState
  final case class Success(data: List[String]) extends UiState
  final case class Error(message: String) extends UiState
}

import UiState._

def render(state: UiState): String = state match {
  case Loading           => "Loading..."
  case Success(items)    => s"Items: ${items.mkString(", ")}"
  case Error(message)    => s"Error: $message"
}

println(render(Success(List("A", "B"))))
// Output: Items: A, B

Scala 3 note: In Scala 3, you can use sealed trait and the same pattern matching works. You can also use enum which is a more direct analog to Python's enum, but sealed traits are the classic approach and more flexible.

Compare options / when to choose what

When to choose:

• Use sealed traits when you need a closed set of states with different data payloads — that's the classic domain modeling sweet spot.
• Use Python enum when you just need constant values without attached data and exhaustiveness isn't critical.
• In Scala 3, you might prefer enum for simple cases, but sealed traits still shine when you need to mix in methods or complex behaviors.

Troubleshooting & edge cases

match may not be exhaustive warning

If you forget a case, Scala emits a warning. To make it an error, add -Xfatal-warnings to your compiler flags. This is especially useful in CI.

Different casing in pattern match

A common mistake is to pattern match using the trait's name as the prefix, like case OrderStatus.Draft. That works in Scala 2 because the companion object provides a path-dependent type. In Scala 3, it's also fine, but the more idiomatic style is to import the members and use them without the prefix.

Using sealed on an abstract class

You can also use sealed abstract class instead of sealed trait. The difference is a class can have constructor parameters, a trait cannot. For most domain modeling, a sealed trait is the right choice.

Serialization and equality

Case objects are singleton and have structural equality. Case classes have structural equality too. But if you serialize to JSON, you'll need custom encoders — no magic for free. Libraries like Circe or Play JSON can derive formats, but you have to wire them up.

What you learned & what's next

You now understand how model domain with sealed traits works in Scala: you declare a closed family of types, pattern match on them exhaustively, and carry data safely. You've seen how this solves the Python issue of unchecked enums and fragile string comparisons, and you know when to prefer sealed traits vs other approaches.

Next in the track, you'll likely explore pattern matching depth or type classes — these build directly on the sealed trait pattern to make your code even more expressive and type-safe.

Keep practicing: try modeling a simple e-commerce domain with order statuses and payment methods using sealed traits, and add exhaustiveness warnings to your build to catch missing cases early.