`oas3-valid-oas-content-example` rule needs to obey readOnly/writeOnly property

[aleung]

Describe the bug

According to https://swagger.io/docs/specification/data-models/data-types/ :

If a readOnly or writeOnly property is included in the required list, required affects just the relevant scope – responses only or requests only. That is, read-only required properties apply to responses only, and write-only required properties – to requests only.

The rule oas3-valid-oas-content-example should not raise error when a readOnly and required property is missing in request example. And also writeOnly property isn't required in response example.

The rule oas3-valid-media-example has the same bug as well.

To Reproduce

1. Given this OpenAPI/AsyncAPI document index.yaml
2. Run this CLI command spectral lint index.yaml
3. See error

16:21 error oas3-valid-oas-content-example Object should have required property self

Expected behavior This error report is not expected.

The self property is readOnly, it isn't required in request.

Environment (remove any that are not applicable):

• Library version: 5.4.0

[zmes50416]

I encountered this issue today and found this. I know this feature(read/write-only) will be removed in OpenAPI v3.1.0. May I ask Is there a plan for fixing it?

[bertramakers]

We also encountered this bug today. AFAIK readOnly and writeOnly are not removed from OpenAPI v3.1.0, it was only adjusted to be compliant with JSON schema which means that it can only be set on properties, not anymore on models. But the bug is also still present for (at least)readOnly + required on properties in request bodies.

/home/runner/work/stoplight-docs-uitpas/stoplight-docs-uitpas/reference/UiTPAS.v2.json
 376:21  error  oas3-valid-media-example  `0` property must have required property `id`  paths./ticket-sales.post.requestBody.content.application/json.examples['Example for one ticket sale'].value[0]
 389:21  error  oas3-valid-media-example  `0` property must have required property `id`  paths./ticket-sales.post.requestBody.content.application/json.examples['Example for multiple ticket sales'].value[0]
 411:21  error  oas3-valid-media-example  `0` property must have required property `id`  paths./ticket-sales.post.requestBody.content.application/json.examples['Example for multiple ticket sales at the same tariff'].value[0]

(However in our case it was the oas3-valid-media-example rule that complained about examples on requests that were missing a required property even though it was read-only.)

[mrjoops]

I encountered this bug yesterday, using Stoplight, prepared a test document and came here to create an issue and found this one. Here is my test, anyway:

openapi: 3.0.0
info:
  title: Test
  version: '1.0'
  contact:
    name: mrjoops
  description: Test API
servers:
  - url: 'http://localhost:3000'
paths:
  /tests:
    post:
      summary: Create test
      operationId: post-tests
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Test'
              examples:
                example-1:
                  value:
                    a: string
      description: Create test
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Test'
            examples:
              example-1:
                value:
                  b: string
        description: ''
      tags:
        - Test
components:
  schemas:
    Test:
      title: Test
      type: object
      properties:
        a:
          type: string
          readOnly: true
        b:
          type: string
          writeOnly: true
      required:
        - a
        - b
tags:
  - name: Test

And here is Spectral output:

 24:25  error  oas3-valid-oas-content-example  `value` property should have required property `b`  paths./tests.post.responses[201].content.application/json.examples.example-1.value
 34:23  error  oas3-valid-oas-content-example  `value` property should have required property `a`  paths./tests.post.requestBody.content.application/json.examples.example-1.value

[mellmann-dtit]

I'm having the exact same problem. Is there any solution to this?

[Kwadz]

Ping @P0lip to find out where the piece of code that needs to be updated is. Could you give some guidance about how to implement a fix and its test? Or it is easier to write a custom ruleset?

[Nezteb]

Hey team! Please add your planning poker estimate with ZenHub @Amjcraft @jasonmgillhub @dotslashderek @kaylachun @cjlanzo

[P0lip]

Ping @P0lip to find out where the piece of code that needs to be updated is. Could you give some guidance about how to implement a fix and its test? Or it is easier to write a custom ruleset?

@Kwadz My apologies, I haven't seen the ping. (Feel free to ping me again next time :))

Here's where the code lives https://github.com/stoplightio/spectral/blob/develop/packages/rulesets/src/oas/functions/oasExample.ts, and the test for the faulty rule is over here https://github.com/stoplightio/spectral/blob/develop/packages/rulesets/src/oas/tests/oas3-valid-media-example.test.ts. Bear in mind that the aforementioned function is used by a few other rules, so other tests might need to be updated accordingly.

[RickKukiela]

Still not fixed 2 years later? This can't possibly be that hard to resolve can it? Ran into this on stoplight.io today.

[mrjoops]

Just tested with Spectral 6.4.2, the issue still exists but the impacted rule has changed, namely oas3-valid-media-example and not oas3-valid-oas-content-example anymore. Here is the error message with the example above:

 24:25  error  oas3-valid-media-example  "value" property must have required property "b"  paths./tests.post.responses[201].content.application/json.examples.example-1.value
 34:23  error  oas3-valid-media-example  "value" property must have required property "a"  paths./tests.post.requestBody.content.application/json.examples.example-1.value

[petkostas]

I can confirm that the issue is still there, it would be nice to fix this as it's creating problems with some of our OAS files.

[LasneF]

Same, confirming the issue is still there in version 6.8.0 is there update ? it s quite annoying as cannot see a simple workaround (i am unable to keep the rule activated but just disabling this use case)

[jasonbstanding]

Still there in 6.10.0 as well.

[jebertz]

Has anyone found a workaround? I don't like totally disabling this rule, but I'm not seeing many other choices without adding a ton of unnecessary definitions