microsoft / microsoft/typespec

Need a design for how client customizations will look in 3p specs

Open
#4,197 0 comments 0 reactions 2 assignees Claimed by @m-nash View on GitHub
design:needed triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Clear and concise description of the problem

Right now we have a bunch of decorators and functionality that allow you to customize the shape of the client output for a given language emitter for Azure. One of the challenges is often we are opinionated in that library since we enforce Azure standards.

We need to design how this same functionality could work in 3p specs as well as integrate with other 3p emitters that are written outside of Microsoft.

We can start with 3 fairly straight forward decorators that we know at least one 3p spec is using today.

- [@clientName](https://github.com/Azure/typespec-azure/blob/main/packages/typespec-client-generator-core/lib/decorators.tsp#L5-L25) - allows you to override the name of an element in the emitted library.
- [@usage](https://github.com/Azure/typespec-azure/blob/main/packages/typespec-client-generator-core/lib/decorators.tsp#L165-L251) - allows you to override the usage of a model in the emitted library which can affect the shape of the model.
- [@access](https://github.com/Azure/typespec-azure/blob/main/packages/typespec-client-generator-core/lib/decorators.tsp#L253-L413) - allows you to override whether something is part of the public api surface of the emitted library.

One thing we rely on today is the notion of `scope` which is a parameter for all three of these decorators. It allows you to work easily in multi-emit scenarios where you are emitting multiple languages at once.

For instance if I have the following model in my tsp

```tsp
namespace Bar;

model FooRequest {
name: string;
count: int;
}
```

Lets say you are emitting Java and Dotnet and lets say Dotnet doesn't want the `Request` suffix on the model type as it can be confusing with an HttpRequest. However Java is just fine with the original name and wants to keep it as is. Scope combined with @clientName will let you specify exactly this.

```tsp
@@clientName(Bar.FooRequest, "FooContent", "csharp");
```

The are 4 main scenarios we currently cover with scope

- apply to a single emitter : "csharp"
- apply to a set of emitters : "java,csharp"
- apply to all except a single emitter: "~csharp"
- apply to all except a set of emitters: "~java,csharp"

### Checklist

- [X] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [X] Read the [docs](https://typespec.io/docs/).
- [X] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.