Fix OpenAPI import: preserve description and decorators for anyOf/oneOf with null

[Copilot]

The OpenAPI 3.1 import tool was losing description and decorator information when converting schemas with anyOf/oneOf containing a definition + null type. This is a common pattern in OpenAPI 3.1 as an equivalent to nullable: true from OpenAPI 3.0.

Before this fix:

# OpenAPI 3.1 schema
ReasoningEffort:
  anyOf:
    - type: string
      enum: [minimal, low, medium, high]
      default: medium
      description: "Constrains effort on reasoning for reasoning models..."
    - type: 'null'

Generated incomplete TypeSpec:

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

After this fix:

/**
 * Constrains effort on reasoning for reasoning models...
 */
union ReasoningEffort {
  "minimal" | "low" | "medium" | "high" = "medium",
  null,
}

Changes Made

1. Enhanced union metadata extraction: Added logic to identify and extract descriptions and decorators from meaningful (non-null) members in anyOf/oneOf scenarios.

2. Support for type arrays: Fixed handling of OpenAPI 3.1 type arrays like ["string", "null"] to properly preserve constraints and descriptions.

3. Improved type identification: Updated getTypeSpecKind to correctly identify type arrays containing "null" as unions rather than scalars.

Test Coverage

Added comprehensive test suite covering:

• anyOf with definition + null
• oneOf with constraints + null
• Type arrays like ["integer", "null"]
• Reference types with null
• Edge cases and backward compatibility

All existing tests continue to pass (1609 tests).

Fixes #8513.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/typespec/typespec/website/node_modules/.bin/../astro/astro.js build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[github-actions]

All changed packages have been documented.

• ✅ @typespec/openapi3

Show changes

@typespec/openapi3 - fix ✏️

[converter] anyOf/oneOf type + type:null gets imported properly and maintains decorators, documentation,...