apple / apple/swift-openapi-generator

Support nullable referenced schemas using anyOf with type: null

Open
#906 1 comment 8 reactions 0 assignees View on GitHub
Dominant language
Swift
Stars
2k
Forks
182
Avg merge
13h 28m
Merged PRs (30d)
5

Description

### Description

When an OpenAPI 3.1 schema uses `anyOf` with a `$ref` and a `type: "null"` branch, Swift OpenAPI Generator does not appear to generate the expected optional Swift property.

Minimal schema:

```yaml
openapi: 3.1.0
info:
title: Repro
version: 1.0.0
paths: {}
components:
schemas:
Parent:
type: object
properties:
child:
anyOf:
- $ref: '#/components/schemas/Child'
- type: 'null'
required:
- child
Child:
type: object
properties:
name:
type: string
required:
- name
```

### Expected behavior

The generated Swift type for `Parent` should allow `child` to be decoded/encoded as a nullable referenced object, for example as an optional `Child`-like generated property.

### Actual behavior

The generator did not produce a usable optional property for this schema shape in my project. I had to switch to this workaround:

```yaml
child:
allOf:
- $ref: '#/components/schemas/Child'
nullable: true
```

That workaround generates a usable optional Swift property, but it also emits warnings because `nullable` is not part of the OpenAPI 3.1 schema vocabulary:

```text
Found 'nullable' property. This property is not supported by OpenAPI v3.1.0.
OpenAPIKit has translated it into 'type: ["null", ...]'.
```

### Why this matters

OpenAPI 3.1 supports JSON Schema's `null` type, so `anyOf`/`oneOf` with a `type: "null"` branch is a common way to express a nullable `$ref`. It would be useful if Swift OpenAPI Generator supported this directly, or documented the recommended schema shape for nullable referenced objects.

### Environment

- Swift OpenAPI Generator: 1.12.0
- OpenAPI document version: 3.1.0
- Swift toolchain: Xcode toolchain, Swift 6.x

Contributor guide

Open the contributing guide

Research direction

Start by running Swift OpenAPI Generator 1.12.0 against the minimal OpenAPI 3.1 schema in the issue and inspect the generated Parent and Child types. Trace how the anyOf branches containing a $ref and type: "null" are handled, then verify that child is a usable nullable Child-like property without requiring the nullable workaround.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
api, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.