Redocly / Redocly/redocly-cli

Simple allOf causes no-invalid-media-type-examples to flag a property

Open
#1,437 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

p3 Type: Bug
Dominant language
TypeScript
Stars
1.5k
Forks
228
Avg merge
1d 14h
Merged PRs (30d)
48

Description

Describe the bug

First, I won't rule out the possibility that my schemas are incorrect or ugly, but they seem okay based on what I know.

I have a schema that uses allOf to bring together two subschema objects that have the same name. One has 4 properties and the other has 3 of the 4. The example response contains all 4 properties. The no-invalid-media-type-examples rule in the linter flags the 4th property with "must not have unevaluated property." Since that property is defined in one of the subschemas, I don't understand why the linter sees it as a problem.

To Reproduce
Steps to reproduce the behavior:

  1. Use the attached OpenAPI YAML file allOf-test.zip.
    The schemas in question are these (with some parts omitted for clarity):
    dimension-ref:
      type: object
      properties:
        department:
          type: object
          properties:
            key:
              type: string
              description: Department Key
              example: '11'
            id:
              type: string
              description: Department
              example: DEP-11
            name:
              type: string
              description: Department Name
              readOnly: true
              example: Sales and Marketing
            href:
              type: string
              readOnly: true
              example: /objects/company-config/department/11

        dimensions:
          type: object
          description: Dimensions active on this project estimate line.
          allOf:
            - $ref: '#/components/schemas/dimension-ref'
            - properties:
                department:
                  type: object
                  description: Reference to the department.
                  properties:
                    key:
                      type: string
                      description: Department key.
                      example: '1'
                    id:
                      type: string
                      description: Unique identifier for the department.
                      example: Dept 11
                    name:
                      type: string
                      description: User-specified name for the department.
                      readOnly: true
                      example: Engineering

Note that in dimension-ref, the department object is defined with 4 properties. Under the dimensions object, dimension-ref is used with allOf and a department object that only has 3 of those 4 properties.

(You might wonder why the 3 properties that are in both schemas are essentially identical. The original versions contain some x- extensions that are different, but those are stripped out by a script that leaves what you see here.)

  1. And this .lint config.yaml file:
extends:
  - recommended

rules:  # off, warn, error
  no-invalid-media-type-examples: warn
  no-unused-components: warn
  spec-components-invalid-map-name: warn
  1. Run this command with these arguments... redocly lint --config=.lint-config.yaml --format=stylish allOf-test.yaml
  2. See error:
  88:27   warning  no-invalid-media-type-examples  Example value must conform to the schema: `department` property must NOT have unevaluated properties `href`.

(There are a couple of other warnings, but this question is just about this one.)

Expected behavior

I would expect no warnings about a property in an example response that is defined in one schema under allOf even if it not defined in the other schema under allOf. I believe that additionalProperties is true by default, so the property should not be flagged. As a test, I added additionalProperties: true to the schema that only has 3 properties, and the linter did not flag the example property.

OpenAPI description

See the attached file. We are using OAS v3.0.0

Redocly Version(s)

redocly 1.9.0

Node.js Version(s)

node 18.7.0

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running the documented redocly lint command with .lint-config.yaml against allOf-test.yaml and inspect the no-invalid-media-type-examples result around the reported line. Compare validation of the department example across the two allOf schemas; done means the valid href property is no longer incorrectly flagged while genuinely invalid properties remain reported.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, typescript
Domain
api, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.