Update base TypeSpec to generate clients in their corresponding nested namespaces

[ShivangiReja]

Currently, there is only one namespace, namespace OpenAI;, in the base TypeSpec. We need to be able to generate clients in their corresponding nested namespaces (e.g., ChatClient → OpenAI.Chat, OpenAIResponseClient → OpenAI.Responses, and any new feature → OpenAI.<Feature>).

My understanding is that TypeSpec has a feature that could help with this: 🔗 https://typespec.io/docs/language-basics/namespaces/

The solution might be to write our base TypeSpec files (models.tsp, operations.tsp..etc) in a way that leverages this feature so that each sub-client goes into its own namespace.

By doing this,

• We don’t have to write custom code for each type, just to update the namespace.
• This will also enable us to apply decorators at the namespace level in client.tsp. Currently, we can’t scope a decorator to a specific subclient(like Response or Chat) via namespace, so the only option is annotating each target model individually.

[baywet]

Update from internal discussion with @glecaros: this might not be desirable in the source specification as it might impact component names and other things. Also service consumers probably won't want to have multiple imports. Maybe this would be better addressed through a plugin instead.

[jsquire]

@baywet: I'd prefer that we discuss before that decision is made. There's a non-trivial impact here that I would like to be sure that we're accounting for as well as understanding your scenario better.

//cc: @achandmsft, @trrwilson

[baywet]

@jsquire would you mind please describing some of those impacts here for everyone's context?

[ShivangiReja]

@baywet A plugin/visitor can customize emitted C# namespaces, but it doesn’t address issues caused by having a single OpenAI namespace in the spec. TypeSpec (and our C# codegen) support namespace-level decorators, but with only one namespace we can’t use them without applying the policy globally. That means we can’t scope a decorator to just Chat or just Responses, , any namespace-level decorator becomes global, so we’re forced into noisy, error-prone per-type annotations. Modeling sub-clients as nested namespaces in the TypeSpec (e.g., OpenAI.Chat, OpenAI.Responses) lets us apply policy once at the right boundary and keeps the spec and generated code aligned.

[jsquire]

@baywet: To expand a bit on what Shivangi is describing - OpenAI is generally organized by feature (chat, responses, files, etc.) This is reflected in their documentation, samples, product announcements, and similar where the features are often treated as independent and distinct offerings more so than just a component of the larger service. The OpenAI client structure mirrors this; feature areas in the client library are distinct. They have a dedicated client, they have unique models and helper types, they're organize into a feature-focused namespace - and they evolve as a single unit. For example:

• We want to promote Chat to stable from experimental
• We want to enable the new pagable support on Responses for public testing
• We want to enable JSON Patch (aka "additional properties") on several areas to unblock Foundry scenarios

The namespace support being discussed here allows the TypeSpec structure to reflect that of the service, and to allow targeting feature areas by their namespace in decorators and other TypeSpec customizations used for code generation. Not having this available results in having to identify each and every type for a feature - by spec name - and apply customization either code.

While we can do this - it's a poor approach that opens the door to mistakes. As we start looking at promoting features to stable, this introduces additional risk due to the strong back-compat guarantees associated with the "no breaking changes" philosophy.

Update from internal discussion with @glecaros: this might not be desirable in the source specification as it might impact component names and other things. Also service consumers probably won't want to have multiple imports. Maybe this would be better addressed through a plugin instead.

The intent is for it to impact component names - and align them with their service representation and associated documentation. If you look through issues here and in the other OpenAI client library repositories, developers are generally focused on one core feature area and sometimes a second that supports it. There aren't many examples of "I'm using all of the service and..." In fact, there's enough overlap between areas such as Chat and Responses that it wouldn't be a mainstream scenario to use them together.

I'd like to understand the data that the statement probably won't want to have multiple imports is based on, as that contradicts the support patterns.

[baywet]

Thank you for the additional information.

probably won't want to have multiple imports

This is an assumption I'm making from past experiences but I have no hard evidence in the current context. The idea is those typespeec definitions will be consumed by SDK producers like yourself, but also by service teams at Microsoft to layer additional definitions on top of. My "hunch" is that we might get some push back from that second audience if they need multiple imports for the OpenAI API surface in their definitions, but it might not be a problem at all, or a smaller on than I think. So at this stage, take this as "an additional consideration to take" rather than a hard push back.

As for the other languages (SDKs), what do they do at this stage? do they also have a segmentation by "feature sets" in the imports etc...? We probably don't want the dotnet SDK to be the oddball out here.

[jsquire]

As for the other languages (SDKs), what do they do at this stage? do they also have a segmentation by "feature sets" in the imports etc...? We probably don't want the dotnet SDK to be the oddball out here.

Every language has segmentation by feature set, just as the REST API is. The representation of that varies based on what is idiomatic to a given language ecosystem. It's important to remember that the goal for client libraries is to be consistent within the language and not with each other. Java should look and feel like Java, Python like Python and so on.

For a cross section, the general pattern in strongly typed languages is namespace segmentation. For example:

• Java
• .NET
• Rust

The general pattern in dynamic languages is sub-clients. For example:

• Python
• JavaScript
• Ruby

The important consideration for this discussion is that we should not equate "how the spec is organized" with "what the structure of clients are when generated." Those are two distinct things. Client generators are responsible for applying language idioms to the output. There's nothing that prevents the generator from using TypeSpec namespaces as sub-clients - in fact, this is exactly what the TS generator for Python does today.

What we're asking for is that the spec be organized such that it reflects the organization of the service. This does not control how the client libraries are structured.

[baywet]

Thank you for the additional information. This helps set the stage a lot better!

Our current export, which is as you probably know work in progress, is segmented by feature set from a file structure perspective.
https://github.com/microsoft/openai-openapi-pr/tree/main/packages/openai-typespec/src, but everything is under a single namespace for the time being.
As a first sanity check, could you please go there and let us know whether this "feature set segmentation" is roughly the same you are expecting on your side? (i.e. are we both thinking about the same groups)

Then, you've mentioned that it's up to each client SDK to decide how things are going to be generated/organized. Assuming you already have the "grouping information" due to the file structure, how would a re-emitter that introduces a different namespace based on those groups work for you? (in that scenario, only the dotnet SDK would use it, we'd still produce definitions under a global namespace)

[jsquire]

Apologies for the delay. This may be bit behind now after discussions on hand-offs and format this week. We've got some time blocked next week to explore the most recent package drop and try to assess the impact and validate against the current form.

how would a re-emitter that introduces a different namespace based on those groups work for you?

So long as we're able to consume an official package drop with the namespace-based organization, then we've got no objections to having both a namespace and non-namespace version. As we talked over earlier this week, the key asks from us for hands-offs are:

• A published drop so that we've got a stable hand-off point (rather than assuming main is safe)
• A change list in the drop so that we're not relying on diffs to understand the intended change scope.
• Namespace organization by feature area (so that we can apply decorators and customizations to an entire feature rather than type-by-type)