Azure / Azure/azure-rest-api-specs
securityinsights/2024-09-01: RestApiPollerRequestPagingConfig discriminator mapping uses wrong $ref path and is missing x-ms-discriminator-value on derived types
- Dominant language
- TypeSpec
- Stars
- 3.1k
- Forks
- 6k
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 444
Description
`RestApiPollerRequestPagingConfig` in `DataConnectors.json` defines a discriminated union via `x-ms-discriminator` on the base type, but two spec errors prevent codegen tools from resolving the derived subtypes. The result is that all subtype-specific properties (such as `nextPageTokenJsonPath` for `NextPageToken` paging) are silently dropped, making cursor-based pagination completely non-functional for CCP connectors built with generated SDKs.
**Affected file**
`specification/securityinsights/resource-manager/Microsoft.SecurityInsights/stable/2024-09-01/DataConnectors.json`
The same issue is present in the `2025-09-01` version of this file.
**Root cause: two compounding errors**
1. Wrong `$ref` path format in the discriminator mapping
The `x-ms-discriminator.mapping` block on `RestApiPollerRequestPagingConfig` references derived types using OpenAPI 3.0-style paths:
```
json"mapping": {
"NextPageToken": "#/components/schemas/RestApiPollerRequestPagingTokenConfig",
"LinkHeader": "#/components/schemas/RestApiPollerRequestPagingLinkHeaderConfig",
...
}
```
This document is a Swagger 2.0 file. All type definitions live under `#/definitions/`, not `#/components/schemas/`. A spec-conformant resolver following these refs finds nothing and silently falls back to the base type only.
The correct paths should be:
```
json"mapping": {
"NextPageToken": "#/definitions/RestApiPollerRequestPagingTokenConfig",
"PersistentToken": "#/definitions/RestApiPollerRequestPagingTokenConfig",
"LinkHeader": "#/definitions/RestApiPollerRequestPagingLinkHeaderConfig",
"PersistentLinkHeader": "#/definitions/RestApiPollerRequestPagingLinkHeaderConfig",
"NextPageUrl": "#/definitions/RestApiPollerRequestPagingNextPageUrlConfigArgs",
"Offset": "#/definitions/RestApiPollerRequestPagingOffsetConfig",
"CountBasedPaging": "#/definitions/RestApiPollerRequestPagingCountBaseConfig"
}
```
**2. Missing `x-ms-discriminator-value` on derived types**
The standard AutoRest pattern for discriminated unions — used correctly elsewhere in the same file for `CcpAuthConfig` and its subtypes. places `x-ms-discriminator-value` on each derived type. For example:
```
json"ApiKeyAuthModel": {
"x-ms-discriminator-value": "APIKey",
"allOf": [{ "$ref": "#/definitions/CcpAuthConfig" }],
...
}
```
None of the five `RestApiPollerRequestPagingConfig` derived types carry this property. Codegen tools that rely on `x-ms-discriminator-value` to identify derived types will not resolve the union even if the `$ref` path issue is corrected.
The fix is to add `x-ms-discriminator-value` to each of the five derived types, matching the pattern used by CcpAuthConfig subtypes in the same file:
Type | x-ms-discriminator-value
- RestApiPollerRequestPagingTokenConfig | "NextPageToken" (also covers "PersistentToken")
- RestApiPollerRequestPagingLinkHeaderConfig | "LinkHeader" (also covers "PersistentLinkHeader")
- RestApiPollerRequestPagingNextPageUrlConfig | "NextPageUrl"
- RestApiPollerRequestPagingOffsetConfig" | Offset"
- RestApiPollerRequestPagingCountBaseConfig | "CountBasedPaging"
**Impact**
Because codegen tools collapse `RestApiPollerRequestPagingConfig` to its base type only, the following subtype-specific properties are unreachable through any generated SDK:
Paging strategy | Dropped properties
- NextPageToken, PersistentTokennext | PageTokenJsonPath, hasNextFlagJsonPath, nextPageTokenResponseHeader, nextPageParaName, nextPageRequestHeader
- LinkHeader, PersistentLinkHeader | linkHeaderTokenJsonPath, linkHeaderRelLinkName
- NextPageUrl | nextPageUrl, nextPageUrlQueryParameters, nextPageParaName, nextPageRequestHeader, hasNextFlagJsonPath
- Offset | offsetParaName
- CountBasedPagingpageCountJsonPath, pageNumberParaName, pageNumberJsonPath, totalResultsJsonPath, zeroBasedIndexing
**Concretely:** passing `nextPageTokenJsonPath` via a generated SDK (e.g. `@pulumi/azure-native`) compiles without error but the property never reaches the Azure API. The resource deployment fails with a `400 BadRequest: "Missing NextPageTokenJsonPath from config"`. `NextPageToken` paging — the most common strategy for CCP connectors using cursor-based pagination — is entirely non-functional through any SDK built from this spec.
**Expected behavior**
Each derived type should be resolvable by codegen tools, and the generated SDKs should expose the full set of subtype-specific properties. The CcpAuthConfig discriminated union in the same file demonstrates the correct pattern and can serve as a reference.
**Steps to reproduce**
1. Generate an SDK from DataConnectors.json using AutoRest or any spec-driven codegen tool
2. Attempt to create a RestApiPollerDataConnector resource with pagingType: "NextPageToken" and nextPageTokenJsonPath set
3. Observe that nextPageTokenJsonPath is absent from the serialized request body and the Azure API returns 400 BadRequest
Contributor guide
Research direction
Start by inspecting the discriminator mapping and derived definitions in specification/securityinsights/resource-manager/Microsoft.SecurityInsights/stable/2024-09-01/DataConnectors.json, then compare the corresponding 2025-09-01 file and the CcpAuthConfig pattern. Generate an SDK with AutoRest to verify the paging properties are preserved; done means both spec versions resolve all paging subtypes and expose their subtype-specific fields.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100