How to fix "path must begin with /" in OpenAPI

Every endpoint path field under the OpenAPI paths object must start with /. The object can also contain x- specification extensions. A key such as users is neither an endpoint path field nor an extension, so it is an unknown field in the Paths Object.

Broken YAML

This complete document omits the leading slash from users:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  users:
    get:
      operationId: listUsers
      responses:
        '200':
          description: Users returned

Why it fails

An OpenAPI path field is a relative path that is appended to a Server Object URL. The field name must begin with /. A validator reads users as an unsupported property, so Redocly reports Property users is not expected here at #/paths/users.

Do not move the server hostname into the path key. Put the base URL in servers and keep only the slash-prefixed path under paths.

Corrected YAML

Add / before the first path segment:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      operationId: listUsers
      responses:
        '200':
          description: Users returned

OpenAPI 3.0 vs 3.1

OpenAPI 3.0 and OpenAPI 3.1 have the same leading-slash rule for endpoint path fields. Both also permit x- specification extensions in the Paths Object. Neither version accepts users, a full URL, or a path that starts with a template variable instead of / as an endpoint path field.

The server and path remain separate in both versions:

servers:
  - url: https://api.example.test
paths:
  /users:
    get: {}

Specification sections: OpenAPI 3.0.4 and OpenAPI 3.1.1.

Validate the fix

Save the complete document as openapi.yaml, then run:

pnpm --package=@redocly/cli@2.53.3 dlx redocly lint openapi.yaml --extends=minimal

The corrected path removes the structural Property users is not expected here error. The minimal preset can still report policy warnings for optional items such as summaries, security, or servers.