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 238 forks source link

Missing spec validation for schema types (that redocly has) #2465

Closed razvanphp closed 5 months ago

razvanphp commented 1 year ago

User story. As a user switching from redocly I noticed in our CI pipeline that some errors are not displayed anymore, here is a test yaml:

openapi: 3.1.0
info:
  license: 
    name: "Apache 2.0"
    url: "https://www.apache.org/licenses/LICENSE-2.0.html"
  title: our-api
  version: '1.0'
  description: This is a base model on how you can communicate with our Portal
  contact:
    email: hell0@vamp1rebyte.ro
servers:
  - url: 'http://localhost:8337'
security:
  - BasicAuth: []
paths:
  /v1/api/config:
    parameters:
      - schema:
          type: integers
        name: id
        in: query
        required: false
        description: Id of an existing config.
      - schema:
          typ: string
        name: user_id
        in: query
        required: false
        description: Id of an existing user.
    get:
      summary: Get User Info by User ID
      operationId: get-users-settings
      description: Retrieve the information of the user settings with the matching user ID.
      tags:
        - get-user-config
      responses:
        '200':
          description: Settings for User Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    type: string,
                  value:
                    type: string
                required:
                  - key
                  - value
      parameters:
        - schema:
            type: array
          in: query
          name: prefix
          required: false
          description: Id of an existing type.
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

This is the output of spectral (with extends: 'spectral:oas'): No results with a severity of 'error' found!

but redocly shows obvious errors:

No configurations were provided -- using built in recommended configuration by default.

validating test.yaml...
[1] test.yaml:19:17 at #/paths/~1v1~1api~1config/parameters/0/schema/type

`type` can be one of the following only: "object", "array", "string", "number", "integer", "boolean", "null".

Did you mean: integer ?

17 | parameters:
18 |   - schema:
19 |       type: integers
20 |     name: id
21 |     in: query

Error was generated by the spec rule.

[2] test.yaml:25:11 at #/paths/~1v1~1api~1config/parameters/1/schema/typ

Property `typ` is not expected here.

Did you mean:
  - type
  - $id
  - id
  - not
  - if

23 |   description: Id of an existing config.
24 | - schema:
25 |     typ: string
26 |   name: user_id
27 |   in: query

Error was generated by the spec rule.

[3] test.yaml:45:27 at #/paths/~1v1~1api~1config/get/responses/200/content/application~1json/schema/properties/key/type

`type` can be one of the following only: "object", "array", "string", "number", "integer", "boolean", "null".

Did you mean: string ?

43 | properties:
44 |   key:
45 |     type: string,
46 |   value:
47 |     type: string

Error was generated by the spec rule.

[4] test.yaml:36:7 at #/paths/~1v1~1api~1config/get/responses

Operation must have at least one `4XX` response.

34 | tags:
35 |   - get-user-config
36 | responses:
37 |   '200':
38 |     description: Settings for User Found

Warning was generated by the operation-4xx-response rule.

test.yaml: validated in 13ms

❌ Validation failed with 3 errors and 1 warning.

Is your feature request related to a problem? It might be; not sure why redocly uses more rules by default compared to spectral, but I'm inclined to think we should have those included even in the recommended ruleset.

Describe the solution you'd like Have the schema type validated by oas spec rules similar to redocly.

Additional context

% redocly --version
1.0.0-beta.125
% spectral --version
6.6.0

Thank you in advance! R

stoplight-bot commented 4 months ago

:tada: This issue has been resolved in version 1.19.0 :tada:

The release is available on @stoplight/spectral-rulesets-1.19.0

Your semantic-release bot :package::rocket:

razvanphp commented 4 months ago

Thank you @mnaumanali94! How can I check from the CI what version of the rulesets I have installed?

I currently only have this:

$ spectral --version
6.11.1
razvanphp commented 4 months ago

Also, I just checked, and I think there is one more edge case with null and 'null' in the type that redocly catches:

[1] models/Config.yaml:18:13 at #/allOf/0/properties/user_id/type/1
`type` can be one of the following only: "object", "array", "string", "number", "integer", "boolean", "null".
Did you mean:
  - object
  - array
  - string
  - number
  - integer
16 |   type:
17 |     - integer
18 |     - null
19 | car_id:
20 |   type:
Error was generated by the spec rule.
[2] models/Config.yaml:22:13 at #/allOf/0/properties/car_id/type/1
`type` can be one of the following only: "object", "array", "string", "number", "integer", "boolean", "null".
Did you mean:
  - object
  - array
  - string
  - number
  - integer
20 |       type:
21 |         - integer
22 |         - null

Schema looks like this:

allOf:
  - type: object
    properties:
      car:
        $ref: ./Car.yaml
      user:
        type:
          - object
          - null
        $ref: ./User.yaml
      user_id:
        type:
          - integer
          - null
      car_id:
        type:
          - integer
          - null

See spec: https://json-schema.org/understanding-json-schema/reference/null