maasglobal/maas-tsp-api

When doing linting OpenAPI specification it produces invalid error message

Opened this issue · 5 comments

huksley commented

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 commented

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 commented

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 commented

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 commented

Thanks for taking a look at this!

I've done the following:

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 commented

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