Azure / Azure/azure-openapi-validator
[new rule]: 'itemName' must exist in response schema
- Dominant language
- TypeScript
- Stars
- 53
- Forks
- 57
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 2
Description
### Lint rule description
According to [`x-ms-pageable` definition](https://github.com/Azure/autorest/blob/main/docs/extensions/readme.md#x-ms-pageable), the `itemName` should specify the name of the property that provides the collection of pageable items. Its default value is `value`. That definition should align with the response schema.
### Related swagger example
Here is one [operation response definition](https://github.com/Azure/azure-rest-api-specs/blob/1424fc4a1f82af852a626c6ab6d1d296b5fe4df1/specification/purview/data-plane/Azure.Analytics.Purview.MetadataPolicies/preview/2021-07-01/purviewMetadataPolicy.json#L23-L45) in `Azure.Analytics.Purview.Account`.
```json
"responses": {
"200": {
"description": "Success",
"schema": {
"$ref": "#/definitions/MetadataRoleList"
}
},
"default": {
"description": "An error response received from the Metadata Policy Service",
"schema": {
"$ref": "#/definitions/ErrorResponseModel"
},
"headers": {
"x-ms-error-code": {
"type": "string",
"description": "The error code"
}
}
}
},
"x-ms-pageable": {
"nextLinkName": "nextLink"
},
"x-ms-examples": {
"MetadataRoles_List": {
"$ref": "./examples/MetadataRoles_List.json"
}
}
```
As you can see, it defines a pageable operation without defining `itemName`, so the value should be `value`. However, if you inspect the [definition](https://github.com/Azure/azure-rest-api-specs/blob/1424fc4a1f82af852a626c6ab6d1d296b5fe4df1/specification/purview/data-plane/Azure.Analytics.Purview.MetadataPolicies/preview/2021-07-01/purviewMetadataPolicy.json#L504-L520) of response `MetadataRoleList`.
```json "MetadataRoleList": {
"description": "List of Metadata roles",
"required": [
"values"
],
"type": "object",
"properties": {
"values": {
"type": "array",
"items": {
"$ref": "#/definitions/MetadataRole"
}
},
"nextLink": {
"type": "string"
}
}
```
You'll realize its `itemName` is `values`, not the default one `value`.
### Category
ARM
### Severity level
Error
### Applies to
Management plane API spec, Data plane API spec
### How to fix the violation
Fix the definition of `itemName` in `x-ms-pageable` to align with response schema definition.
### What't the impact if breaking the rule
The generated SDK codes will not correctly parse the pagination results.
Contributor guide
Assessment
This issue has not been assessed yet.