`example-value-or-externalValue` should only target OAS3

#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]

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

[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"