spectral: Invalid schema causes "should have required property '$ref'" error

Describe the bug When an OpenAPI v3 Response Object contains a schema which has invalid schemas, an error is thrown saying: should have a required $ref property.

This is probably coming from better-ajv-errors, which is deduping errors which are saying “should be a valid sub schema, or should be a $ref” and its just showing the $ref bit.

To Reproduce

Given this OpenAPI document

openapi: 3.0.1
info:
  title: Example $ref error
  version: 1.0.0
paths:
  /user:
    get:
      operationId: getUser
      responses:
        "200":
          description: An Example
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id: 12345

Run this CLI command spectral lint openapi.yml
See error

Expected behavior

Show a more appropriate validation error. In this instance, other validators return this error:

Structural error at paths./user.get.responses.200.content.application/json.schema.properties.user_id should be object

Environment:

Library version: 4.0.1
OS: Mac OS 10.14.5

About this issue

Original URL
State: closed
Created 5 years ago
Reactions: 19
Comments: 24 (15 by maintainers)

Most upvoted comments

This also happens for path params:

  '/modules/{module_id}/sections':
    parameters:
      - type: string
        name: module_id
        in: path
        required: true
        schema:
          type: string
        description: Module ID
    get:

/paths//modules/{module_id}/sections/parameters/0 should have required property '$ref'

moltar on Dec 20, 2019

We’ve not forgotten about this issue. We are solving problems a few levels down, with supporting multiple JSON Schema and OpenAPI dialects and vocabularies, which will get us to reevaluate some of the dependencies we’ve built features like schema-based validation on top of. If we’re continuing to use schema-based validation it’ll likely be switching to DJV, and we need to work on some functionality there to make it support better errors. Otherwise maybe Sway, but we’ll have to see what happens as this work progresses.

For now invalid schema messages are a bit funky and I’m sorry about that. We’ll get there.

philsturgeon on Mar 23, 2020

For me it was a UI (studio) based error. I was using UI to generate “model” specifications but Studio was creating false yaml.

For example for a “model” with a “nullable” property the UI outputs something like this:

properties:
  id:
    type:
     - string
     - null

However OAS3 specification tells that it should be like below:

properties:
  id:
    type: string
    nullable: true

After I fixed this on the “code” view. The errors disappeared. So my assumption is that if you trust the output of Studio for OAS3 you may fall into such issues and the linter can get confused. It is not a big issue but the message is misleading for sure.

I hope this info will help you to fix your issues.

Cheers!

canberkol on Jan 27, 2020

Thank you for sharing the example. You are right that this will cause the validator library we use to vomit up the $ref error, and we are working on switching out to a more useful validator. AJV is not the best for error messages sadly. You either get duplicates, or you get this misleading one.

All that said, the conclusion that the GUI cannot be trusted is not entirely accurate. Allowing multiple types in OpenAPI is a known issue, but you would not believe how many people do this intentionally and expect it to work. Most people are not aware of the JSON Schema !== OpenAPI Divergence, see JSON Schema allowing multiple types, then because people do it so much various tools have decided to add support for it… 🤕

We’re working on getting “multiple flavour” support into Stoplight to support multiple drafts of JSON Schema and OpenAPI v2/v3/v3.1 more accurately, but this is the biggest issue you’re likely to notice using the GUI. https://github.com/stoplightio/studio/issues/190 This one will be fixed, but just be aware of it and keep on using the GUI to your hearts content.

philsturgeon on Jan 30, 2020

@m-denton this is being worked on, it has a very high priority, but so do a few other things. We’ll get to it. In the meantime just keep in mind that it means “something nearby is invalid” and do you best to fix it by eye. Then soon, after an update, it’ll just start being awesome again and you won’t have to eyeball it anymore. 😄

philsturgeon on Jan 21, 2020

https://github.com/stoplightio/spectral/pull/1071 should address most of the issues that have been reported here.

P0lip on Apr 7, 2020