Azure / Azure/azure-rest-api-specs

[BUG] [Search] KnowledgeBaseIndexedSharePointReference.docUrl is incorrectly modeled as top-level property

Open
#41,158 0 comments 0 reactions 0 assignees View on GitHub
bug customer-reported question
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.