Azure-docs: The example JSON should follow the REST spec

[jiasli]

The example JSON should follow the Role Definitions - Create Or Update REST API spec, and also use camelCase, instead of PascalCase.

These properties don't match their REST equivalents:

"Name": "Virtual Machine Operator",
"Id": "88888888-8888-8888-8888-888888888888",

The mapping is

| This doc | REST spec | Definition
|----------|---------------------|-------------
| Name | properties.roleName | The literal name, like Virtual Machine Operator
| Id | name | A GUID, like 6134dd49-621f-4c59-94db-a56b3f7e45f8
| - | id | A resource ID, like /subscriptions/subID/providers/Microsoft.Authorization/roleDefinitions/6134dd49-621f-4c59-94db-a56b3f7e45f8

This causes lots of confusions, including the help messages from az role definition create --help and az role definition update --help which follow this doc but don't comply with the REST spec.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: eac44e5e-65e1-d989-4afe-0463e8ff51d0
• Version Independent ID: 5665dd03-d06e-ca29-668f-7cb91e5f9ffd
• Content: Custom roles for Azure resources
• Content Source: articles/role-based-access-control/custom-roles.md
• Service: role-based-access-control
• GitHub Login: @rolyon
• Microsoft Alias: rolyon

[SwathiDhanwada-MSFT]

@jiasli Thanks for your comment. We are actively investigating and will get back to you shortly.

[jiasli]

The inconsistency also caused the confusion at https://github.com/MicrosoftDocs/azure-docs/issues/34334. We should stick with the new ARM style and eliminate the unnecessary manual transformation.

[SwathiDhanwada-MSFT]

@jiasli Thanks for analysis and valuable feedback.

@rolyon Can you please review the issue and update the document accordingly?

[rolyon]

Hi @jiasli
Thanks for your feedback. This example shows the capping for PowerShell, which most customers use. I will update the docs to make this more clear.
thanks

[rolyon]

Hi @jiasli
We published a doc update that hopefully makes this more clear.
https://docs.microsoft.com/en-us/azure/role-based-access-control/custom-roles
If you have any additional feedback, feel free to reopen this issue.
thanks

[rolyon]

please-close

[jiasli]

@rolyon, the update looks great! Azure CLI will switch to the one in REST spec in the future. At least, it is now clearer for the users.