Which top-level OpenAPI fields are required?

An OpenAPI document requires the version field, an info object, and paths or the version-appropriate equivalent structure.

Some validators accept an empty paths object, but it describes no callable operations and is rarely useful.

Why can valid YAML still fail OpenAPI validation?

YAML syntax validity does not guarantee that the parsed object follows the OpenAPI schema.

OpenAPI "Missing Required Field" Errors, Explained

An OpenAPI v3 document is still just YAML or JSON underneath — it can be syntactically valid and still fail spec validation because a handful of top-level fields are mandatory.

The required root fields

openapi — a version string (e.g. 3.0.0) declaring which OpenAPI Specification version the document follows. Tooling uses this to decide how to parse everything else.
info.title and info.version — identify the API itself. These aren't cosmetic: code generators and documentation tools use them to name the generated client/docs.
paths — the actual API surface. A spec with no paths (or an empty object) describes an API with no endpoints, which is rarely intentional.

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

Why each path also needs an HTTP method

A path entry with no HTTP method (get/post/put/delete/patch/options/head) underneath it describes a URL with nothing you can actually call — most validators flag this too, since it's almost always a copy-paste mistake or an incomplete draft.

What this doesn't catch

Checking these root fields is a base-level sanity check, not full schema validation — it won't catch an invalid $ref, a malformed request/response schema, or type errors inside your data models. For that level of detail you need a full OpenAPI schema validator (e.g. Swagger Editor or the openapi npm package's validator); Cryonel's OpenAPI Spec Validator is intentionally a fast first-pass check, not a replacement for one.

Use the validator path to fix the right object

Read the complete error path. A message about a missing required field might refer to a schema keyword inside components, not a missing root property. Validate the fully bundled document if your source uses external $ref files; a partial fragment can look incomplete even when the assembled contract is valid.

After adding the field, run both structural validation and a small toolchain smoke test. Documentation renderers, code generators, gateways, and diff tools exercise different parts of the specification. Keep a minimal valid contract in the repository so CI can distinguish parser failures from incomplete generated output.

Frequently Asked Questions

Which root fields are required?

The version, info, and operation structure required by the chosen OpenAPI version must be present.

Can `paths` be empty?

Some validators allow it, but the document then describes no callable operations.

Why can valid YAML still fail?

YAML syntax validity does not prove that the resulting object follows the OpenAPI schema.