IBM Validator `examples` Keyword as Disallowed in OpenAPI Schema

[m4rcingsxr]

Summary

The IBM OpenAPI Validator reports an error for the examples keyword in the OffsetDateTime schema, stating it is a disallowed keyword. However, the examples keyword is valid in OpenAPI 3.1.0, and its usage in the provided schema appears correct.

Details

When validating the following OpenAPI 3.1.0 schema with the IBM OpenAPI Validator, an error is reported:

Validator Error:

Message: Found disallowed keyword: examples
Rule: ibm-schema-keywords
Path: components.schemas.OffsetDateTime.examples
Line: 33

Full OpenAPI Document:

openapi: 3.1.0
components:
  schemas:
    TestEntity:
      type: object
      required:
      - alias
      - number
      properties:
        createdAt:
          anyOf:
          - $ref: "#/components/schemas/OffsetDateTime"
          - type: "null"
        updatedAt:
          anyOf:
          - $ref: "#/components/schemas/OffsetDateTime"
          - type: "null"
        alias:
          type: string
        number:
          type: string
        id:
          type:
          - integer
          - "null"
          format: int64
          maximum: 9223372036854775807
          minimum: 1
    OffsetDateTime:
      type: string
      format: date-time
      examples:
      - 2022-03-10T12:15:50-04:00
paths:
  /api/v1/tax/test:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TestEntity"
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestEntity"
      tags:
      - Test Controller
info:
  title: API
  version: unspecified

[JakWai01]

We are experiencing the same error. This contributes 16/40 errors to our overall error count 🙂

[pyrooka]

We are aware of this issue, actually a draft PR has been already opened to start supporting the examples keyword. The only thing that we need to do before finalizing it is adding support to this array in our internal tooling - which hasn't been done yet, due to structural changes in the team and lack of time. We'll try to keep this in the top of our backlog and address it soon.