(task description is a WIP)

The newest version of the OAD example raised a lot of new warnings related to examples when checked by the linter, so I investigated how the two rules: wikimedia-requestbody-example-exists and wikimedia-response-example-exists work.

Initial requirements from the list of required fields

Based on my tests, both rules:

• Work correctly when the example is defined as [...].content.[media type].example. (OAD example)
• Work correctly when the example is defined as [...].content.[media type].examples.[example]. (OAD example)
• Result in a false positive (i.e., example doesn't exist) when the example is defined as [...].content.[media type].schema.example, where the schema is included in the requestBody or response definition directly (i.e., not via $ref). (OAD example)

The above scenarios are included in the OAD list of required fields, so the last item is likely a bug.

Potential improvements

In addition to the above, I have also tested other permitted methods of including requestBody and response examples in the OAD. The following scenarios were flagged with warnings by the linter:

• Examples defined in property definitions under schema included directly (OAD example):

application/json:
  schema:
    required:
      - id
      - name
    properties:
      id:
        type: integer
        format: int64
        description: Pet identifier
        example: 32
      name:
        type: string
        description: Pet name
        example: Haru
      tag:
        type: string
        enum:
          - cat
          - dog
          - fish
          - hamster
        description: Pet type or category
        example: cat

• Example defined as part of the schema linked via $ref (OAD example):

(...)

schema:
  $ref: '#/components/schemas/NewPet'

(...)

NewPet:
  type: object
  required:
    - name
  example:
    name: Haru
    tag: cat
  properties:

(...)

• Examples defined in property definitions under schema linked via $ref (OAD example):

schema:
  $ref: '#/components/schemas/NewPet'


(...)


NewPet:
  type: object
  required:
    - name
  properties:
    name:
      type: string
      description: Pet name
      example: Haru
    tag:
      type: string
      enum:
        - cat
        - dog
        - fish
        - hamster
      description: Pet type or category
      example: cat

These scenarios are all correct methods of defining examples for request bodies and responses. It would be great if the linter didn't flag them with warnings.

Proposed task scope

In scope for this task (please feel free to change/split into sub-tasks as needed):

• Fix false positives for schema.example for both requestBody and response.
• Decide whether we want to support all of these scenarios in the linter or prefer to focus on a well-defined subset.
• Investigate the technical feasibility of verifying examples in schemas linked via $ref.