openai / openai/openai-openapi

OpenAPI spec is a mix of version 3.0.x and version 3.1.x

Open
#452 1 comment 10 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug specification
Dominant language
No language data
Stars
2.5k
Forks
527
Avg merge
1h 46m
Merged PRs (30d)
2

Description

Summary

Your openapi spec declares itself as version 3.0.0, but the document uses a mixture of 3.0.0 and 3.1.0 features, causing validation failures.

Detail

I cannot get OpenAI's latest OpenAPI spec to validate. I've had this for a while, but didn't dig into until today because I received a bug report on it. Specifically, this commit:

commit 498c71ddf6f1c45b983f972ccabca795da211a3e (HEAD -> master, origin/master, origin/HEAD)
Author: Kevin Whinnery kwhinnery@openai.com
Date: Tue Apr 29 15:05:57 2025 -0500

Update openapi.yaml

At the top of your OpenAPI spec, you have the following:

openapi: 3.0.0

There are multiple errors when I attempt to load it. For example:

/components/schemas/VectorStoreFileAttributes: /oneOf/0 Properties not allowed: propertyNames.

OpenAPI 3.0.x uses an extended subset of JSON Schema Draft 5 (which is just a cleanup of Draft 4), while version 3.1.x uses JSON Schema Draft 6. From the docs:

OpenAPI v3.0 was based on JSON Schema Draft 05, and JSON Schema has gone through a few drafts since then: Draft 06, Draft 07, and Draft 2019-09. Now thanks to feedback gathered from users and tooling maintainers during the v3.1.0 release candidates, one more small draft was released: Draft 2020-12. This should be the last one for a while and no major changes are planned by the JSON Schema crew, so if all goes well a final release is on the horizon, to avoid any further discrepancies.

So for the propertyNames keyword referenced above, that was introduced in version JSON Schema Draft 6.

Thus, you use propertyNames from OpenAPI v3.1.0, but declare that you're using OpenAPI v3.0.0, causing validation to fail.

Unfortunately, switching from openapi: 3.0.0 to openapi: 3.1.0 may not be a quick fix. Again, from the changes between Draft 4 and Draft 6:

"exclusiveMinimum" and "exclusiveMaximum" changed from a boolean to a number to be consistent with the principle of keyword independence wherever one of these would be true before, change the value to the corresponding "minimum" or "maximum" value and remove the "minimum"/"maximum" keyword

So when we see things like this:

              oneOf:
                - type: string
                  enum:
                    - auto
                  x-stainless-const: true
                - type: number
                  minimum: 0
                  exclusiveMinimum: true
              default: auto

It should now be this:

              oneOf:
                - type: string
                  enum:
                    - auto
                  x-stainless-const: true
                - type: number
                  exclusiveMinimum: 0
              default: auto

Below is my full list of validation errors. I do not claim the list is fully correct because when I manually edit the spec to openapi: 3.1.0, my validation errors go away, despite some of the spec apparently being incorrect. I have not looked into this further.

Invalid schema: file://share/openapi.yaml has the following errors:
/components/schemas/ApproximateLocation/$ref: /oneOf/1 Missing property.
/components/schemas/ApproximateLocation/properties/city/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/ApproximateLocation/properties/city/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/ApproximateLocation/properties/city/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/ApproximateLocation/properties/country/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/ApproximateLocation/properties/country/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/ApproximateLocation/properties/country/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/ApproximateLocation/properties/region/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/ApproximateLocation/properties/region/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/ApproximateLocation/properties/region/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/ApproximateLocation/properties/timezone/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/ApproximateLocation/properties/timezone/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/ApproximateLocation/properties/timezone/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/CompoundFilter: /oneOf/0 Properties not allowed: $recursiveAnchor.
/components/schemas/CompoundFilter/$ref: /oneOf/1 Missing property.
/components/schemas/ComputerCallOutputItemParam/$ref: /oneOf/1 Missing property.
/components/schemas/ComputerCallOutputItemParam/properties/acknowledged_safety_checks/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/ComputerCallOutputItemParam/properties/acknowledged_safety_checks/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/ComputerCallOutputItemParam/properties/acknowledged_safety_checks/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/ComputerCallOutputItemParam/properties/id/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/ComputerCallOutputItemParam/properties/id/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/ComputerCallOutputItemParam/properties/id/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/ComputerCallOutputItemParam/properties/status/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/ComputerCallOutputItemParam/properties/status/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/ComputerCallOutputItemParam/properties/status/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/ComputerCallSafetyCheckParam/$ref: /oneOf/1 Missing property.
/components/schemas/ComputerCallSafetyCheckParam/properties/code/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/ComputerCallSafetyCheckParam/properties/code/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/ComputerCallSafetyCheckParam/properties/code/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/ComputerCallSafetyCheckParam/properties/message/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/ComputerCallSafetyCheckParam/properties/message/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/ComputerCallSafetyCheckParam/properties/message/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/CreateTranscriptionResponseJson/$ref: /oneOf/1 Missing property.
/components/schemas/CreateTranscriptionResponseJson/properties/logprobs: /oneOf/0/oneOf/0 Properties not allowed: optional.
/components/schemas/CreateTranscriptionResponseJson/properties/logprobs/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/EvalScoreModelGrader/$ref: /oneOf/1 Missing property.
/components/schemas/EvalScoreModelGrader/properties/range/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/EvalScoreModelGrader/properties/range/items: /oneOf/0/oneOf/0/oneOf/0 Properties not allowed: max_items, min_items.
/components/schemas/EvalScoreModelGrader/properties/range/items/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/FileSearchTool/$ref: /oneOf/1 Missing property.
/components/schemas/FileSearchTool/properties/filters/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/FileSearchTool/properties/filters/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/FileSearchTool/properties/filters/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/FunctionCallOutputItemParam/$ref: /oneOf/1 Missing property.
/components/schemas/FunctionCallOutputItemParam/properties/id/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/FunctionCallOutputItemParam/properties/id/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/FunctionCallOutputItemParam/properties/id/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/FunctionCallOutputItemParam/properties/status/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/FunctionCallOutputItemParam/properties/status/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/FunctionCallOutputItemParam/properties/status/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/FunctionTool/$ref: /oneOf/1 Missing property.
/components/schemas/FunctionTool/properties/description/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/FunctionTool/properties/description/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/FunctionTool/properties/description/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/FunctionTool/properties/parameters/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/FunctionTool/properties/parameters/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/FunctionTool/properties/parameters/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/FunctionTool/properties/strict/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/FunctionTool/properties/strict/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/FunctionTool/properties/strict/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/InputFileContent/$ref: /oneOf/1 Missing property.
/components/schemas/InputFileContent/properties/file_id/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/InputFileContent/properties/file_id/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/InputFileContent/properties/file_id/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/InputImageContent/$ref: /oneOf/1 Missing property.
/components/schemas/InputImageContent/properties/file_id/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/InputImageContent/properties/file_id/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/InputImageContent/properties/file_id/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/InputImageContent/properties/image_url/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/InputImageContent/properties/image_url/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/InputImageContent/properties/image_url/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/ItemReferenceParam/$ref: /oneOf/1 Missing property.
/components/schemas/ItemReferenceParam/properties/type/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/ItemReferenceParam/properties/type/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/ItemReferenceParam/properties/type/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string.
/components/schemas/RankingOptions/$ref: /oneOf/1 Missing property.
/components/schemas/RankingOptions/required: /oneOf/0 Not enough items: 0/1.
/components/schemas/VectorStoreFileAttributes: /oneOf/0 Properties not allowed: propertyNames.
/components/schemas/VectorStoreFileAttributes/$ref: /oneOf/1 Missing property.
/components/schemas/WebSearchPreviewTool/$ref: /oneOf/1 Missing property.
/components/schemas/WebSearchPreviewTool/properties/user_location/$ref: /oneOf/0/oneOf/1 Missing property.
/components/schemas/WebSearchPreviewTool/properties/user_location/anyOf/1/$ref: /oneOf/0/oneOf/0/oneOf/1 Missing property.
/components/schemas/WebSearchPreviewTool/properties/user_location/anyOf/1/type: /oneOf/0/oneOf/0/oneOf/0 Not in enum list: array, boolean, integer, number, object, string. at /Users/ovid/perl5/perlbrew/perls/perl-5.40.0/lib/site_perl/5.40.0/OpenAPI/Client.pm line 66.

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 with openapi.yaml and compare its declared OpenAPI version with the schema keywords and constructs listed in the issue. Validate the document against the intended version, address the reported compatibility errors, and consider the work done when the specification validates without the version-mismatch failures.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 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.