openai / openai/openai-openapi

Some implementations cant merge schemas defined in `allOf` property.

Open
#419 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

specification
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.