Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
aleung opened this issue Jul 8, 2020 · 14 comments · Fixed by #2573
Closed

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

aleung opened this issue Jul 8, 2020 · 14 comments · Fixed by #2573
Labels
help wanted Extra attention is needed OpenAPI Issues related to the OpenAPI ruleset p/documented released t/bug Something isn't working team/dnc Team: Dazed and Confused

Comments

@aleung
Copy link

aleung commented Jul 8, 2020

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
@aleung aleung added the t/bug Something isn't working label Jul 8, 2020
@P0lip P0lip added the OpenAPI Issues related to the OpenAPI ruleset label Sep 30, 2020
@zmes50416
Copy link

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
Copy link

bertramakers commented Aug 19, 2021

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
Copy link

mrjoops commented Aug 19, 2021

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

@philsturgeon philsturgeon added the help wanted Extra attention is needed label Oct 1, 2021
@mellmann-dtit
Copy link

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

@Kwadz
Copy link

Kwadz commented Mar 18, 2022

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
Copy link

Nezteb commented May 3, 2022

@P0lip
Copy link
Contributor

P0lip commented May 3, 2022

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
Copy link

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
Copy link

mrjoops commented Jul 29, 2022

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
Copy link

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
Copy link

LasneF commented Jun 20, 2023

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
Copy link

Still there in 6.10.0 as well.

@jebertz
Copy link

jebertz commented Sep 21, 2023

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

@stoplight-bot
Copy link
Collaborator

🎉 This issue has been resolved in version 1.19.0 🎉

The release is available on @stoplight/spectral-rulesets-1.19.0

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted Extra attention is needed OpenAPI Issues related to the OpenAPI ruleset p/documented released t/bug Something isn't working team/dnc Team: Dazed and Confused
Projects
None yet
Development

Successfully merging a pull request may close this issue.