When doing linting OpenAPI specification it produces invalid error message

[huksley]

OpenAPI specification checked by using spectral linter.

However due to bugs in spectral linter (see stoplightio/spectral#403) perfectly valid OpenAPI specifications might produce errors if use externally defined JSON Schema type definitions.

This issue can not be fixes until stoplightio/spectral#403 fixed.

[philsturgeon]

I'm not sure I follow. #403 is about invalid schemas, but you are saying that valid OpenAPI can still produce this error message? Got an example OpenAPI file you could give us to reproduce this?

[huksley]

Hi @philsturgeon sorry for slow response.
We have schemas as external files from maas-schemas project
We copy them locally and their are valid according to spectral

>git clone https://github.com/maasglobal/maas-tsp-api
>cd maas-tsp-api
>npm install
>npm run build
>npx spectral lint schemas
Found 54 rules (43 enabled)
No results with a severity of 'error' or higher found!

However, when we run lint against OpenAPI which references schemas, we get error

>NODE_OPTIONS=--max_old_space_size=4096 npx spectral lint specs/booking.yml
OpenAPI 3.x detected
/home/user/src/maas/maas-tsp-api/specs/booking.yml
 396:11  error  oas3-schema  `4` property should have required property `$ref`
✖ 1 problem (1 error, 0 warnings, 0 infos, 0 hints)

It would be great if you can help me understand errors in schemas or OpenAPI so I can fix them.

[philsturgeon]

We've figured out a workaround for making the AJV error output more useful for most use cases: stoplightio/spectral#1071

Please let us know if it's still a problem.

[huksley]

Thanks for taking a look at this!

I've done the following:

• Forked stoplightio/spectral current develop #3041eaa to https://github.com/huksley/spectral
• Build and published as @huksley/spectral 5.3.4

git clone https://github.com/maasglobal/maas-tsp-api
cd maas-tsp-api
npm install
npm remove @stoplight/spectral
npm install --save @huksley/spectral
npm run build
NODE_OPTIONS=--max_old_space_size=4096 npx spectral lint specs/booking.yml

OpenAPI 3.x detected
/Users/user/src/maas-tsp-api/schemas/core/components/travel-mode.json
 1:1  error  oas3-schema  Property `$id` is not expected to be here.

✖ 1 problem (1 error, 0 warnings, 0 infos, 0 hints)

I see no problem with this JSON schema file, see https://github.com/maasglobal/maas-schemas/blob/develop/maas-schemas/schemas/core/components/travel-mode.json

Could I am using it wrong?
Should I wait for release of npm package which includes stoplightio/spectral#1071 ?

[philsturgeon]

It's valid JSON Schema, but it's not valid OpenAPI. If specs/booking.yml is OpenAPI then you cannot $ref to proper JSON Schema files, only OpenAPIish Schema Objects.

This is the bane of my existence, and is being resolved in OpenAPI v3.1. https://www.apisyouwonthate.com/blog/openapi-v31-and-json-schema-2019-09