Azure / Azure/azure-rest-api-specs
[BUG] Azure OpenAI 2025-03-01-preview and 2025-04-01-preview multiple issues
- 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
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