Azure / Azure/azure-openapi-validator

[new rule]: 'itemName' must exist in response schema

Open
#351 0 comments 0 reactions 0 assignees View on GitHub
sdk-rule
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.