Parameter with required and example fails valid-example rule

I’m submitting a…

• bug report

What is the current behavior?

If you have a parameter that has required: true and an example, the valid-example rule fails. See “Other information” for details.

What is the expected behavior?

The valid-example rule executes successfully for a valid parameter example as it understands that required is not a list for parameters but a boolean.

What is the motivation / use case for changing the behavior?

The valid-example rule is very helpful and it should work for parameters

Please tell us about your environment:

$ spectral --version
@stoplight/spectral/3.0.0 linux-x64 node-v12.2.0

Other information

Given this schema

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  description: Swagger Petstore
  license:
    name: MIT
  contact:
    name: Test
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      description: Get a pet
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
          example: "1234567890"
      responses:
        '200':
          description: Expected response to a valid request

Running spectral lint myschema.yml results in:

Adding OpenAPI 3.x functions
OpenAPI 3.x detected
Encountered error when running rule 'valid-example' on node at path '$,paths,/pets/{petId},get,parameters,0':
Error: schema is invalid: data/required should be array
No errors or warnings found!

As an aside, an “error” was found but yet spectral says “No errors or warnings found!” and the return code is 0. Why the discrepancy?

Thanks a lot. Let me know if I can help!

[chris-miaskowski]

Hi @cbautista1002, @philsturgeon.

Great conversation so far and thanks for reporting! We’ve made some progress on this but aren’t quite done yet - bear with us!

Just wanted to add my two cents here.

The OAS documentation says

The example SHOULD match the specified schema and encoding properties if present.

Note it says “SHOULD” not “MUST”. This means that the final solution we’ll present should imo return a warning (vs error) if there is a mismatch.

@cbautista1002 FYI you can still use ‘required’ if you put the example inside the schema. The following example works:

parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
            example: "1234567890"

[philsturgeon]

If at all possible it should be done for v4.0 but it could be 4.0.1. This rule is broken in certain situations, but it’s not effecting too many people, and can be skipped as a workaround, so it’s not a blocker.

– Phil Sturgeon @philsturgeon

On Jul 6, 2019, at 20:32, Brian Rock [e-mail] wrote:

@philsturgeon I have this tagged for next sprint, but if its not needed fro v4.0 release, lets leave it on the backlog.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.