Running spectral CLI on OAS with external schemas produces incorrect results

[huksley]

Description

When running spectral on OpenAPI 3 specification with externally defined schemas, spectral gives errors for completely valid schemas and OpenAPI Specification.

PLEASE NOTE Running spectral on schemas folder alone gives no errors 🤷‍♂

To Reproduce

1. Checkout this repo with branch https://github.com/huksley/maas-tsp-api/tree/spec-schemas
2. Install packages npm install
3. Build local schemas npm run build
4. Run this CLI command npm run lint
5. See errors:

/home/test/maas-tsp-api/schemas/core/components/bike-station.json
 34:3  error  parser  Duplicate key: required

/home/test/maas-tsp-api/schemas/core/components/state-log.json
 49:7  error  parser  Duplicate key: additionalProperties

/home/test/maas-tsp-api/schemas/core/customer.json
 104:7  error  parser  Duplicate key: required
 105:7  error  parser  Duplicate key: additionalProperties

/home/test/maas-tsp-api/schemas/core/components/fare.json
 31:5  error  parser  Duplicate key: type

/home/test/maas-tsp-api/schemas/core/components/terms.json
 120:11  error  parser  Duplicate key: type

/home/test/maas-tsp-api/schemas/core/modes/MODE_BICYCLE.json
 23:9  error  parser  Duplicate key: type

/home/test/maas-tsp-api/schemas/core/modes/MODE_SHARED_BICYCLE.json
 11:9  error  parser  Duplicate key: type

/home/test/maas-tsp-api/specs/booking.yml
 251:15  error  oas3-schema  /paths//bookings/options/get/responses/200 should have required property '$ref'

Example case schemas/core/components/bike-station.json breakdown

For following schema (when referenced from OAS):

{
  "$id": "http://maasglobal.com/core/components/bike-station.json",
  "description": "MaaS bike station schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "location": {
      "$ref": "../../../schemas/core/components/units-geo.json#/definitions/location"
    },
    "slots": {
      "type": "object",
      "properties": {
        "total": {
          "type": "number",
          "minimum": 0
        },
        "empty": {
          "type": "number",
          "minimum": 0
        },
        "bikes": {
          "type": "number",
          "minimum": 0
        }
      },
      "required": ["total", "empty", "bikes"]
    }
  },
  "required": ["id", "name", "location"]
}

produces following error:

 34:3  error  parser  Duplicate key: required

Expected behavior These errors should not be reported.

Environment (remove any that are not applicable):

• Library version: 4.2.0
• OS: MacOS 10.14.6
• Node: 12.11.1

[philsturgeon]

Hey I can’t find the specs you’re talking about, is it the default branch you linked to, develop, or somewhere else? It’s hard to tel what’s going on from just the one file.

[huksley]

@philsturgeon Hi, yes you need specific branch and you need first run npm run build to copy schemas locally

I´ve updated repo and issue description, sorry for not being clear on this

[huksley]

@philsturgeon Any updates on this? Could I be of an assistance?

[philsturgeon]

Sorry I'm out of brain space to look into this, but hopefully one of the team will be with you soon!

[P0lip]

Hey, my sincere apologies for dropping a ball on this one. I can confirm it's an issue and will fix it very soon. Thanks for the report.

[P0lip]

@huksley The issue has been fixed and will be released in the next version of Spectral. In the meantime, you can mitigate the issue by setting a resolution in your package.json.

"resolutions": {
  "@stoplight/json": "^3.2.2"
}

Make sure to reinstall dependencies once resolution is set. If you don't use Yarn, you may need to use npm-force-resolutions. That said, the release is around, so you can just wait a tiny bit longer :slightly_smiling_face:

Last but not least, make sure to remove the actual duplicate property in schemas/core/error.json :wink:

[huksley]

Thanks @P0lip!

I done the changes specified and Schema errors are gone!!! However it still complains about oas3-schema error, is there something wrong with the specification?

It is in this branch/PR https://github.com/maasglobal/maas-tsp-api/pull/52

> maas-tsp-api@0.0.3 lint-spec /Users/user/src/maas-tsp-api
> node utils/adopt-schemas.js && cross-env NODE_OPTIONS=--max_old_space_size=4096 spectral lint specs/booking.yml

OpenAPI 3.x detected

/Users/user/src/maas-tsp-api/specs/booking.yml
 319:11  error  oas3-schema  /paths//bookings/options/get/parameters/4 should have required property '$ref'

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

I took a look at parameters, they are all have defined type via schema/$ref

If I remove the mode parameter, which declared like this (and references this):

        - name: mode
          description: 'Transfer mode'
          in: query
          required: false
          schema:
            $ref: ../schemas/core/components/travel-mode.json

it starts to complain with this:

/Users/user/src/maas-tsp-api/specs/booking.yml
 337:15  error  oas3-schema  /paths//bookings/options/get/responses/200 should have required property '$ref'

which is again looks fine to me 🤔

      responses:
        '200':
          x-summary: Array of options
          description: |
            Available transport options matching the given query parameters. If no transport options are available; an empty array is returned.
          content:
            application/json:
              schema:
                $ref: ../schemas/tsp/booking-options-list/response.json
              examples:
                Taxi:
                  summary: Taxi
                  externalValue: '../examples/taxi/booking-options-response.json'

Kind of related to #403 🤷‍♂

[P0lip]

@huksley Yeah, we know oas3-schema tends to produce weird errors. Feel free to post your issue in that ticket!