Determine "value" or "values" recommendation

[markweitzel]

The value (singular) naming convention comes from OData. I don't think we've been consistent in Azure. I'd do an inventory of what is being used today and unless there is a clear winner/a large majority uses value, I don't have a strong opinion. We obviously wouldn't want to recommend breaking changes to "fix" the consistency problem, however.

Originally posted by @johanste in Azure/azure-rest-api-specs#14938 (comment)

Note: This replaces #16015

[mikekistler]

It does appear that "value" is much more commonly used than "values". A quick search in azure-rest-api-specs shows:

• "value": { --14344 results in 4062 files
• "values": { --357 results in 208 files

Note that this simple text search might not be completely accurate, but the results are so lopsided I think the conclusion is still safe.

But I personally find using a singular name for an array property unnatural and potentially confusing to users. So I think I'd prefer to allow "values" -- that is, not suggest that it be changed to "value" in cases where it could be changed without compatibility concerns.

And we could go even further and allow other names that make sense. For example, the IBM API Guidelines say that the array property name should be

the same plural resource name appearing in the collection's URL

This actually feels the most natural to me, but I suppose that's not surprising since I advocated for it at IBM. And in a few minutes of searching I could not find any instances of this pattern in Azure APIs.

So if we really want to drive consistency, I guess we should make "value" the only option.

[mikekistler]

Another point we may want to consider is that the ARM openapi validator already checks specifically for “value” in the body of a pageable response. It is rule R3008.

[johanste]

That should not have been an ARM rule. It was applicable to all API designs.

[markweitzel]

API Stewardship LT meeting 9/20

We will update the guidelines to specify the singular value