If it walks like a duck and quacks like a duck, is it a duck? In TypeScript, yes—even if you named it a Goose. This fundamental design choice separates TypeScript from traditional object-oriented languages and creates both powerful flexibility and subtle pitfalls.
Type systems exist to catch errors before code runs. But they encode fundamentally different philosophies about what constitutes a “type.” Java and C# check whether a value explicitly declares itself to be a particular type. TypeScript checks whether a value has the right shape—the right properties with the right types—regardless of what it calls itself.
This distinction between nominal typing (typing by name) and structural typing (typing by shape) isn’t merely technical—it reflects different philosophies about identity, relationships, and what it means for two things to be compatible.
The Duck Typing Heritage
TypeScript’s structural typing directly inherits from JavaScript’s duck typing tradition. The name comes from the “duck test”: if it walks like a duck and quacks like a duck, then it must be a duck. In dynamic languages, we don’t check what something claims to be—we check what it can do.
JavaScript code commonly passes objects to functions without formal class hierarchies. A function expecting something with a render() method doesn’t care whether that object is a Button, a Canvas, or a completely ad-hoc object literal—if it has render(), it works.
When TypeScript was designed to add static typing to JavaScript, it faced a choice: impose an alien type system that would require massive refactoring of existing JavaScript patterns, or embrace JavaScript’s flexibility with compile-time guarantees. TypeScript chose the latter, making structural typing central to its design.
Core Insight: TypeScript’s structural typing isn’t a limitation or compromise—it’s a deliberate design that preserves JavaScript’s flexibility while adding safety. The type system describes JavaScript’s runtime behavior accurately.
How Structural Typing Works
In structural typing, two types are compatible if their structures match. A type defines a shape—a set of properties with specific types. Any value that has at least those properties with compatible types satisfies that type, regardless of the value’s declared type or origin.
Consider this TypeScript code:
interface Point { x: number; y: number; } interface Coordinate { x: number; y: number; } function distance(p: Point): number { return Math.sqrt(p.x * p.x + p.y * p.y); } const coord: Coordinate = { x: 3, y: 4 }; console.log(distance(coord)); // Works! Returns 5
The function distance() expects a Point, but we pass it a Coordinate. TypeScript allows this because Point and Coordinate have identical structures. They’re different names for the same shape, and in structural typing, shape is what matters.
More surprisingly, objects with additional properties also match:
const point3D = { x: 1, y: 2, z: 3, label: "origin" }; console.log(distance(point3D)); // Also works!
The object has x and y properties with number types, satisfying Point’s requirements. The extra properties (z and label) don’t disqualify it. This exemplifies width subtyping—types with more properties are subtypes of types with fewer properties.
The Philosophical Divide: Structural vs Nominal
The choice between structural and nominal typing reflects fundamentally different worldviews about classification and identity.
Aristotelian vs Platonic Classification
Nominal typing echoes Aristotelian classification systems—organisms belong to taxonomic hierarchies based on ancestry and explicit categorization. A whale is a mammal because we’ve classified it that way based on its evolutionary lineage, even though it swims like a fish.
Structural typing resembles Platonic forms more closely—things belong to types based on their essential properties. If two entities have identical essential characteristics, they belong to the same conceptual category regardless of their names or origins.
The TypeScript Handbook’s section on type compatibility acknowledges this philosophical stance explicitly: “TypeScript’s type system allows certain operations that can’t be known at compile-time to be safe.”
| Aspect | Nominal Typing (Java/C#) | Structural Typing (TypeScript) |
|---|---|---|
| Identity Basis | Declared name and hierarchy | Property shape and types |
| Compatibility | Explicit declaration required | Implicit based on structure |
| Refactoring | Breaking changes on renames | Renames rarely break code |
| Type Safety | Intentional relationships | Accidental compatibility possible |
| Verbosity | Explicit implements/extends | Minimal declarations needed |
| JavaScript Fit | Poor – foreign to JS patterns | Excellent – models JS behavior |
Why Java Developers Get Confused
Developers with Java or C# backgrounds often stumble over TypeScript’s structural typing because it violates deeply ingrained intuitions about type safety. After years of thinking nominally, structural typing feels dangerously permissive.
The Intent Problem
In Java, when you declare a class implements an interface, you’re making an explicit statement of intent. You’re saying, “this class is designed to fulfill this contract.” The type system enforces that you’ve actually implemented all required methods, but equally important, it records your intent.
Consider this Java code:
// Java interface Serializable { String serialize(); } interface Displayable { String serialize(); // Same signature, different intent! } class Document implements Serializable { public String serialize() { return "..."; } } // This is a compile error - Document doesn't implement Displayable Displayable d = new Document();
Even though Document has a serialize() method matching Displayable’s signature, Java rejects the assignment because Document never declared it implements Displayable. The developer’s intent matters.
The equivalent TypeScript code accepts the assignment silently:
// TypeScript interface Serializable { serialize(): string; } interface Displayable { serialize(): string; } class Document { serialize(): string { return "..."; } } const d: Displayable = new Document(); // Allowed!
TypeScript sees two interfaces with identical structure and a class that satisfies both. It allows the assignment because structurally, Document is compatible with Displayable. The developer’s intent doesn’t enter the equation—only the shape matters.
The “Too Permissive” Feeling
Java developers often feel TypeScript’s type checking is too loose. Code that “should” be an error passes type checking. This stems from different definitions of “should”—in nominal typing, explicit declaration determines correctness; in structural typing, shape determines correctness.
The confusion intensifies with empty interfaces:
interface Tagged {} function process(item: Tagged) { /*...*/ } process({ x: 1 }); // Works! process("hello"); // Works! process(42); // Works!
An empty interface has no structural requirements, so everything satisfies it. Java developers expect Tagged to be a marker interface requiring explicit implementation. In TypeScript, it’s an open invitation to any value.
Advantages for JavaScript Interoperability
While structural typing confuses Java developers, it’s precisely why TypeScript succeeds at typing JavaScript. JavaScript’s dynamic nature and common patterns would be nearly impossible to type with nominal typing.
Object Literals and Ad-Hoc Objects
JavaScript code constantly creates and passes anonymous objects without classes or prototypes:
// Common JavaScript pattern fetch('/api/user', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Alice', age: 30 }) });
The second argument is an object literal that’s never declared to implement any interface. Nominal typing would require declaring a class, instantiating it, and passing that—transforming idiomatic JavaScript into verbose Java-style code.
Structural typing handles this elegantly. TypeScript’s type definitions for fetch specify the expected shape of the options parameter. Any object with the right structure works, whether it’s a class instance, object literal, or dynamically constructed object.
Gradual Typing and Migration
TypeScript’s gradual typing approach allows incremental adoption—you can add types to JavaScript files one at a time. Structural typing makes this practical.
If TypeScript used nominal typing, adding types to one file would require modifying all other files that interact with it to declare proper type relationships. Dependencies would cascade, forcing either all-or-nothing adoption or breaking type checking entirely. Structural typing breaks this dependency—files become type-safe independently.
Library Compatibility
JavaScript’s ecosystem includes thousands of libraries written without TypeScript in mind. Type definitions for these libraries must describe their actual runtime behavior, not retrofit a nominal type hierarchy they never had.
Structural typing enables DefinitelyTyped—community-maintained type definitions for JavaScript libraries. These definitions describe shapes and behaviors without requiring library authors to modify their code or adopt specific type declarations.
Subtle Bugs Structural Typing Introduces
Structural typing’s flexibility comes with tradeoffs. The same permissiveness that enables JavaScript interoperability can allow bugs that nominal typing would catch.
Accidental Compatibility
The most common pitfall is accidental type compatibility—two types with the same structure but different semantic meanings become interchangeable:
interface Money { amount: number; currency: string; } interface Distance { amount: number; currency: string; // Oops, should be "unit" } function formatMoney(m: Money): string { return `${m.currency}${m.amount}`; } const distance: Distance = { amount: 100, currency: "km" }; console.log(formatMoney(distance)); // TypeScript allows this!
The Distance interface accidentally matches Money’s structure due to a poor naming choice. TypeScript accepts passing Distance to formatMoney, even though this is almost certainly a bug. In nominal typing, you’d get a compile error unless Distance explicitly extended Money.
Over-Accepting Functions
Functions that accept interfaces with minimal properties can accidentally accept inappropriate values:
interface Timestamped { timestamp: number; } function logEvent(event: Timestamped) { console.log(`Event at ${event.timestamp}`); } // These all work, even if nonsensical: logEvent({ timestamp: Date.now(), userId: 123 }); logEvent({ timestamp: Date.now(), error: "fail" }); logEvent({ timestamp: Date.now(), anything: "goes" });
Any object with a timestamp property satisfies Timestamped. If you intended logEvent to accept only specific event types, structural typing won’t enforce that without additional checks.
The Excess Property Problem
TypeScript does catch excess properties in object literals assigned directly to typed variables, but not when assigned to a variable first:
interface User { name: string; age: number; } // Error: excess property 'email' const user1: User = { name: "Alice", age: 30, email: "a@b.com" }; // No error - excess property checking doesn't apply const temp = { name: "Alice", age: 30, email: "a@b.com" }; const user2: User = temp; // Allowed!
This inconsistency confuses developers and can allow typos in property names to slip through type checking.
Common Pitfall: Structural typing means semantically distinct types with identical shapes become interchangeable. Use branded types or nominal typing techniques when semantic distinction matters more than structural compatibility.
Mitigation Strategies: Bringing Nominal Typing to TypeScript
When you need nominal-style guarantees in TypeScript, several patterns can simulate nominal typing’s strictness.
Branded Types
The most common technique uses phantom types—type properties that exist only at compile-time:
type Brand<K, T> = K & { __brand: T }; type USD = Brand<number, "USD">; type EUR = Brand<number, "EUR">; function formatUSD(amount: USD): string { return `$${amount}`; } const dollars = 100 as USD; const euros = 100 as EUR; formatUSD(dollars); // OK formatUSD(euros); // Type error!
The __brand property differentiates USD from EUR structurally, even though at runtime they’re both just numbers. This provides compile-time nominal distinction with zero runtime overhead.
Private Constructors
Classes with private constructors and factory methods can enforce nominal typing:
class UserId { private constructor(private readonly value: number) {} static create(value: number): UserId { return new UserId(value); } getValue(): number { return this.value; } } function getUser(id: UserId) { /*...*/ } getUser(UserId.create(123)); // OK getUser({ value: 123 }); // Error - not assignable
The private constructor prevents creating compatible objects outside the class, effectively making UserId nominal.
What We’ve Learned
TypeScript’s structural typing represents a fundamental design choice that shapes the entire language. Rather than checking type compatibility based on declared names and inheritance hierarchies like Java, TypeScript checks whether values have the required shape—the right properties with the right types.
This approach directly descends from JavaScript’s duck typing tradition. If it walks like a duck and quacks like a duck, TypeScript treats it as a duck, regardless of what it calls itself. This philosophical difference—structural vs nominal typing—reflects divergent views on identity and classification.
Java developers often struggle with structural typing because it violates nominal typing’s intent-based guarantees. Code that would be compilation errors in Java passes TypeScript’s type checker because structural compatibility ignores semantic intent. Empty interfaces accept anything, and types with identical structures become interchangeable even when semantically distinct.
However, structural typing is precisely why TypeScript succeeds at typing JavaScript. JavaScript’s pervasive use of object literals, ad-hoc objects, and dynamic patterns would be nearly impossible to type with nominal typing. Structural typing enables gradual adoption, seamless library compatibility, and type definitions that describe actual runtime behavior rather than impose artificial hierarchies.
The flexibility does introduce subtle bugs—accidental type compatibility, over-accepting functions, and the excess property inconsistency can allow errors that nominal typing would catch. When semantic distinction matters more than structural compatibility, branded types and private constructors can simulate nominal guarantees within TypeScript’s structural system.
Ultimately, neither structural nor nominal typing is inherently superior. They make different tradeoffs appropriate for different contexts. TypeScript’s structural typing perfectly fits its mission: adding compile-time type safety to JavaScript while preserving the language’s essential character and flexibility.
