Azure / Azure/azure-rest-api-specs
[BUG] [Search] KnowledgeBaseIndexedSharePointReference.docUrl is incorrectly modeled as top-level property
- Dominant language
- TypeSpec
- Stars
- 3.1k
- Forks
- 5.9k
- Avg merge
- 2d 22h
- Merged PRs (30d)
- 444
Description
### API Spec link
https://github.com/Azure/azure-rest-api-specs/blob/main/specification/search/data-plane/Search/preview/2025-11-01-preview/search.json
### API Spec version
2025-11-01-preview
### Describe the bug
The spec defines [docUrl] as a top-level property of [KnowledgeBaseIndexedSharePointReference]. However, the actual API response does not return that field at the top level. Instead, the value is returned inside the [sourceData] object (and with snake_case naming: doc_url).
### Expected behavior
__Expected spec model__
[docUrl] should either:
- Be removed as top-level properties of the reference types and instead be documented as known keys within the [sourceData] dictionary, or
- Be moved to be defined as property inside a typed [sourceData] model (instead of [sourceData] being an untyped Record) or
- Be moved as first level property
### Actual behavior
__Actual API response__
When calling
```POST /knowledgebases('{name}')/retrieve?api-version=2025-11-01-preview``` with "__includeReferenceSourceData__": true, the response looks like:
```json
{
"references": [
{
"type": "indexedSharePoint",
"id": "0",
"activitySource": 1,
"sourceData": {
"uid": "...",
"doc_url": "/drives/.../root:/sample.pdf",
"snippet": "..."
},
"rerankerScore": 3.1165779
}
]
}
```
Note:
- doc_url is inside [sourceData], not a top-level sibling of type, [id].
- The JSON key is doc_url (snake_case), not [docUrl](camelCase).
### Reproduction Steps
```POST https://{{SearchService}}/knowledgebases('kb-products')/retrieve?api-version=2025-11-01-preview```
```json
{
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": " During Solar Flare Alert Level Gamma, \r\n what is Abyx\u2019s official required throughput \r\n reduction, and what alternative reduction \r\n is suggested by internal simulations?"
}
]
}
],
"retrievalReasoningEffort": {
"kind": "low"
},
"outputMode": "extractiveData", // extractiveData | answerSynthesis
// "knowledgeSourceParams": [
// {
// "knowledgeSourceName": "ks-sp-abyx-products",
// "includeReferences": true,
// "includeReferenceSourceData": true,
// "alwaysQuerySource": false,
// //"rerankerThreshold": 2.1,
// "kind": "indexedSharePoint"
// }
// ],
"includeActivity": true
}
```
```docUrl``` not returned as indexedSharePoint reference:
```json
"references": [
{
"type": "indexedSharePoint",
"id": "0",
"activitySource": 1,
"sourceData": null,
"rerankerScore": 3.1165779
}
]
```
However, if you uncomment the ```knowledgeSourceParams``` section, you will get the doc_url param in the ```sourceData``` section:
```json
{
"type": "indexedSharePoint",
"id": "0",
"activitySource": 1,
"sourceData": {
"uid": "XXXXX1_pages_0",
"doc_url": "/drives/b!oxxxxxxO/root:/Abyx_Product_04_HelixRail_Mobility_Grid.pdf",
"snippet": "..."
},
"rerankerScore": 3.1165779
},
```
### Environment
Not apply.
Contributor guide
Research direction
Open specification/search/data-plane/Search/preview/2025-11-01-preview/search.json and inspect KnowledgeBaseIndexedSharePointReference, its docUrl property, and sourceData. Compare the model with the reproduced retrieve response, then confirm which of the listed modeling options is intended before updating the spec so the documented shape and naming match the API.
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
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100