Does not validate exemples correctly with no-invalid-media-type-examples (ref resolving problem)

[Apoorva64]

Describe the bug

When linting with the rule no-invalid-media-type-examples. Redocly throws errors when it shouldn't.
More precisely it dosen't resolve the ref when validating the json schema.

To Reproduce
Steps to reproduce the behavior:

1. Given this redocly.yaml file

extends:
  - recommended
apis:
  main:
    root: ./openapi.yaml

2. And this OpenAPI file(s)
   example.zip

3. Run this command with these arguments... redocly lint

4. See error

[1] paths/owner@{owner}@car/get.yaml:15:17 at #/responses/200/content/application~1json/examples/$ref/value

Example value must conform to the schema: type must be array.

13 |           $ref: ../../components/schemas/Car.yaml
14 |       examples: 
15 |         $ref: ./examples/get/200/_index-json.yaml
16 | '404':
17 |   description: Not Found

referenced from paths/owner@{owner}@car/get.yaml:10:9 at #/responses/200/content/application~1json

Warning was generated by the no-invalid-media-type-examples rule.

Expected behavior
The error should not show as the example is correct. Futhermore if you bundle the api it correctly verifies the example.

OpenAPI description

OpenApi version 3.0.0. It is a simple API made to test this case

Redocly Version(s)

1.6.0

Node.js Version(s)

18

Additional context

[tatomyr]

Hi @Apoorva64! OAS 3.1 defines the examples field as a map of example objects or reference objects, so it's not quite correct to put a $ref there. Although Redocly CLI allows you to use $refs almost everywhere, it is only guaranteed to be correctly linted if it complies with the specification. To check if you're using $refs correctly, you can turn on the spec-strict-refs rule. This is tangentially related to this issue, and you can use the workaround from there.

[Apoorva64]

Hi @tatomyr, thanks for the reply.
I have restructured the example like follows:

.
├── components
│   ├── parameters
│   │   └── path
│   │       └── owner.yaml
│   └── schemas
│       └── Car.yaml
├── openapi.yaml
├── paths
│   └── owner@{owner}@car
│       ├── _index.yaml
│       └── get
│           └── 200
│               ├── examples
│               │   └── laurent-cars.json
│               └── response.yaml
└── redocly.yaml

And i have enabled the "spec-strict-refs" which does not give an error with theses files.
example.zip

But i still get the same validation error on the example

validating /openapi.yaml...
[1] paths/owner@{owner}@car/get/200/response.yaml:12:11 at #/content/application~1json/examples/laurent/value

Example value must conform to the schema: type must be array.

10 | summary: Laurent's Cars
11 | value: 
12 |   $ref: ./examples/laurent-cars.json

referenced from paths/owner@{owner}@car/get/200/response.yaml:4:5 at #/content/application~1json

Warning was generated by the no-invalid-media-type-examples rule.

[Apoorva64]

Hi @tatomyr, thanks for the reply. I have restructured the example like follows:

.
├── components
│   ├── parameters
│   │   └── path
│   │       └── owner.yaml
│   └── schemas
│       └── Car.yaml
├── openapi.yaml
├── paths
│   └── owner@{owner}@car
│       ├── _index.yaml
│       └── get
│           └── 200
│               ├── examples
│               │   └── laurent-cars.json
│               └── response.yaml
└── redocly.yaml

And i have enabled the "spec-strict-refs" which does not give an error with theses files. example.zip

But i still get the same validation error on the example

validating /openapi.yaml...
[1] paths/owner@{owner}@car/get/200/response.yaml:12:11 at #/content/application~1json/examples/laurent/value

Example value must conform to the schema: type must be array.

10 | summary: Laurent's Cars
11 | value: 
12 |   $ref: ./examples/laurent-cars.json

referenced from paths/owner@{owner}@car/get/200/response.yaml:4:5 at #/content/application~1json

Warning was generated by the no-invalid-media-type-examples rule.

After reading the spec https://spec.openapis.org/oas/v3.1.0#fixed-fields-15. I unterstood why it wasn't showing as an error.
$ref: ./examples/laurent-cars.json is the value of the example and the ref in there is not considred as a json ref but as part of the example

[tatomyr]

This is a tricky thing. I see you use $ref inside the value property. Although the spec says that the value property could be of any type, it is unclear if it could be a reference. Anyway, Redocly CLI behaves inconsistently in this case. It should either resolve the $ref when linting or do not resolve when bundling. According to the refs guide, the linter's behaviour is correct, so I'm closing this one and will open a separate issue on the bundle's behaviour.

Thanks for the issue @Apoorva64! I'd suggest you use the following workaround (not using $ref inside example values):

content:
  application/json:
    schema:
      type: array
      items:
        $ref: ../../../../components/schemas/Car.yaml
    examples: 
      laurent:
        $ref: ./examples/laurent.json # This file should contain an object with the `value` property