openai / openai/openai-openapi
Some implementations cant merge schemas defined in `allOf` property.
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 2.5k
- Forks
- 527
- Avg merge
- 1h 46m
- Merged PRs (30d)
- 2
Description
The following exists in the openapi schema:
response_format:
allOf:
- $ref: "#/components/schemas/AssistantsApiResponseFormatOption"
- nullable: true
Which means merging the schemas in the list (detailed here).
In AssistantsApiResponseFormatOption:
AssistantsApiResponseFormatOption:
description: >
Specifies the format that the model must output. Compatible with
[GPT-4o](/docs/models#gpt-4o), [GPT-4
Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models
since `gpt-3.5-turbo-1106`.
Setting to `{ "type": "json_schema", "json_schema": {...} }` enables
Structured Outputs which ensures the model will match your supplied JSON
schema. Learn more in the [Structured Outputs
guide](/docs/guides/structured-outputs).
Setting to `{ "type": "json_object" }` enables JSON mode, which ensures
the message the model generates is valid JSON.
**Important:** when using JSON mode, you **must** also instruct the
model to produce JSON yourself via a system or user message. Without
this, the model may generate an unending stream of whitespace until the
generation reaches the token limit, resulting in a long-running and
seemingly "stuck" request. Also note that the message content may be
partially cut off if `finish_reason="length"`, which indicates the
generation exceeded `max_tokens` or the conversation exceeded the max
context length.
oneOf:
- type: string
description: |
`auto` is the default value
enum:
- auto
x-stainless-const: true
- $ref: "#/components/schemas/ResponseFormatText"
- $ref: "#/components/schemas/ResponseFormatJsonObject"
- $ref: "#/components/schemas/ResponseFormatJsonSchema"
x-oaiExpandable: true
No nullable: true is defined.
This means, according to the openapi specification (detailed here) that the value of the nullable is false!
Implementations of openapi parsers that are strict to the specifications I linked to earlier, will throw an exception, because trying to merge schemas that have the same field with different values has undefined, unexpected behaviour.
I guess that in practice, many implementations decided to treat merging a schema which has a property defined and one which doesn't define it in an out-of-spec way, using the value from the schema with the value defined, and completely ignoring the one which didn't define any value. This breaks the specs I linked to earlier, and probably why nobody noticed it before.
Edit 1:
I tried it with oapi-codegen.
Here are my temp fixes:
https://github.com/lukacat10/kin-openapi/tree/nullable-fields
https://github.com/lukacat10/oapi-codegen/tree/nullable-fields
Edit 2:
Sort-of-related issues:
https://github.com/oapi-codegen/oapi-codegen/issues/1898
https://github.com/oapi-codegen/oapi-codegen/issues/1883
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating response_format and AssistantsApiResponseFormatOption in the OpenAPI YAML and review how the allOf members combine nullable values. Validate the schema with a strict OpenAPI parser; done means implementations no longer reject this definition for conflicting or ambiguous nullable behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- yaml
- Domain
- api
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100