Proposal: add explicit named API views

[leeo3264]

Full Proposal Document

The complete Exhibits proposal is available here:
https://gist.github.com/leeo3264/625f7cdc3629f7ff2f3cd91dc6b9bd6b

Proposal: Add explicit named API views to C#

Goal: Allow library authors to organize the public members of a class or namespace into named, workflow-oriented API views, improving discoverability without changing runtime behavior.

Justification: Mature framework types often expose dozens or hundreds of public members serving very different purposes. As frameworks grow, every intended usage scenario contributes additional public members. A developer configuring a service, diagnosing failures, or performing administration must navigate through the entire API to discover the members pertinent to the task. As this naturally divides the API into workflow-specific categories, this proposal simply provides a formal means for declaring this organization in the language.

The proposal applies to APIs a principle analogous to relational database views: different workflows present different projections of the same underlying API. This permits developers to work with domain-focused subsets of an API while leaving all runtime behavior unchanged. To assert safety, the following design invariant applies: any valid program using API views compiles to the same computation as if the API views were absent.

Motivation: Why a language feature? API organization already exists in practice. Today, API organization in C# is represented only indirectly through documentation, naming conventions, and tooling heuristics. These are useful, but all outside the language itself. The proposal introduces named API views as a first-class language declaration.

Are there other options? Existing tooling can infer API organization, but it is necessarily heuristic and tool-specific. The proposal allows API authors to declare that organization once, providing a single authoritative source for IDEs, analyzers, documentation generators, and source generators.

Employing attributes has the drawback of introducing metadata that becomes part of the compiled assembly. Interfaces likewise introduce semantic contracts, which the proposed API views intentionally avoid. API views are designed to have zero impact beyond semantic analysis.

Inheritance also provides a limited form of organization, but only by imposing a strict hierarchical structure. Inheritance organizes behavior through specialization rather than projection, making it unsuitable for grouping members by workflow.

Non-goals:

• Do not define contracts or introduce metadata
• Do not affect accessibility or participate in inheritance
• Do not influence overload resolution
• Do not affect binary compatibility or influence code generation

I'm particularly interested in feedback on two questions:

1. Is explicit API organization a problem worth solving in the language?
2. If so, is a compile-time-only API view an appropriate mechanism?

[CyrusNajmabadi]

This feels wrong. It's a way to organize apis into sensible chunks to be used. But we already have that today. That's what classes/interfaces/etc. are for. They exist so that you can properly create sensible apis. If you're not using those, then it's not for the language to try to paper over that for you.

[timcassell]

I feel like roles would fill this niche. They are strong type aliases, so under the hood they just are the original type at runtime (not an interface), and you can opt to expose only the APIs you want to per role.

[leeo3264]

I feel like roles would fill this niche. They are strong type aliases, so under the hood they just are the original type at runtime (not an interface), and you can opt to expose only the APIs you want to per role.

Is there an organized way to approach "roles" in existing C#, or is this a similar language proposal? My future motivation for the Exhibits system design was to establish an anchor for attaching formal verifications. I would hope that sections of C# code may then be certifiably compliant where required for high-criticality systems (Level A).

[timcassell]

It's a proposal that was unfortunately deprioritized.

[leeo3264]

It's a proposal that was unfortunately deprioritized.

Thank you -- However from what I was able to find out about "roles" -- it is done through declaring an alias to a type and thus has more downstream effect than what I propose here.

[leeo3264]

There are also other features that would make the proposal more flexible than what I presented here to answer your question.

Why not include that.

See the formal proposal, introduced today. Thank you for your interest.

[leeo3264]

Can you provide a simple code example of what you're proposing?

Very well, first I propose to introduce a term for a named API surface that a class or namespace supports. Considering the analogy of a museum curator selecting artifacts to put on display, I choose the name exhibit. Unlike museum pieces, however, the inclusion of exhibits does not restrict its employment, and an item may freely appear in any number of exhibits without restriction. In the formal proposal I give further rules to keep the employment of exhibits from propagating and complicating the codebase.

A few clarifications are in order: Exhibit names are introduced in the class signature and may also occupy the modifier position of a method of the class to signal its inclusion. In method declarations, exhibit names appear before the return type, in the same syntactic position as public. They behave like contextual modifiers, proxy for public accessibility, and the keyword public may be included or omitted without effect. Anywhere public is permitted as a modifier, a declared exhibit name may be substituted.

To restate the principle of non-interference: Exhibit markers do not participate in overload resolution, metadata or runtime behavior.

In the example, exhibit names appear as modifiers and the return type (void, bool, etc.) remains in its normal position. The example provides a feel of how exhibits may be declared inline with the class:

``public class DataStore
    out EAdministration,
    out EReadOnly,
    out EMutation
{
    // Administration operations
    EAdministration void Connect(string connectionString) { /* … */ }
    EAdministration void Disconnect() { /* … */ }

    // Read-only operations
    EReadOnly bool Exists(string key) { /* … */ }
    EReadOnly object? Read(string key) { /* … */ }

    // Mutation operations
    EMutation void Write(string key, object value) { /* … */ }
    EMutation  void Delete(string key) { /* … */ }

    // Mixed-surface operation (appears in multiple exhibits)
    EReadOnly EAdministration object? ReadWithAdmin(string key) { /* … */ }
}``

By way of a brief justification: The class signature includes the base class and any interfaces that may be implemented, and now also new exhibit names. To distinguish these from interfaces, I propose to prefix each new exhibit name with a contextual employment of the keyword out. It is contextual and syntactically disjoint from parameter and generic positions. This is consistent with the current employment of the keyword: in parameter signatures it means that "this flows outward from the method". In generics it means "this type parameter is only produced and never consumed". This aligns with exhibits, which represent outward-facing surfaces. It is produced by the type but not consumed by callers except to reveal names for employment scenarios.

[HaloFour]

I think this is where we simply fundamentally disagree: that conceptual mapping should be a part of the library API design. The code consuming that library should flow appropriately based on that intent. The idea of organizing it differently through some other means is simply foreign to me. And if the library author isn't putting the appropriate care into their API design I don't believe they would consider this alternate approach either.

Whatever this metadata would be would have to be attached to the actual API anyway, so XML documentation and custom attributes are still the existing appropriate mechanism.

It all comes down to this question:

"Why would you want/need to organize the API surface without actually organizing the API surface?"

[CyrusNajmabadi]

not structure the language or tooling can reason about.

Why not?

wrapper types whose sole purpose is “this subset of members belongs together”

Why is this a bad thing. If these subset of members belong together, then a wrapper type for taht is sensible. Even better, it means that everything (from the compiler to all downstream consumers) will agree on that. You won't be able to violate it either. Because it's now enforced throughout the system.

they don’t organize the API surface.

Why is that the case? Ultimately, they're as flexible as xml is. So if you want them to organize the api surface... why can't they do that?

types that exist not because the domain demands them,

Most of your examples (outside of partial types) seem like cases where the domain demanded them. For example, it's preferable and clearer to distinguish the thing that builds something, vs that thing itself. And it's preferable to do that in a way that isn't just adhoc, but truly enforced. a StringBuilder is not a string (and vice versa). Furthermore, it would be bad to have these together, with only a 'named view' being the way to hope that people don't violate the separation :)

[CyrusNajmabadi]

Perhaps it would be good to give an example of an existing .net BCL api where this would be good to have. Thanks!

[leeo3264]

The discussion is colliding with a category error. Exhibits are designed to address organizational intent. What I am hearing is the claim that all organization must be semantic and type enforced. To emphasize the mismatch: Structural intent (What I am forwarding): Emphasize conceptual grouping. Do this without adding contracts or runtime meaning -- just enable tooling visibility projections to improve developer workflow. Semantic constructs (What I am hearing) enforce behavior and shape API surfaces through additional types. All meaning must emerge into the runtime to be valid.

With enough curation, semantic constructs can indeed work -- but my claim is that they are really an unnecessary complication if the desire is simply to organize. C# currently provides only semantic encapsulation mechanisms, so structural intent has no formal expression. Introducing a structural mechanism necessarily expands the workflow model, but it does so without affecting existing semantics. Further, employing the feature is always opt-in; I am not proposing the removal of any existing C# feature.

Thus, the objections really do not apply here. What I am proposing is a structural segmentation model -- not the semantic segmentation already available. Currently API authors must reshape the API surface to also express conceptual grouping. This adds a requirement that (in my view) complicates the type system. The objection assumes the wrong category of solution.

Extended examples will inevitably be evaluated through the semantic lens (“should this be a type?”), because that is the only mechanism C# currently provides for expressing organization. That lens cannot validate a structural feature, so examples become misleading rather than clarifying. Indeed, producing one would not resolve the mismatch — it would simply reinforce the assumption that all grouping must be semantic. Exhibits provide a way to express conceptual organization without introducing semantic artifacts, and examples framed in semantic terms cannot demonstrate that.

Of course, semantic segmentation mechanisms are indeed adequate for semantic problems. However, the Exhibit proposal addresses a different class of problem. This is a similar structural gap that motivated LINQ: semantic tools were adequate, but they did not address the "impedance" mismatch that argued for the inclusion of LINQ expressions. Exhibits occupy a similar space. The adequacy of semantic tools does not resolve the structural gap Exhibits target.

[HaloFour]

What I am proposing is a structural segmentation model -- not the semantic segmentation already available.

Incorrect, what you are suggesting could be accomplished already today via custom attributes without any modifications to the type system. That would be metadata that could already be surfaced to tooling to "improve developer workflow."

Now, the onus is on you to demonstrate why custom attributes aren't sufficient here.

public class DataStore {
    // Administration operations
    [EAdministration] void Connect(string connectionString) { /* … */ }
    [EAdministration] void Disconnect() { /* … */ }

    // Read-only operations
    [EReadOnly] bool Exists(string key) { /* … */ }
    [EReadOnly] object? Read(string key) { /* … */ }

    // Mutation operations
    [EMutation] void Write(string key, object value) { /* … */ }
    [EMutation]  void Delete(string key) { /* … */ }

    // Mixed-surface operation (appears in multiple exhibits)
    [EReadOnly, EAdministration] object? ReadWithAdmin(string key) { /* … */ }
}

That presumes defining attribute types per effect, but if that's unpalatable to you you could just as easily define a custom attribute that accepts an identifier of some kind.

[leeo3264]

Exhibits introduce semantic partitions into the type system, enabling explicit API surfaces that attributes by design cannot express.

Custom attributes provide a flexible mechanism for attaching metadata to program elements, and they are well-suited for scenarios where descriptive information is sufficient. However, attributes do not introduce structural organization into the type system. Exhibits define named API surfaces that the compiler can recognize and tooling can reliably consume. This distinction is not one of capability but of purpose: attributes annotate members, whereas Exhibits partition the API into conceptual views that are part of the language’s semantic model.

From this foundation, the differences follow naturally:

1. Metadata vs. structure — Attributes attach descriptive metadata and are intentionally lightweight and semantically open-ended. Exhibits introduce structured organization: they define named API surfaces that the compiler can recognize, reason about, and project. Attributes annotate; exhibits organize.

2. Reflection layer vs. language layer — Attributes become part of the compiled assembly as metadata, consumed by reflection, and analyzers. Exhibits participate in the language’s semantic model and are visible during analysis, binding, and projection. This difference in layer naturally leads to differing affordances.

3. Description vs. declaration — Attributes describe properties of members. They do not define relationships between members or introduce conceptual partitions. Exhibits declare that certain members belong to a named conceptual surface, and that declaration becomes part of the program's structure.

4. Tagging vs. partitioning — Attributes support tagging members with arbitrary information. Exhibits introduce explicit partitions of the API into named views that are stable, structural, and available to the compiler and tooling without convention.

5. Unconstrained vs. semantically meaningful — Attributes impose no semantic obligations and are open-ended by design. Exhibits introduce constructs with defined semantics: a named surface with a clear relationship to the type's public projection.

None of this is a criticism of attributes; they serve their intended purpose well. Exhibits simply address a different design goal: providing explicit, compiler-recognized API surfaces that support structural organization, semantic partitioning, and in the future, layers of static reasoning.

[HaloFour]

Exhibits introduce semantic partitions into the type system, enabling explicit API surfaces that attributes by design cannot express.

How, exactly? Nothing about your proposal suggests anything remotely like this and I don't understand why you're being super cagey about how you imagine any of this working. All you've done is associate some identifiers with some methods. You can do that with custom attributes just fine.

[leeo3264]

Attributes give metadata; Exhibits define structure. Treating those as interchangeable is a category mismatch — they operate at different semantic layers. One annotates, the other partitions.

To answer the “How, exactly?” question:
Exhibits introduce semantic partitions by creating named API surfaces that the compiler recognizes. If MyClass has eight public methods, that’s the standard C# surface. But if MyClass also declares exhibits like EIni, EArchive, and EDiagnose, each exhibit defines its own structural view:

EIni → methods 1, 3, 5
EArchive → methods 1, 4, 5, 6
EDiagnose → methods 1, 7, 8

Now, in another namespace, using the initialization surface is explicit:

MyClass.EIni.Method1
MyClass.EIni.Method3
MyClass.EIni.Method5

And if you attempt something outside that surface — say MyClass.EIni.Method2 — the compiler reports:

MyClass.Method2 is not a member of MyClass.EIni.

That’s the semantic partition:
Exhibits define compiler‑recognized API surfaces; attributes do not.

[HaloFour]

Build your developer tooling around attributes, come back with something concrete that actually demonstrates value, and then propose something. Otherwise there's no reason to continue this discussion. It's simply not actionable.

[sator-imaging]

leeo3264
You should "exhibit" all of your thought with better "structure" instead of wall of text.

[leeo3264]

leeo3264 You should "exhibit" all of your thought with better "structure" instead of wall of text.

Ok, HaloFour and sator-imaging, please reread the reply -- your comments appeared while I was in mid-edit.

[CyrusNajmabadi]

Exhibits define compiler‑recognized API surfaces;

But the compiler doesn't recognize them. Because they are erased.

attributes do not.

But they do. You can add attributes to all members saying what "exhibit" they belong to. And now the entire .net stack can read and understand them, using the tooling that has existed since 1.0.

Again, I need actual examples of what this enables. So far everything you've mentioned is doable with attributes