x-ms-identifiers alternatives

.chronus/changes/x-ms-identifiers-alternatives-2024-11-12-14-15-30.md

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-autorest"
+  - "@azure-tools/typespec-azure-resource-manager"
+---
+
+Use the @identifiers decorator to identify and utilize identifiers for x-ms-identifiers. Additionally, use the @key decorator to identify identifiers.

packages/typespec-autorest/src/openapi.ts

@@ -12,6 +12,7 @@ import {
 } from "@azure-tools/typespec-azure-core";
 import {
   getArmCommonTypeOpenAPIRef,
+  getArmIdentifiers,
   isArmCommonType,
   isAzureResource,
   isConditionallyFlattened,
@@ -1833,6 +1834,10 @@ export async function getOpenAPIForService(
     );
   }
 
+  function ifArmIdentifiersDefault(armIdentifiers: string[]) {
+    return armIdentifiers.every((identifier) => identifier === "id" || identifier === "name");
+  }
+
   function getSchemaForUnionVariant(
     variant: UnionVariant,
     schemaContext: SchemaContext,
@@ -2373,9 +2378,18 @@ export async function getOpenAPIForService(
           visibility: context.visibility | Visibility.Item,
         }),
       };
-      if (!ifArrayItemContainsIdentifier(program, typespecType as any)) {
+
+      const armIdentifiers = getArmIdentifiers(program, typespecType);
+      if (
+        armIdentifiers !== undefined &&
+        armIdentifiers.length > 0 &&
+        !ifArmIdentifiersDefault(armIdentifiers)
+      ) {
+        array["x-ms-identifiers"] = armIdentifiers;
+      } else if (!ifArrayItemContainsIdentifier(program, typespecType as any)) {
         array["x-ms-identifiers"] = [];
       }
+
       return applyIntrinsicDecorators(typespecType, array);
     }
     return undefined;

packages/typespec-autorest/test/openapi-output.test.ts

@@ -823,6 +823,180 @@ describe("typespec-autorest: extension decorator", () => {
   });
 });
 
+describe("typespec-azure: identifiers decorator", () => {
+  it("ignores name/id keys for x-ms-identifiers", async () => {
+    const oapi = await openApiFor(
+      `
+      model Pet {
+        @key
+        name: string;
+        @key
+        id: int32;
+      }
+      model PetList {
+        value: Pet[]
+      }
+      @route("/Pets")
+      @get op list(): PetList;
+      `,
+    );
+    ok(oapi.paths["/Pets"].get);
+    deepStrictEqual(oapi.definitions.PetList.properties.value["x-ms-identifiers"], undefined);
+  });
+  it("uses identifiers decorator for properties", async () => {
+    const oapi = await openApiFor(
+      `
+      model Pet {
+        name: string;
+        age: int32;
+      }
+      model PetList {
+        @identifiers(["age"])
+        value: Pet[]
+      }
+      @route("/Pets")
+      @get op list(): PetList;
+      `,
+    );
+    ok(oapi.paths["/Pets"].get);
+    deepStrictEqual(oapi.definitions.PetList.properties.value["x-ms-identifiers"], ["age"]);
+  });
+  it("identifies keys correctly as x-ms-identifiers", async () => {
+    const oapi = await openApiFor(
+      `
+      model Pet {
+        name: string;
+        @key
+        age: int32;
+      }
+      model PetList {
+        value: Pet[]
+      }
+      @route("/Pets")
+      @get op list(): PetList;
+      `,
+    );
+    ok(oapi.paths["/Pets"].get);
+    deepStrictEqual(oapi.definitions.PetList.properties.value["x-ms-identifiers"], ["age"]);
+  });
+  it("prioritizes identifiers decorator over keys", async () => {
+    const oapi = await openApiFor(
+      `
+      model Pet {
+        name: string;
+        @key
+        age: int32;
+      }
+      model PetList {
+        @identifiers([])
+        value: Pet[]
+      }
+      @route("/Pets")
+      @get op list(): PetList;
+      `,
+    );
+    ok(oapi.paths["/Pets"].get);
+    deepStrictEqual(oapi.definitions.PetList.properties.value["x-ms-identifiers"], []);
+  });
+  it("supports multiple identifiers", async () => {
+    const oapi = await openApiFor(
+      `
+      model Pet {
+        name: string;
+        age: int32;
+      }
+      model PetList {
+        @identifiers(["name", "age"])
+        value: Pet[]
+      }
+      @route("/Pets")
+      @get op list(): PetList;
+      `,
+    );
+    ok(oapi.paths["/Pets"].get);
+    deepStrictEqual(oapi.definitions.PetList.properties.value["x-ms-identifiers"], ["name", "age"]);
+  });
+  it("supports inner properties in identifiers decorator", async () => {
+    const oapi = await openApiFor(
+      `
+        model Pet {
+          dogs: Dog;
+        }
+
+        model Dog {
+          breed: string;
+        }
+
+        model PetList {
+          @identifiers(["dogs/breed"])
+          pets: Pet[]
+        }
+        @route("/Pets")
+        @get op list(): PetList;
+      `,
+    );
+    ok(oapi.paths["/Pets"].get);
+    deepStrictEqual(oapi.definitions.PetList.properties.pets["x-ms-identifiers"], ["dogs/breed"]);
+  });
+  it("supports inner properties for keys", async () => {
+    const oapi = await openApiFor(
+      `
+        model Pet {
+          dogs: Dog;
+          cats: Cat;
+        }
+
+        model Dog {
+          @key
+          breed: string;
+        }
+
+        model Cat
+        {
+          features: Features;
+        }
+
+        model Features {
+            @key
+            color:string;
+            size:int32;
+        }
+
+        model PetList {
+          pets: Pet[]
+        }
+
+        @route("/Pets")
+        @get op list(): PetList;
+      `,
+    );
+    ok(oapi.paths["/Pets"].get);
+    deepStrictEqual(oapi.definitions.PetList.properties.pets["x-ms-identifiers"], [
+      "dogs/breed",
+      "cats/features/color",
+    ]);
+  });
+  it("supports multiple keys", async () => {
+    const oapi = await openApiFor(
+      `
+        model Pet {
+          @key
+          name: string;
+          @key
+          age: int32;
+        }       
+        model PetList {
+          pets: Pet[]
+        }
+        @route("/Pets")
+        @get op list(): PetList;
+      `,
+    );
+    ok(oapi.paths["/Pets"].get);
+    deepStrictEqual(oapi.definitions.PetList.properties.pets["x-ms-identifiers"], ["name", "age"]);
+  });
+});
+
 describe("typespec-autorest: multipart formData", () => {
   it("expands model into formData parameters", async () => {
     const oapi = await openApiFor(`

packages/typespec-azure-resource-manager/README.md

@@ -79,6 +79,7 @@ Available ruleSets:
 - [`@armResourceUpdate`](#@armresourceupdate)
 - [`@armVirtualResource`](#@armvirtualresource)
 - [`@extensionResource`](#@extensionresource)
+- [`@identifiers`](#@identifiers)
 - [`@locationResource`](#@locationresource)
 - [`@resourceBaseType`](#@resourcebasetype)
 - [`@resourceGroupResource`](#@resourcegroupresource)
@@ -353,6 +354,34 @@ See more details on [different Azure Resource Manager resource type here.](https
 
 None
 
+#### `@identifiers`
+
+This decorator is used to indicate the identifying properties of objects in the array, e.g. size
+The properties that are used as identifiers for the object needs to be provided as a list of strings.
+
+```typespec
+@Azure.ResourceManager.identifiers(properties: string[])
+```
+
+##### Target
+
+`ModelProperty`
+
+##### Parameters
+
+| Name       | Type       | Description                                                                                                         |
+| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
+| properties | `string[]` | The list of properties that are used as identifiers for the object. This needs to be provided as a list of strings. |
+
+##### Examples
+
+```typespec
+model Pet {
+  @identifiers(["size"])
+  dog: Dog;
+}
+```
+
 #### `@locationResource`
 
 `@locationResource` marks an Azure Resource Manager resource model as a location based resource.

packages/typespec-azure-resource-manager/generated-defs/Azure.ResourceManager.ts

@@ -1,9 +1,10 @@
-import type {
+import {
   DecoratorContext,
   EnumMember,
   EnumValue,
   Interface,
   Model,
+  ModelProperty,
   Namespace,
   Operation,
   Type,
@@ -266,6 +267,12 @@ export type ResourceBaseTypeDecorator = (
   baseType: Type,
 ) => void;
 
+export type IdentifiersDecorator = (
+  context: DecoratorContext,
+  target: ModelProperty,
+  properties: string[],
+) => void;
+
 export type AzureResourceManagerDecorators = {
   armResourceCollectionAction: ArmResourceCollectionActionDecorator;
   armProviderNameValue: ArmProviderNameValueDecorator;
@@ -288,6 +295,7 @@ export type AzureResourceManagerDecorators = {
   armCommonTypesVersion: ArmCommonTypesVersionDecorator;
   armVirtualResource: ArmVirtualResourceDecorator;
   resourceBaseType: ResourceBaseTypeDecorator;
+  identifiers: IdentifiersDecorator;
 };
 
 export type AzureResourceManagerLegacyDecorators = {

packages/typespec-azure-resource-manager/lib/decorators.tsp

@@ -191,3 +191,19 @@ extern dec resourceBaseType(
   target: Model,
   baseType: "Tenant" | "Subscription" | "ResourceGroup" | "Location" | "Extension"
 );
+
+/**
+ * This decorator is used to indicate the identifying properties of objects in the array, e.g. size
+ * The properties that are used as identifiers for the object needs to be provided as a list of strings.
+ *
+ * @param properties The list of properties that are used as identifiers for the object. This needs to be provided as a list of strings.
+ *
+ * @example
+ * ```typespec
+ * model Pet {
+ *  @identifiers(["size"])
+ *  dog: Dog;
+ * }
+ * ```
+ */
+extern dec identifiers(entity: ModelProperty, properties: string[]);

packages/typespec-azure-resource-manager/src/lib.ts

@@ -14,6 +14,10 @@ export const $lib = createTypeSpecLibrary({
       messages: {
         armUpdateProviderNamespace:
           "The parameter to @armUpdateProviderNamespace must be an operation with a 'provider' parameter.",
+        armIdentifiersIncorrectEntity:
+          "The @identifiers decorator must be applied to a property that is an array of objects",
+        armIdentifiersProperties:
+          "The @identifiers decorator expects a parameter that is an array of strings or an empty array.",
       },
     },
     "arm-resource-circular-ancestry": {