Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

List the actual unevaluatedProperties when logging oas3-valid-schema-example error/warning #2750

Open
DavidBiesack opened this issue Dec 2, 2024 · 0 comments

Comments

@DavidBiesack
Copy link

User story.

As a API designer, I can use Spectral to validate examples and clearly see which unevaluated properties exist, so that I can update my examples to be correct

Is your feature request related to a problem?

Yes. When Spectral checks examples against a schema, and the schema has

unevaluatedProperties: false

and the schema example or examples contains unexpected properties,
Spectral just shows:

 error  oas3-valid-schema-example  "example" property must not have unevaluated properties   

Describe the solution you'd like
When there are unevaluated properties, list which properties are not evaluated.

Additional context
Here is a sample openapi.yaml source file:

openapi: 3.1.0

info:
  title: Unevaluated Property
  description: OpenAPIwith invalid schema example (unevaluated property)
  version: "1.0.0"
  contact: {}
tags:
  - name: Example
    description: Example
servers:
  - url: https://www.example.com/api
paths:

  /present:
    get:
      summary: Get a present
      description: Get a present
      operationId: getAPresent
      tags:
        - Example
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/present'
        4XX:
          description: OK
          content:
            application/json:
              schema:
                type: object

components:
  schemas:
    present:
      title: A present
      type: object
      unevaluatedProperties: false
      properties:
        openedOn:
          description: The date the present was opened.
          type: string
          format: date
          minLength: 10
          maxLength: 10
        receivedOn:
          description: The date the present was received.
          type: string
          format: date
          minLength: 10
          maxLength: 10
      example:
        recievedOn: 2024-12-25
        openedOn: 2024-12-25

running

$ spectral lint -r ~/config/oas-spectral-ruleset.yaml openapi.yaml

 55:15  error  oas3-valid-schema-example  "example" property must not have unevaluated properties  components.schemas.present.example

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

This only tells me the example must not have unevaluated properties, but this is not specific enough.
In this case, it is not to hard to deduce the problem (receivedOn was misspelled as recievedOn)
but in real world examples where a schema may have many properties (especially when
composing schemas with allOf), it is not immediately obvious which properties
are not defined with a properties constraint. I'd like to see the violations listed, such as:

55:15  error  oas3-valid-schema-example  "example" property must not have unevaluated properties: 
components.schemas.present.example
- recievedOn is not evaluated

Note: My ruleset file contains:

extends:
  - spectral:oas
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant