Renaming

This page documents how to customize the name of models, operations, and parameters. For an overview of the setup, please visit the setup page.

Note

The TypeSpec compiler provides an @encodedName decorator that allows changing the name of the property for a given serialization format. However in Azure we recommend that you define the property name as the value sent on the wire and use the @clientName decorator to change the name of the generated property.

Default behaviors

By default, any language code generator will assume the TYPESPEC name is the client. For clarity, generators do not attempt to do any auto-magic rename.

NOTE: While names are not transformed, they will be adapted to what is idiomatic of the language (Python snake_case, etc.).

main.tsp

namespace PetStoreNamespace;

/** This is the input I need */
@resource("input")
model InputModel {
  /** Id of this object */
  @key
  @visibility("read")
  name: string;
}

/** Read my resource */
op get is ResourceRead<InputModel>;

Python

class InputModel:
  name: str = rest_field(readonly=True)

response: InputModel = client.get_model(name="name")

CSharp

namespace PetStoreNamespace.Models
{
  public partial class InputModel
  {
    public string Name { get; }
  }
}

namespace PetStoreNamespace
{
  public partial class PetStoreNamespaceClient
  {
    // protocol method
    public virtual async Task<Response> GetAsync(string name, RequestContext context) {}
    public virtual Response Get(string name, RequestContext context) {}
    // convenience method
    public virtual async Task<Response<InputModel>> GetAsync(string name, CancellationToken cancellationToken = default) {}
    public virtual Response<InputModel> Get(string name, CancellationToken cancellationToken = default) {}
  }
}

TypeScript

interface InputModel {
  name: string;
}

const model: InputModel = await client.path("/petStore/model/{name}").get();

Java

package petstorenamespace.models;
public final class InputModel {
    public String getName()
}

package petstorenamespace;
public final class PetStoreNamespaceClient {
    public Response<BinaryData> getWithResponse(String name, RequestOptions requestOptions)
    public InputModel get(String name)
}

Customizations

Renaming models and attributes

You can rename models and attributes. Renames have a target:

• client means that all client will use that name
• csharp, javascript, python, java means you target this specific language

Language target takes priority over client target.

NOTE: As model name do not get serialized as JSON, sometimes the best choice is to rename the main TYPESPEC for clarity. Talk to your emitter contact is you’re unsure if you should rename the model in the main TYPESPEC or customize it.

client.tsp

import "./main.tsp";
import "@azure-tools/typespec-client-generator-core";

using Azure.ClientGenerator.Core;

@@clientName(InputModel, "InputOptions"); // Use InputOptions as a base name in clients
@@clientName(InputModel, "ParameterOptions", "csharp"); // Prefer a different name for C# only

@@clientName(InputModel.name, "input_name", "python"); // Python may need a different to be idiomatic

Python

class InputOptions:
  input_name: str = rest_field(rest_name="name", readonly=True)

response: InputOptions = client.get_computed_model(input_name="name")

CSharp

namespace PetStoreNamespace.Models
{
  public partial class ParameterOptions
  {
    public string Name { get; }
  }
}

namespace PetStoreNamespace
{
  public partial class PetStoreNamespaceClient
  {
    // protocol method
    public virtual async Task<Response> GetAsync(string name, RequestContext context) {}
    public virtual Response Get(string name, RequestContext context) {}
    // convenience method
    public virtual async Task<Response<ParameterOptions>> GetAsync(string name, CancellationToken cancellationToken = default) {}
    public virtual Response<ParameterOptions> Get(string name, CancellationToken cancellationToken = default) {}
  }
}

TypeScript

// Typescript do not change behavior based on protocolAPI or convenientAPI

Java

package petstorenamespace.models;
public final class InputOptions {
    public String getName()
}

package petstorenamespace;
public final class PetStoreNamespaceClient {
    public Response<BinaryData> getWithResponse(String name, RequestOptions requestOptions)
    public InputOptions get(String name)
}

Renaming operations and parameters

Similarly, you can rename operations like in the example below:

client.tsp

import "./main.tsp";
import "@azure-tools/typespec-client-generator-core";

using Azure.ClientGenerator.Core;

@@clientName(Get, "Read"); // Use InputOptions as a base name in clients
@@clientName(Get, "GetComputed", "python"); // Note that Python will still snake_case it

Python

class InputModel:
  input_name: str = rest_field(rest_name="name", readonly=True)
response: InputModel = client.get_computed_model(name="name")

CSharp

namespace PetStoreNamespace.Models
{
  public partial class InputModel
  {
    public string Name { get; }
  }
}

namespace PetStoreNamespace
{
  public partial class PetStoreNamespaceClient
  {
    // protocol method
    public virtual async Task<Response> ReadModelAsync(string name, RequestContext context) {}
    public virtual Response ReadModel(string name, RequestContext context) {}
    // convenience method
    public virtual async Task<Response<InputModel>> ReadModelAsync(string name, CancellationToken cancellationToken = default) {}
    public virtual Response<InputModel> ReadModel(string name, CancellationToken cancellationToken = default) {}
  }
}

TypeScript

// Typescript do not change behavior based on protocolAPI or convenientAPI

Java

package petstorenamespace.models;
public final class InputModel {
    public String getName()
}

package petstorenamespace;
public final class PetStoreNamespaceClient {
    public Response<BinaryData> readModelWithResponse(String name, RequestOptions requestOptions)
    public InputModel readModel(String name)
}

You cannot at this moment rename parameters in the client.tsp file. You will need to add the @clientName decorator over the parameter directly, example:

Implementation

Order of Operations

For consistency when generating code, the order in which overrides are applied is important. Code emitters should apply overrides in the following order.

Over-the-Wire JSON Names

For determining the final name of a TypeSpec entity when sent over-the-wire in JSON:

1. If the @encodedName decorator exists, use this value
2. Use the original name in the spec

Client SDK Names

For determining the final name of a TypeSpec entity when used in a client SDK (e.g. Python):

1. Check if there’s a scoped @clientName decorator for your emitter
2. Check if there’s a @clientName decorator at all
3. Check the friendly name
4. Use the original name in the spec

Note: If the object name is from @clientName decorator, do not apply your language’s casing rules on it. If it’s not, apply your language’s heuristics (i.e. for Python, apply snake casing)