Azure / Azure/azure-rest-api-specs

[BUG] Azure OpenAI 2025-03-01-preview and 2025-04-01-preview multiple issues

Open
#33,724 6 comments 3 reactions 0 assignees View on GitHub
bug customer-reported data-plane OpenAI question Service Attention
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/tree/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2025-03-01-preview

### API Spec version

2025-03-01-preview

### Describe the bug

# Multiple errors with specification

OpenAPI specification for API version 2025-03-01-preview has been updated to **3.1.0** from previous **3.0.0** (in 2025-02-01-preview and below) and now uses recursion. This makes it incompatible with API Management API import capability. Recursion is used only in a single place and should ideally either be removed or a non-recursive version provided.

OpenAPI 3.1.0 foregoes `nullable: true` in favour of specifying nullability as:

```yaml
type: ['null', string]
```
or
```yaml
type:
- 'null'
- string
```
Yet the specification file uses OpenAPI 3.0.* variant which is not valid in **197** places. Trying lint with redocly-cli generates **241** errors (some of which are for missing 4xx responses definitions). Any suitably strict API spec parser will reject this file.

Furthermore, API specification references [WebSearchTool](https://github.com/Azure/azure-rest-api-specs/blob/49ccdfef22c98c88c4d90261156a6d182f675c8f/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2025-03-01-preview/inference.yaml#L12444) which is orphaned (reference is pointing at non-existent section). This tool is not available in 2025-03-01-preview API as per [documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/responses).

Trying to load API specification in swagger editor (non preview version) highlights further issues with the way API specification has been defined and needs significant further review. There are incorrect properties in places and invalid definitions according to either API spec, e.g. [here](https://github.com/Azure/azure-rest-api-specs/blob/49ccdfef22c98c88c4d90261156a6d182f675c8f/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2025-03-01-preview/inference.yaml#L12596).

A suggestion is to either revert back to 3.0.* spec and avoid nullability issues (forcing need to eliminate recursion and making API compatible with APIM again) or perform a comprehensive rewrite using OpenAPI 3.1.0. Current version is neither.

### Expected behavior

Valid API definition that follows standard specification.

### Actual behavior

Numerous errors with API definition, mixing definitions from 3.0.* and 3.1.* and orphan links to references. Mismatch between specification and documentation.

### Reproduction Steps

Load API specification in swagger editor (validating original version, not the preview). Run linter, such as open source Redocly CLI on the specification file.

### Environment

Azure API Management, redocly-cli 1.34.1

Contributor guide

Open the contributing guide

Research direction

Start with specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2025-03-01-preview/inference.yaml and load the specification in Swagger Editor. Run Redocly CLI 1.34.1 against the specification, then review the reported OpenAPI 3.0/3.1 incompatibilities, recursion, missing references, and documentation mismatch. Done means a valid API definition that follows the standard and matches the documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, yaml
Domain
api, backend-api-design
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
18/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.