Proposal: Lightweight nominal primitive types (newtype) for stronger ID safety

[JavadSayedi]

Lightweight Nominal Primitive Types (NewType) for C#

Champion

Seyed Javad Seyedi

Summary

This proposal introduces a lightweight nominal type feature for
primitive types in C#.

The goal is to allow developers to define distinct, compile-time
enforced identifier types that:

• Preserve underlying runtime representation
• Introduce zero allocation overhead
• Maintain full performance equivalence with primitive types
• Improve domain modeling and type safety
• Prevent common identifier misuse bugs

Proposed syntax:

public newtype OrderId = int;
public newtype OrderItemId = int;
public newtype CustomerId = Guid;

---

Motivation

Real-World Bug Pattern

In large enterprise systems, especially those following Domain-Driven
Design (DDD), identifier confusion is a recurring issue.

Example:

public class Order
{
    public int Id { get; set; }
}

public class OrderItem
{
    public int Id { get; set; }
    public int OrderId { get; set; }
}

Bug example:

orderItem.OrderId = orderItem.Id; // Compiles but logically incorrect

This category of bug:

• Is not caught by the compiler
• Frequently appears in large codebases
• Is difficult to detect during code review
• May lead to data corruption or subtle production defects

After decades of enterprise development experience and extensive code
reviews, this pattern remains common.

---

Current Workarounds and Their Limitations

record struct Wrapper Pattern

public readonly record struct OrderId(int Value);

Problems:

• Boilerplate
• Increased cognitive overhead
• Conversion friction
• EF Core configuration complexity
• Serialization configuration
• Resistance from development teams due to verbosity

Third-Party Libraries

Strongly-typed ID libraries exist but:

• Require configuration
• Add abstraction overhead
• Complicate EF Core integration
• Are not universally adopted
• Lack compiler-level enforcement semantics

---

Design Goals

1. Zero runtime overhead
2. Zero additional memory allocation
3. Identical IL representation to underlying primitive
4. Nominal typing (not structural)
5. Compile-time enforcement of type distinction
6. Seamless compatibility with:
   • Generics
   • EF Core
   • JSON serializers
   • Pattern matching
   • Switch expressions
   • Interop

---

Proposed Syntax

public newtype OrderId = int;
public newtype OrderItemId = int;
public newtype CustomerId = Guid;

---

Semantics

• OrderId is a distinct nominal type.
• Underlying runtime representation is identical to int.
• No wrapper object.
• No heap allocation.
• No boxing.
• No implicit assignment between different newtypes.

Example:

OrderId orderId = 5;
OrderItemId itemId = orderId; // Compile-time error

Explicit conversion (subject to design discussion):

int raw = orderId;
OrderId id = (OrderId)raw;

---

Runtime Representation

Preferred approach:

Pure compile-time aliasing.
The compiler enforces nominal type distinctions but emits the underlying
primitive type in IL.

Advantages:

• Zero runtime change
• Maximum backward compatibility
• No CLR modification required

---

Example Usage in DDD

public newtype OrderId = int;
public newtype OrderItemId = int;

public class Order
{
    public OrderId Id { get; set; }
}

public class OrderItem
{
    public OrderItemId Id { get; set; }
    public OrderId OrderId { get; set; }
}

Invalid assignment:

orderItem.OrderId = orderItem.Id; // Compile-time error

---

Generics Interaction

newtype behaves like its underlying primitive for generic constraints.

If the underlying type satisfies constraints such as unmanaged or
notnull, the newtype automatically satisfies them as well.

No new generic constraint syntax is introduced in this proposal.

This keeps the feature minimal and avoids unnecessary complexity in the
type system.

---

Serialization Behavior

Default behavior:

• Treated as underlying primitive by serializers
• No custom converters required

---

EF Core Compatibility

• Mapped automatically as underlying primitive
• No ValueConverter required
• No additional configuration required
• Full compatibility with existing database schemas

This is critical for enterprise adoption.

---

Performance Requirements

Must guarantee:

• No boxing
• No allocation
• No performance regression compared to primitive types
• JIT optimizations unaffected

---

Backward Compatibility

• Purely additive feature
• No breaking changes
• No impact on existing enum or struct behavior
• No CLR breaking change required

---

Non-Goals

• Does not introduce primitive inheritance
• Does not alter enum semantics
• Does not introduce union types
• Does not introduce validation constraints in MVP

---

Conclusion

This proposal addresses:

• A common enterprise bug pattern
• Domain modeling limitations
• Type-safety gaps in large systems
• Boilerplate-heavy workarounds

It enables safer domain modeling without sacrificing performance or
simplicity.

[HaloFour]

See: #410

[JavadSayedi]

Thanks for pointing to #410 — I reviewed that discussion.

My understanding is that the earlier proposal focused more broadly on type aliasing and even validation scenarios.

The intent of this proposal is narrower and performance-focused:
a minimal nominal distinction for primitive types (primarily identifiers) with zero runtime overhead and no additional validation semantics.

The goal is specifically to address accidental cross-assignment of domain identifiers (e.g., OrderId vs OrderItemId) while keeping the surface area small and avoiding type-system complexity.

If the concern in #410 was scope or complexity, I would be interested in understanding whether a strictly minimal, compile-time-only approach would be more aligned with current design goals.

[HaloFour]

Also see: #5496, specifically roles.

[JavadSayedi]

Thanks for pointing to #5496 and the roles discussion.

I reviewed that thread as well. It seems that the focus in that space is on roles and contextual typing rather than strict compile-time nominal distinction for primitive identifiers.

My proposal here is specifically about introducing lightweight nominal primitive types for identifiers (e.g., OrderId vs OrderItemId) that:

• have zero runtime overhead,
• preserve underlying IL representation,
• provide strict compile-time differentiation,
• and avoid any extra validation or behavioral semantics.

The intent is narrower and more performance-oriented than either full-blown type aliasing with validation or role-based contextual typing.

If there's interest in exploring this as a minimal, compile-time-only feature with a small surface area, I’d be happy to refine it further based on feedback.

Thanks!

[CyrusNajmabadi]

My proposal here is specifically about introducing lightweight nominal primitive types for identifiers (e.g., OrderId vs OrderItemId) that:

have zero runtime overhead,

Roles have zero runtime overhead.

preserve underlying IL representation,

I don't understand how you want to achieve this. You mentioned explicitly that you want 'Nominal typing'. If there is nominal typing, then the underlying representation must change because you have a different nominal type.

These two goals are at odds with eachother. Furthermore, I don't see why 'underlying il representation' even matters. IL is just an impl detail. Nothing about the language states what it is. Your proposal does not even indicate how you would accomplish that at a compiler level.

provide strict compile-time differentiation,

Roles provide this.

and avoid any extra validation or behavioral semantics.

Roles provide this. Anything extra is simply something you opted for yourself.

The intent is narrower and more performance-oriented

What makes this more performance oriented than roles? Roles are already zero overhead.

than either full-blown type aliasing with validation or role-based contextual typing.

What do you think 'role based contextual typing' actually is?

[HaloFour]

Those are the same goals as "roles". The discussion had morphed quite a bit but where "extensions" would be implicitly in scope, "roles" are a strong type alias offering type safety that would be elided at compile time so they would have zero overhead. You would not be able to assign the underlying type to the role without an explicit cast where presumably you would be able to enforce some kind of validation where need be, and potentially also pattern matching as a kind of active pattern. But they would be more than just an alias in that they can offer their own members as well. It's hard to say what the syntax would look like since they were split from extensions and the latter was implemented in the language, but I assume something somewhat similar to Dart extension types.

[CyrusNajmabadi]

This looks identical to an 'explicit role'. Where you would be blocked from conversions unless writing an explicit cast.

[CyrusNajmabadi]

Resistance from development teams due to verbosity

Why is tehre resistance to one, but not resistance to your approach? Both are just named entities that wrap around an underlying type. Why is the role version public explicit extension OrderId for int unacceptable, but public newtype OrderId = int; is? They're practically the same. Except one states rules about needing explicit (vs implicit) conversions from underlying type to the role type, while the other does not. Why is = going to make the difference over for? Why is newtype better than extension? etc. etc.

Pure compile-time aliasing.

If this is only at compile time, then the final metadata representation won't include this, which means anyone consuming this will see this as the underlying type.

If you want this to be visible to the consumers, there has to be something in metadata/il indicating that it's this new thing, with new semantics, so that you don't violate this immediately. This has to bake-through to the end code, or else this is just going to be useful within a compilation unit, and not a full program/ecosystem.

[JavadSayedi]

Thank you — these are important points.

Regarding the similarity to explicit roles: I agree that semantically they are very close. My intent is not to introduce fundamentally new semantics beyond nominal distinction with controlled conversions.

The motivation here is largely about ergonomics and adoption. In practice, strongly-typed ID patterns often face resistance due to verbosity and perceived friction. A declaration form that communicates "this is a distinct identity type backed by a primitive" in a minimal and declarative way may improve adoption compared to extension/role-based syntax, even if the underlying semantics are similar.

That said, if explicit roles already fully satisfy the nominal distinction + zero-overhead requirement, then it would be useful to understand whether roles are intended to cover this use case directly.

Regarding compile-time-only aliasing: you're absolutely right that if the distinction does not survive into metadata, it cannot provide cross-assembly safety. My original wording may have been imprecise.

The real requirement is zero runtime cost, not necessarily absence of metadata identity. If preserving nominal identity across assembly boundaries requires distinct metadata representation, that would be acceptable as long as layout and performance characteristics remain equivalent to the underlying primitive.

So the core requirement is:

• nominal distinction visible across assemblies,
• no additional allocation,
• no performance regression.

I'm open to clarification on whether roles are the intended long-term solution for this scenario, or whether a more specialized construct for primitive-backed identity types would be considered.

[HaloFour]

"Roles" are the name given the project intended to achieve those goals, a strong nominally typed wrapper around any existing type that persists in metadata across assembly boundaries but has zero runtime overhead.

[JavadSayedi]

Thank you for the clarification — that helps a lot.

If roles are intended to provide a nominal, metadata-preserving, zero-overhead wrapper, then that aligns closely with the problem I’m trying to address.

The specific scenario I care about is strongly-typed IDs in domain-driven systems, for example:

OrderId
CustomerId
ProductId

all backed by int or Guid, but intentionally non-interchangeable.

In large codebases this pattern dramatically reduces accidental mix-ups, but today it requires either record structs (with overhead and boilerplate) or source generators.

If roles are the intended direction, I’d be very interested in understanding:

• Whether primitive-backed identity types are considered a primary scenario
• What the expected declaration syntax might look like
• Whether implicit vs explicit conversion rules are still open for discussion

My goal isn’t to introduce competing syntax, but to ensure this extremely common use case is handled cleanly and ergonomically in the final design.

[JavadSayedi]

For example, would something like this be expected?

public role OrderId : int;

[HaloFour]

Yes, something like that. You would then need to explicitly cast an int to an OrderId:

int i = 123;
OrderId o1 = i; // compiler error
OrderId o2 = (OrderId) i; // fine

Presumably you could layer in some kind of validation as well, maybe through declaring an explicit conversion operator

int i = -1;
OrderId o = (OrderId) i; // runtime error

Even better if it supports a kind of active pattern:

int i = -1;
if (i is OrderId o) {
    // can use validated OrderId here
}

[sator-imaging]

You can use enum for type aliases for integer values that is type-safe, lightweight than record and less-reliable.

public enum OrderId : ulong { }
public enum CustomerId : ulong { }

Console.WriteLine(((OrderId)0) == ((CustomerId)0));  // Error

[CyrusNajmabadi]

The current syntax is more like : public explicit extension OrderId for int;

The reasons for the difference:

1. explicit/implicit allows you to say if there should be implicit or explicit conversions between the types, then either requiring or making optional the need for casts in code.

2. for is used instead of : as we still want the : to introduce an inheritance list. We believe extensions could make it so this nominal type freely can implement more interfaces than the original type. The syntax allows distinguishing "this is the type being extended" vs "this type is being extended here to support this new interface"

As a trivial example, if you want a zero cost wrapper around an interface you need a way to specify that.

[JavadSayedi]

@sator-imaging

That’s an interesting workaround, and it does provide compile-time separation between the types.

However, enums are semantically intended to represent a closed set of named values, not identity wrappers over primitives. Using an empty enum purely as a type-safe alias feels like a repurposing of the construct rather than an intended design use.

Some practical concerns with this approach:

• It suggests a finite value domain, which isn’t accurate for identifiers.
• Conversions become awkward and require explicit casts.
• Tooling, serialization, and ORM integration may treat enums differently than plain primitives.
• The intent (“this is a distinct identity type”) isn’t clearly communicated — it reads as a value domain rather than a nominal wrapper.

So while it’s technically possible, it feels more like a workaround than a first-class modeling construct.

The core question is whether strongly-typed primitive-backed identities are common enough to deserve direct language support, rather than relying on patterns that repurpose existing features.

[TahirAhmadov]

Specifically for this:

public class OrderItem
{
    public int Id { get; set; }
    public int OrderId { get; set; }
}

The better pattern is:

public class OrderItem
{
    public int Id { get; set; }
    public Order Order { get; set; }
}

Then ORM maps that as a many-to-one, gives you options to hydrate, etc.
When you need to pass an "entity id" as a method parameter, etc., (not a many-to-one property of another entity) you can use something like:

public readonly struct EntityRef<TEntity> where TEntity : EntityBase
{
  public EntityRef(int id) { this.Id = id; }
  public EntityRef(TEntity entity) { this.Id = entity.Id; }

  public int Id { get; }

  // equality, ToString, etc. boilerplate
}

// elsewhere
void DeleteOrder(EntityRef<Order> orderRef) { ... }

[TahirAhmadov]

Even if you don't want to have properties like public Order Order { get; set; }, you can use something like public EntityRef<Order> Order { get; set; } and write a trivial ORM "adapter" (or whatever it's called in EF etc.).

[JavadSayedi]

Those are good patterns, and I agree they work well in many ORM-centric designs.

However, the scenario I’m targeting is slightly different.

Navigation properties (e.g., Order Order) are great when modeling relationships inside an aggregate or when relying heavily on ORM features. But in many real-world systems — especially in CQRS-style architectures, projections, APIs, messaging, or service boundaries — IDs frequently exist as standalone value representations.

For example:

• DTOs
• Integration events
• Command objects
• Cross-service contracts

In those cases, we often want:

• A lightweight value that represents identity
• Zero allocation
• No ORM dependency
• Strong compile-time distinction between, say, OrderId and CustomerId

Generic wrappers like EntityRef<TEntity> can model this, but they introduce:

• Generic verbosity in public APIs
• Slightly more complex signatures
• Additional boilerplate (equality, converters, serialization handling, etc.)

The core motivation here isn’t that the problem is unsolvable today — it clearly is — but that this pattern is common enough that a first-class, low-friction language construct could significantly improve ergonomics while preserving performance.

If roles are meant to cover that cleanly, then that would be a very compelling direction.