Proposal: Tags

[Richiban]

Proposal: Tags

Summary

This proposal introduces tags as a new primitive concept in C#. Tags are symbolic, strongly typed, lightweight values that act as both a type and a value. Inspired primarily by Roc’s tag system and influenced by atoms in Erlang, symbols in Ruby/JavaScript, and discriminated unions in F#/Rust, this feature enhances domain modeling and interplays naturally with the existing nominal type unions proposal.

Tags offer an ergonomic and type-safe alternative for representing sentinel values, results, events, symbolic messages, or lightweight enums—with or without payloads.

Motivation

C# developers often need to express simple symbolic variants—especially as return values, messages, or status codes. Today, options include:

• Magic strings or enum constants (not extensible or typed)
• Dedicated record types (verbose)
• Discriminated unions with predeclared case types (boilerplate-heavy)
• Custom wrappers like Result<T, E> or OneOf<T1, T2> (limited native support)

Tags fill the gap by offering:

• Lightweight, inline declaration
• Optional payloads
• Pattern matching support
• Compatibility with the proposed union construct

Syntax (Strawman)

Creating a tag

var x = $MyTag;

This declares a value x of type $MyTag, which is a tag with no payload.

Explicit typing

$MyTag x = $MyTag;

Tags are first-class types as well as values. They are nominal, not stringly typed.

With payload

var y = $SomeTag("some data");

$SomeTag(string) y = $SomeTag("some data");

Tuple payloads are allowed:

var p = $Point((3, 4));

In unions

Tags integrate seamlessly into nominal type unions:

union Result<T>($Ok(T), $Err(string));

Return types can mix tags and named records:

public union(Customer, $CustomerNotFound) GetCustomer(string id) => ...;

Use Cases

Results and Options:

union Result<T>($Ok(T), $Err(string));

Result<int> ParseInt(string s)
{
    if (int.TryParse(s, out var value)) return $Ok(value);

    return $Err("Invalid number");
}

Status indicators / sentinel values:

return $NotReady;

Inline union-like domain models:

union Shape($Circle(double radius), $Rectangle(double width, double height));

Events / messages:

ProcessMessage($UserSignedIn("alice"));

Implementation

Tags would be implemented as a small struct with a tag ID and optional data:

namespace System;

public readonly struct Tag(int id, object? data)
{
    public int Id { get; } = id;
    public object? Data { get; } = data;
}

Global Tag Table

To avoid having to carry around a string per instance for the tag name, tag IDs are registered globally per AppDomain. For example:

$MyTag == new Tag(GlobalTagRegistry.GetId("MyTag"));

The registry ensures:

• Fast identity comparison (Id)
• No duplication of string names
• Optional debugging metadata for name lookup

This mirrors Erlang atoms, JavaScript symbols, or interned strings in .NET.

Compiler & Pattern Matching

The compiler knows how to:

• Generate tag types as distinct nominal types (e.g., $MyTag)
• Support pattern matching via switch expressions:

result switch
{
    $Ok(var val) => $"Got {val}",
    $Err(var msg) => $"Error: {msg}"
};

Exhaustiveness checking can be performed when tags are used inside unions.

Advantages

• Minimal ceremony for symbolic variants
• Better performance and safety than magic strings
• Works natively with unions and pattern matching
• First-class citizen—tags are values and types
• No need for declarations or boilerplate

Summary

Tags give C# a small but powerful feature that unlocks expressive, safe modeling for symbolic data. They pair naturally with unions and pattern matching and align C# more closely with the expressive power found in modern functional-first languages—while remaining intuitive and idiomatic for C# developers.

They also mean that the standard library does not need standard Option/Result types, as unions can be ad-hoc and can therefore have cases that perfectly fit the domain in which they're being used. For example:

union UIState($Idle, $Loading, $Loaded(UIData), $Error(string));

...

    protected override async Task OnParametersSetAsync()
    {
	_state = $Loading;

	try 
	{
	        var data = await DataQuery.GetAsync(dataId);
		_state = $Loaded(data);
	} catch (SomeDataException e)
	{
		_state = $Error(e.Message);
	}
    }

[HaloFour]

Optional payloads

What controls this? Does the tag itself dictate that it can have a payload, or can any tag have a payload? $None("something")?

Lightweight, inline declaration

I see what this is going for, but I have concerns about this inline declaration syntax, especially since they are not strongly typed. If any/every $Foo is $Foo regardless of where it is declared it feels like it's too easy to have a collision. IMO, a one-liner struct record declaration to actually declare a nominal type doesn't feel onerous and feels much more inline with the typing philosophies of C#. Plus, that allows the type to be explicit about the data that it supports, and can be extended to support additional type functionality, whereas tags cannot.

Compatibility with the proposed union construct

I'm not sure it would be compatible with that construct, given that they are based on the actual type, which in this case would always be Tag. The compiler would need to understand how to unpack two levels of discriminators.

Tags would be implemented as a small struct with a tag ID and optional data

IMO would be better to have Tag and Tag<T>, the latter used for scenarios with optional data so that the data doesn't have to be boxed, in the case of value type data.

To avoid having to carry around a string per instance for the tag name, tag IDs are registered globally per AppDomain.

Is it necessary to use a separate mechanism here rather than relying on string interning?

[Richiban]

What controls this? Does the tag itself dictate that it can have a payload, or can any tag have a payload? $None("something")?

Any tag can have a payload. Although it may seem nonsensical to have $None("something") when we're used to FP-style options, there's nothing actually wrong with it. The tag would (from a program behaviour perspective) be no different from declaring a record

public record None(string Value);

At least with the tags there's no need to declare "sentinel" records just to use them in a union (i.e. a record with no data; it's really just the name). Currently one must define the record but, even though it carries no data, it's still an instance type, and this feel weird:

public record None();

var x = new None();
var y = new None();

Object.ReferenceEquals(x, y); // false

If any/every $Foo is $Foo regardless of where it is declared it feels like it's too easy to have a collision. IMO, a one-liner struct record declaration to actually declare a nominal type doesn't feel onerous and feels much more inline with the typing philosophies of C#

I realise I may be slightly at odds with the typing philosophies of C#, as you say, but to me it's a fairly important feature that tags have no declaration and are therefore not nominal. It is at the usage site that the developers declares whether or not a particular tag will carry a payload or what combination of tags is considered valid. Having written a lot of Typescript in which string-literal types are heavily used, I have never actually seen collisions become a problem.

IMO would be better to have Tag and Tag, the latter used for scenarios with optional data so that the data doesn't have to be boxed, in the case of value type data.

Fair; I don't think that would be breaking to the proposal.

Is it necessary to use a separate mechanism here rather than relying on string interning?

Not at all! I just don't know enough about string interning to be able to offer input here; I took the mechanisms I do know wholesale. If interning works then that would be fine!

[Richiban]

I'm not sure it would be compatible with that construct, given that they are based on the actual type, which in this case would always be Tag. The compiler would need to understand how to unpack two levels of discriminators.

This is probably where the unions proposal differs from Roc enough to be worth mentioning: in Roc unions can only be of tags. So

union($A, $B); // Valid

union($A, string); // Invalid

This restriction might be worth considering because (I believe) it would allow for unifying the implementations of Tag and Union structs into the same concept.