Skip to content

[Bug]: import tool anyOf type null + definition leads to loss of information #8513

@baywet

Description

@baywet

Describe the bug

In OpenAPI 3.1, using an any/oneOf with one entry being a definition and the other being a simple type: null schema is often used as equivalent of nullable: true in OpenAPI 3.0. (the alternative is to use a type array)

When importing those using the import tool, the example below results in this TypeSpec definition

union ReasoningEffort {
  "minimal" | "low" | "medium" | "high",
  null,
}

Notice how the description and the default value are missing.

I'd have expected something like this instead (the default value of a union type cannot be expressed currently, so that'd be lossy)

/**
* Constrains effort on reasoning for
* [reasoning models](https://platform.openai.com/docs/guides/reasoning).
* Currently supported values are `minimal`, `low`, `medium`, and `high`. Reducing
* reasoning effort can result in faster responses and fewer tokens used
* on reasoning in a response.
*/
union ReasoningEffort {
  "minimal" | "low" | "medium" | "high",
  null,
}

This issue also applies to decorators (like min/maxValue), and extensions as soon as an anyOf/oneOf definition + type: null is in use. I think this import scenario should be special-cased so we don't end up loosing a bunch of information.

Note: the other way to express that (type: [something, null]) should also be implemented and tested against.

Reproduction

Here is a fragment of OpenAPI description that reproduces the issue

components:
  schemas:
    ReasoningEffort:
      anyOf:
        - type: string
          enum:
            - minimal
            - low
            - medium
            - high
          default: medium
          description: |
            Constrains effort on reasoning for
            [reasoning models](https://platform.openai.com/docs/guides/reasoning).
            Currently supported values are `minimal`, `low`, `medium`, and `high`. Reducing
            reasoning effort can result in faster responses and fewer tokens used
            on reasoning in a response.
        - type: 'null'

Checklist

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingopenapi3:converterIssues for @typespec/openapi3 openapi to typespec converter

Type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions