Union Types  More Details
Syntax
Syntactically, unions follow the same rules as intersections, but have a lower precedence, see Intersection Types  More Details.
Interaction with pattern matching syntax

is also used in pattern matching to separate pattern alternatives and has lower precedence than :
as used in typed patterns, this means that:
case _: A  B => ...
is still equivalent to:
case (_: A)  B => ...
and not to:
case _: (A  B) => ...
Subtyping Rules

A
is always a subtype ofA  B
for allA
,B
. 
If
A <: C
andB <: C
thenA  B <: C

Like
&
,
is commutative and associative:A  B =:= B  A A  (B  C) =:= (A  B)  C

&
is distributive over
:A & (B  C) =:= A & B  A & C
From these rules it follows that the least upper bound (LUB) of a set of types is the union of these types. This replaces the definition of least upper bound in the Scala 2 specification.
Motivation
The primary reason for introducing union types in Scala is that they allow us to guarantee that for every set of types, we can always form a finite LUB. This is both useful in practice (infinite LUBs in Scala 2 were approximated in an adhoc way, resulting in imprecise and sometimes incredibly long types) and in theory (the type system of Scala 3 is based on the DOT calculus, which has union types).
Additionally, union types are a useful construct when trying to give types to existing dynamically typed APIs, this is why they're an integral part of TypeScript and have even been partially implemented in Scala.js.
Join of a union type
In some situation described below, a union type might need to be widened to a nonunion type, for this purpose we define the join of a union type T1  ...  Tn
as the smallest intersection type of base class instances of T1
,...,Tn
. Note that union types might still appear as type arguments in the resulting type, this guarantees that the join is always finite.
The visible join of a union type is its join where all operands of the intersection that are instances of transparent traits or classes are removed.
Example
Given
trait C[+T]
trait D
trait E
transparent trait X
class A extends C[A], D, X
class B extends C[B], D, E, X
The join of A  B
is C[A  B] & D & X
and the visible join of A  B
is C[A  B] & D
.
Hard and Soft Union Types
We distinguish between hard and soft union types. A hard union type is a union type that's explicitly written in the source. For instance, in
val x: Int  String = ...
Int  String
would be a hard union type. A soft union type is a type that arises from type checking an alternative of expressions. For instance, the type of the expression
val x = 1
val y = "abc"
if cond then x else y
is the soft unon type Int  String
. Similarly for match expressions. The type of
x match
case 1 => x
case 2 => "abc"
case 3 => List(1, 2, 3)
is the soft union type Int  "abc"  List[Int]
.
Type inference
When inferring the result type of a definition (val
, var
, or def
) and the type we are about to infer is a soft union type, then we replace it by its visible join, provided it is not empty. Similarly, when instantiating a type argument, if the corresponding type parameter is not upperbounded by a union type and the type we are about to instantiate is a soft union type, we replace it by its visible join, provided it is not empty. This mirrors the treatment of singleton types which are also widened to their underlying type unless explicitly specified. The motivation is the same: inferring types which are "too precise" can lead to unintuitive typechecking issues later on.
Example
import scala.collection.mutable.ListBuffer
val x = ListBuffer(Right("foo"), Left(0))
val y: ListBuffer[Either[Int, String]] = x
This code typechecks because the inferred type argument to ListBuffer
in the righthand side of x
was Left[Int, Nothing]  Right[Nothing, String]
which was widened to Either[Int, String]
. If the compiler hadn't done this widening, the last line wouldn't typecheck because ListBuffer
is invariant in its argument.
Members
The members of a union type are the members of its join.
Example
The following code does not typecheck, because method hello
is not a member of AnyRef
which is the join of A  B
.
trait A { def hello: String }
trait B { def hello: String }
def test(x: A  B) = x.hello // error: value `hello` is not a member of A  B
On the other hand, the following would be allowed
trait C { def hello: String }
trait A extends C with D
trait B extends C with E
def test(x: A  B) = x.hello // ok as `hello` is a member of the join of A  B which is C
Exhaustivity checking
If the selector of a pattern match is a union type, the match is considered exhaustive if all parts of the union are covered.
Erasure
The erased type for A  B
is the erased least upper bound of the erased types of A
and B
. Quoting from the documentation of TypeErasure#erasedLub
, the erased LUB is computed as follows:
 if both argument are arrays of objects, an array of the erased LUB of the element types
 if both arguments are arrays of same primitives, an array of this primitive
 if one argument is array of primitives and the other is array of objects,
Object
 if one argument is an array,
Object
 otherwise a common superclass or trait S of the argument classes, with the following two properties:
 S is minimal: no other common superclass or trait derives from S
 S is last : in the linearization of the first argument type
A
there are no minimal common superclasses or traits that come after S. The reason to pick last is that we prefer classes over traits that way, which leads to more predictable bytecode and (?) faster dynamic dispatch.