search

stoplightio / spectral

A flexible JSON/YAML linter for creating automated style guides, with baked in support for OpenAPI (v3.1, v3.0, and v2.0), Arazzo v1.0, as well as AsyncAPI v2.x.
https://stoplight.io/spectral
Apache License 2.0
2.5k stars 235 forks source link

Misleading error for invalid header object #1715

Open MarcusAckermann opened 3 years ago

MarcusAckermann commented 3 years ago

To Reproduce

  1. Given the attached OpenAPI/AsyncAPI document
  2. Run this CLI command 'spectral lint openapi.json'
  3. I get ' 38:18 error oas3-schema Property schema is not expected to be here. components.headers.Cache-Control.schema'

Expected behavior According to https://swagger.io/specification/#header-object the property 'schema' is allowed in a header declaration. There should be no error regarding rule oas3-schema.

openapi.zip

P0lip commented 2 years ago

Hey, first of all, my apologies for a delayed response. In our case, the way you reference that header object is invalid. One should do

     "headers": {
         "Cache-Control"  : {
                "$ref": "#/components/headers/Cache-Control"
          }
    }

I do agree however that the error could be more meaningful.

jstockdi-marstone commented 2 years ago

I came across this error and it stumped me for a bit. For anyone else who has the same issue:

Change:

            "headers": {
              "Cache-Control" :{
                "schema": {
                  "$ref": "#/components/headers/Cache-Control"
                }
              }
            }

To:

            "headers": {
              "Cache-Control" :{
                "$ref": "#/components/headers/Cache-Control"
              }
            }

It's easy to mix up, as schema often has an attribute $ref in other use cases. If the component has schema in it, then the object referencing it should not refer to it from a schema attribute. I think... if anyone posts additional info here, that'd help me out.

NOTE: only happens for version 3.0.1, it works fine in 3.1.0.