apple / apple/swift-openapi-generator

Support `oneOf` `required` sections

Open
#739 10 comments 2 reactions 0 assignees View on GitHub
area/openapi kind/enhancement status/needs-design
Dominant language
Swift
Stars
2k
Forks
182
Avg merge
13h 28m
Merged PRs (30d)
5

Description

### Description

As described in https://github.com/openai/openai-openapi/issues/391, the [OpenAI OpenAPI specification](https://github.com/openai/openai-openapi) contains the following `oneOf` `required` definitions:
```yaml
oneOf:
- required:
- vector_store_ids
- required:
- vector_stores
```

While not wrong in OpenAPI 3.0 or 3.1, the `swift-openapi-generator` doesn't properly recognize that `required` definition and produces the following warnings:
```
A property name only appears in the required list, but not in the properties map - this is likely a typo; skipping this property. [context: foundIn=Components.Schemas.CreateAssistantRequest.tool_resourcesPayload.file_searchPayload.Case1Payload (#/components/schemas/CreateAssistantRequest/tool_resources/file_search/case1)/vector_store_ids]

A property name only appears in the required list, but not in the properties map - this is likely a typo; skipping this property. [context: foundIn=Components.Schemas.CreateAssistantRequest.tool_resourcesPayload.file_searchPayload.Case2Payload (#/components/schemas/CreateAssistantRequest/tool_resources/file_search/case2)/vector_stores]
```

The `swift-openapi-generator` should support this valid syntax.

### Reproduction

The usage of the following [OpenAI OpenAPI spec](https://github.com/openai/openai-openapi) results in the `swift-openapi-generator` not properly recognizing the `required` definition and produces warnings.

A small excerpt of the relevant piece of the OpenAI OpenAPI spec:
```yaml
openapi: 3.0.0
# ...
tool_resources:
type: object
description: >
A set of resources that are used by the assistant's tools. The
resources are specific to the type of tool. For example, the
`code_interpreter` tool requires a list of file IDs, while the
`file_search` tool requires a list of vector store IDs.
properties:
code_interpreter:
type: object
properties:
file_ids:
type: array
description: >
A list of [file](/docs/api-reference/files) IDs made
available to the `code_interpreter` tool. There can be a
maximum of 20 files associated with the tool.
default: []
maxItems: 20
items:
type: string
file_search:
type: object
properties:
vector_store_ids:
type: array
description: >
The [vector store](/docs/api-reference/vector-stores/object)
attached to this assistant. There can be a maximum of 1
vector store attached to the assistant.
maxItems: 1
items:
type: string
vector_stores:
type: array
description: >
A helper to create a [vector
store](/docs/api-reference/vector-stores/object) with
file_ids and attach it to this assistant. There can be a
maximum of 1 vector store attached to the assistant.
maxItems: 1
items:
type: object
properties:
file_ids:
type: array
description: >
A list of [file](/docs/api-reference/files) IDs to add
to the vector store. There can be a maximum of 10000
files in a vector store.
maxItems: 10000
items:
type: string
chunking_strategy:
type: object
description: The chunking strategy used to chunk the file(s). If not set, will
use the `auto` strategy.
oneOf:
- type: object
title: Auto Chunking Strategy
description: The default strategy. This strategy currently uses a
`max_chunk_size_tokens` of `800` and
`chunk_overlap_tokens` of `400`.
additionalProperties: false
properties:
type:
type: string
description: Always `auto`.
enum:
- auto
x-stainless-const: true
required:
- type
- type: object
title: Static Chunking Strategy
additionalProperties: false
properties:
type:
type: string
description: Always `static`.
enum:
- static
x-stainless-const: true
static:
type: object
additionalProperties: false
properties:
max_chunk_size_tokens:
type: integer
minimum: 100
maximum: 4096
description: The maximum number of tokens in each chunk. The default value is
`800`. The minimum value is `100` and the
maximum value is `4096`.
chunk_overlap_tokens:
type: integer
description: >
The number of tokens that overlap between
chunks. The default value is `400`.

Note that the overlap must not exceed half
of `max_chunk_size_tokens`.
required:
- max_chunk_size_tokens
- chunk_overlap_tokens
required:
- type
- static
x-oaiExpandable: true
metadata:
$ref: "#/components/schemas/Metadata"
oneOf: # Syntax not recognized by the swift-openapi-generator
- required:
- vector_store_ids
- required:
- vector_stores
nullable: true
# ...
```

Swift Generator config:
```yaml
generate:
- types
- client
accessModifier: package
```

Results in the following warnings:
```
A property name only appears in the required list, but not in the properties map - this is likely a typo; skipping this property. [context: foundIn=Components.Schemas.CreateAssistantRequest.tool_resourcesPayload.file_searchPayload.Case1Payload (#/components/schemas/CreateAssistantRequest/tool_resources/file_search/case1)/vector_store_ids]

A property name only appears in the required list, but not in the properties map - this is likely a typo; skipping this property. [context: foundIn=Components.Schemas.CreateAssistantRequest.tool_resourcesPayload.file_searchPayload.Case2Payload (#/components/schemas/CreateAssistantRequest/tool_resources/file_search/case2)/vector_stores]
```

### Package version(s)

```console
├── swift-openapi-generator
│ ├── swift-algorithms
│ │ └── swift-numerics
│ ├── swift-collections
│ ├── openapikit
│ │ └── yams
│ ├── yams
│ └── swift-argument-parser
├── swift-openapi-runtime
│ └── swift-http-types
└── swift-openapi-urlsession
├── swift-openapi-runtime
│ └── swift-http-types
├── swift-http-types
└── swift-collections
```

### Expected behavior

The `oneOf` required definition should be properly recognized by the generator and used for the Swift output generation.

### Environment

```console
swift-driver version: 1.115.1 Apple Swift version 6.0.3 (swiftlang-6.0.3.1.10 clang-1600.0.30.1)
Target: arm64-apple-macosx15.0
```

### Additional information

_No response_

Contributor guide

Open the contributing guide

Research direction

Start in the swift-openapi-generator code path that processes OpenAPI oneOf schemas and required properties, using the OpenAI specification excerpt as the reproduction. Verify the generated Swift output and warnings for the vector_store_ids/vector_stores cases; done means the valid oneOf required sections are recognized without the reported warnings.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, swift
Domain
api, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.