example-value-or-externalValue should only target OAS3

[nulltoken]

#882 puts under the light a minor issue: value or externalValue only make sense in the context of OAS3, but the rule example-value-or-externalValue apply to both OAS2 and OAS3.

#882 could be merged without incurring any breaking change. However, maybe should we rename the rule to examples-value-or-externalValue (and update the doco accordingly) to make it clear what it actually targets.

[m-mohr]

Does #882 also fix that the rule example-value-or-externalValue does get applied to example(s) properties in actual examples, too? I have an example that contains the properties example(s) and spectral complains about it not having a value or externalValue.
It also seems to get applied to schemas that contain a property example(s), which is not an example itself but defined a field example(s) sent in the response.

Edit:
The JSON path for the examples is $..examples.
After checking the OpenAPI 3 spec, I think the following paths should capture all examples:

• $..content.*.examples
• $.components.examples
• $..parameters.*.examples

Not sure how to combine them, I am new to JSONPath. Thought it would be $..[?(@.content.*),?(@.components),?(@.parameters.*)].examples, but seems to be wrong?!

[nulltoken]

It also seems to get applied to schemas that contain a property example(s), which is not an example itself but defined a field example(s) sent in the response.

@m-mohr Good catch! This path seems indeed too broad.

Not sure how to combine them, I am new to JSONPath.

I wonder if they should be combined. That might hinder the maintainability. #799 looks like bringing a capability that should make that easier.

[m-mohr]

Oh great, didn't know about #799. I started a PR in #899.

[tillig]

There's a bit of a windy path here and I'm curious if the issue I'm seeing is related or something new.

I have an OAS3 doc like this, where the example is on the object in the schema rather than on the request/response. The example-value-or-externalValue in Spectral 5.0.0 catches the example there and complains there's no value... but I think what I have is valid. If I try to put a value property under example then the oas-valid-schema-example rule fails.

I'm thinking the rule should only catch examples (plural) not example (singular).

openapi: 3.0.0
info:
  title: Authentication
  version: 0.0.1
  description: Authentication and credential functionality.
  contact:
    name: My Name
    url: https://my-company.com
servers:
  - url: https://localhost
    description: Local development host
tags:
  - name: users
    description: Management for user accounts and related data.
paths:
  /authentication/v1/users/{id}/password:
    put:
      operationId: put-password-by-id
      summary: Sets the specified user's password.
      description: This operation sets the password for the specified user. The user's current password may be required depending on the user's authorization rights. The new password will be validated against password complexity and history requirements.
      parameters:
        - name: id
          description: The ID of the user for whom the password should be set.
          in: path
          required: true
          schema:
            type: string
          example: "758ce33c-5d7a-4300-bcb9-f26a19a22791"
      requestBody:
        description: An object containing the user's current and desired new passwords.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/passwordChange'
      responses:
        '204':
          description: The password was successfully changed.
      tags:
        - users
components:
  schemas:
    passwordChange:
      type: object
      description: Information required to change a user's password.
      properties:
        current:
          description: The user's current password.
          type: string
        new:
          description: The user's desired new password.
          type: string
      required:
        - new
      example:
        current: "my-current-password"
        new: "my-new-password"

[m-mohr]

This should be fixed with the PRs mentioned above. We just need a new release...