False positive (lint and resolve) with referenced ($ref) examples

[checkin247]

Detailed description

Linting and resolving the specifications works great untill you come to examples. If an example has a property name of type (1st level, not nested), it throws a lint error: `Type "Italian" is not a valid type". Bug or question or enhancement???. Is it possible (how) to define a custom rule which allows examples to have property names used by the openapi specifications without throwing an error? or, Would there be a better approach (see context). or, Is it a bug (my guess).

There is a "workaround" by not separating examples which have property names conflicting with openapi specs.

Context

Consider a restaurant api. The api has a collection of restaurants, a restaurant has a property name of type. A valid type could be, Italian, Chinese etc.

title: Restaurant
type: object
tags:
  - Restaurants
properties:
  type:
    type: string

So far, so good. No problems with linting (yet).

Now consider we want to add examples for mocking.

title: Restaurant
type: object
tags:
  - Restaurants
properties:
  type:
    type: string
examples:
  example-1:
    type: Italian

Still no problems with linting (yet).

My prefence is to keep the examples in separate files. I would abstract it as far as possible, in order to be able to reuese examples. Therefore I would have an example which may look like:

type: Italian

which is stored in a separate file. Note: this is not a "model" it is an example. The example would be referenced, ie. like this:

title: Restaurant
type: object
tags:
  - Restaurants
properties:
  type:
    type: string
examples:
  example-1:
    $ref: ./examples/restaurants/one.yaml

This is where the linting problem starts. It "thinks" that the type must be an openapi type, like object, string ....

Possible implementation

Examples should be linted if they match the documentation, but they are NOT openapi specifications and should not be treated as such (not linted).

Your environment

Windows 10

[negebauer]

I'm having this same problem, my solution was to use the value key for examples.

# Main file
components:
  examples:
    $ref: ./examples/_index.yml

# ./examples/_index.yml
SomeExample:
  value:
    $ref: ./SomeExample.yml

# ./examples/SomeExample.yml
id :1
name: Some name
otherKey: other value