Improve docs for x-ms-arm-id-details

Open TimLovellSmith opened this issue 10 months ago • 0 comments

Before filling a bug

[ ] have you checked the faq for known issues.
[ ] have you checked existing issues

Describe the bug

This doc examples seem inconsistent. Are 'types' and 'scopes' fields part of 'AllowedResources', 'allowedScopes', or both?

https://azure.github.io/autorest/extensions/#x-ms-arm-id-details

x-ms-arm-id-details
Can only be set on "type": "string" fields with "format": "arm-id".

When set, specifies the set of resource types which can be referenced by this arm-id. If this extension isn’t provided for a particular arm-id, the field can refer to any valid ARM ID.

Parent element: Parameter Object, Schema Object, or Items Object

Schema
Field Name	Type	Description
allowedResources	[AllowedResource]	Required An array of allowed ARM resources. Each element represents a particular type of ARM resource which can be referred to by this arm-id.

<html>
<body>
<!--StartFragment-->
Resource in a tenant | {"scopes": ["Tenant"], "type": "Microsoft.Capacity/reservationOrders"}
-- | --


<!--EndFragment-->
</body>
</html>

Example: An arm-id field that must refer to a virtual network

"MyExampleType": {
  "properties": {
    "vnetId": {
      "type": "string",
      "format": "arm-id",
      "x-ms-arm-id-details": {
        "allowedResources": [
          {
            "type": "Microsoft.Network/virtualNetworks"
          }
        ]
      }
    }
  }
}

Expected behavior The examples should both match the schema. I think the VirtualNetwork example is good. But the "Resource in a tenant" example is confusing. It looks like the 'scope' goes inside the allowedResources property bag.

Also, there's a formatting issue with the 'allowed scopes schema' it doesn't display correctly~

Additional context

Feb 21 '25 18:02 TimLovellSmith