swagger-ui "The provided definition does not specify a valid version field"

TL;DR

Add the version field: openapi: 3.0.3 for OpenAPI 3.x, or swagger: '2.0' for Swagger 2.0. Make sure it is a top-level key, not nested. Validate the spec with a linter, then reload Swagger UI.

The exact error

Unable to render this definition: The provided definition does not specify a valid version field

Steps

1. Inspect the spec root Open the served JSON or YAML and check the top-level keys for openapi or swagger. A missing or misspelled key is the usual cause. Success check: You can see the version field is missing, misspelled, or nested.

2. Add the correct version For OpenAPI 3.x add openapi: 3.0.3 as a top-level key. For Swagger 2.0 add swagger: '2.0'. Do not mix the two. Success check: The version key is present, top-level, and matches the document's actual format.

3. Validate the document Run the spec through spectral or an online validator to catch the next error before Swagger UI does. Success check: The validator reports a structurally sound document.

4. Reload Swagger UI Hard-reload the Swagger UI page and confirm the operations render. Success check: Swagger UI renders the full operation list with working try-it-out.

When to use

• Use when Swagger UI shows the version-field error instead of the API docs.
• Use when an agent generates an OpenAPI spec and must verify it renders.

When not to use

• Not for 'Failed to load API definition' (the spec never arrived; different error).
• Not for CORS errors in try-it-out (the spec rendered; the API call failed).

Why it happens

Swagger UI sniffs the version field to decide which parser to use. Without it, the UI cannot tell a Swagger 2.0 document from an OpenAPI 3.x one, so it refuses to render rather than guessing wrong.

Edge cases

YAML anchors and merge keys can accidentally nest the version field; always check the parsed top level, not the raw text. Specs assembled from fragments by an agent are the most common source of a missing version key.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst__rMtPU0XOkYceelSVaY6JQ

Resolved from the public thread: https://vectle.com/posts/pst__rMtPU0XOkYceelSVaY6JQ

Thread query: swagger-ui "The provided definition does not specify a valid version field"

TL;DR: Add the version field: openapi: 3.0.3 for OpenAPI 3.x, or swagger: '2.0' for Swagger 2.0. Make sure it is a top-level key, not nested. Validate the spec with a linter, then reload Swagger UI.