Skip to content

Encoded names

There is some cases where the name you have in TypeSpec might differ from the name over the wire or for a certain language.

Update name for a given target

To update the name of a TypeSpec entity you can use the @encodedName decorator. This decorator takes 2 parameters:

ParameterTypeDescription
mimeTypestringMime type this should apply to. The mime type should be a known mime type as described here https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types without any suffix (e.g. +json)
encodedNamestringThe name should be when serialized to the given mime type.

Example:

model Foo {
  // Specify that when serializing to JSON `expireAt` property should be named `exp`
  @encodedName("json", "exp")
  expireAt: string;
}

Example

model CertificateAttributes {
  @encodedName("application/json", "nbf")
  notBefore: int32;


  @encodedName("application/json", "exp")
  @encodedName("application/xml", "ExpireAt")
  expires: int32;


  created: int32;
  updated: int32;
}
Json Xml Yaml
When serialized to `application/json` properties will use the encodedName for `application/json` if available or default to the property name. When serialized to `application/xml` properties will use the encodedName for `application/xml` if available or default to the property name. Yaml didn't provide any different names so it will serialize using the property names. 
{
  "nbf": 1430344421,
  "exp": 2208988799,
  "created": 1493938289,
  "updated": 1493938291
}
 
<CertificateAttributes>
  <notBefore>1430344421</notBefore>
  <ExpireAt>2208988799</ExpireAt>
  <created>1493938289</created>
  <updated>1493938291</updated>
</CertificateAttributes>
 
notBefore: 1430344421
expires: 2208988799
created: 1493938289
updated: 1493938291

Use in library/emitter

To consume the value of @encodedName in your library or emitter you can use resolveEncodedName(target: Type, mimeType: string): string from the compiler.

import { resolveEncodedName } from "@typespec/compiler";


// Resolve the encoded name for the given property and mime type. If the property doesn't have a encoded name for the given mime type it will return the property name.
const encodedName = resolveEncodedName(property, "application/json");


// You can also pass a full http mime type and `resolveEncodedName` will automatically resolve it to the base mime type.
const encodedName = resolveEncodedName(property, "application/merge-patch+json");