Customer feedback | JSON and YAML file formats not provided | both Core & Extension

[dbradish-microsoft]

Summary: There is a recurring theme in customer feedback that centers around the lack of JSON examples in our autogenerated content. When we tell a customer that they can use a JSON file instead of a complex JSON parameter value, what does that JSON file format look like?

As of 2024-07-25, we have 5,337 instances of this phrase in our reference content: Support shorthand-syntax, json-file and yaml-file. Try "??" to show more. What does ?? show more of? As this phrase is so common, is there a repeatable JSON and YAML file format that we can put into a new article, and this phrase can be followed by "...For example file formats, see []()"?

See [Azure CLI Shorthand Syntax (Preview)](https://github.com/Azure/azure-cli/blob/dev/doc/shorthand_syntax.md) and consider it moving it to azure-docs-cli.

Suggestion: When we mention the use of a JSON or YAML file for a parameter value, we need to provide a very small example file in another example code block, in the short-summary property, or the long-summary property of the parameter.

Example customer verbatims:

Verbatim date	Reference URL	Customer verbatim
2025-03-26	https://learn.microsoft.com/en-us/cli/azure/backup/policy	Can you give examples of the policy object?
2024-10-18	https://learn.microsoft.com/en-us/cli/azure/lab/vm	When using az lab vm commands, it's possible to use in some cases the --artifacts argument. However, the schema expected for this argument is specified nowhere. I tried extracting it from the ARM template of the formula in the portal, it does not work. There are no links to documentation regarding this file.
2024-07-14	https://learn.microsoft.com/en-us/cli/azure/afd/endpoint#az-afd-endpoint-purge	Please add information on how to add multiple domains to the '--domains' parameter.
2024-05-28	https://learn.microsoft.com/en-us/cli/azure/monitor/data-collection/rule	theres an issue with this cli command when updating an existing DCR. it claims "(InvalidPayload) The new DCR kind `` is different from the previous one Linux. The kind is immutable." using the rest api from the docs works, for the same json
2024-05-28	https://learn.microsoft.com/en-us/cli/azure/monitor/data-collection/rule	this page does not tell me how to create the sample.json to create a data collection rule
2024-04-14	https://learn.microsoft.com/en-us/cli/azure/fleet/updatestrategy	An option is explained as "Path to a JSON file that defines the update strategy," but the example/schema/etc of the JSON file is not explained.
2024-04-14	https://learn.microsoft.com/ja-jp/cli/azure/fleet/updatestrategy	The example of "JSON file that defines the update strategy" is not posted, and I don't know what kind of file to prepare.
2023-09-27	https://learn.microsoft.com/en-us/cli/azure/postgres/flexible-server/migration	How the fuck am I supposed to know what is going into the migrationConfig.json file? No references or anything.
2023-06-20	https://learn.microsoft.com/en-us/cli/azure/resource	provide help on where to find the properties json
2023-05-05	https://learn.microsoft.com/en-us/cli/azure/monitor/data-collection/rule	For the az monitor data-collection rule create command the parameter rule-file is doceumented poorly: --rule-file The json file for rule parameters. It's not described how to prepare such a file, and no example is given.

[yonzhan]

Thank you for opening this issue, we will look into it.

[github-actions]

Hi, this inquiry has been well received albeit being triaged as non-security related ask.

Azure CLI is currently prioritizing direct SFI requirements and items and this request does not seem to be related to SFI. We'll retain it in our backlog at this point. Please reach out to AzPyCli@microsoft.com if you'd justify it's highly customer-impacted and need to be escalated.

Thank you,

Azure CLI team