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

[steve-nay-sage]

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.)

3. 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

4. Run this command with these arguments... redocly lint --config=.lint-config.yaml --format=stylish allOf-test.yaml
5. 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

[tatomyr]

Hi @steve-nay-sage!

By default, we treat all schemas as closed. So you have two options: either add the additionalProperties: true to make them explicitly open or tweak the rule to do so automatically: https://redocly.com/docs/cli/rules/no-invalid-schema-examples/#configuration. Please keep in mind that the second option may result in worse error catching.

[steve-nay-sage]

Hi. We are using OpenAPI v3.0.3 in our schemas. The specification says that "additionalProperties defaults to true." So treating all schemas as closed is incorrect. I think we can agree that the linter should enforce the specification, which in this case would mean that schemas are open by default.

[tatomyr]

You're correct: schemas are open by default as per specification. However, for that particular rule, this behaviour doesn't allow catching typos. Imagine the following case:

openapi: 3.0.3
paths: 
  /test:
    get: 
      responses: 
        200:
          content: 
            application/json:
              schema: 
                type: object
                properties: 
                  TYPE: 
                    type: string
              example: 
                TYPO: something # <-- this is a typo, and the linter will error by default

If the rule treated the schema as open, it would not recognise the typo.

However, if that doesn't work for your case, you can configure the rule this way:

rules: 
  no-invalid-media-type-examples: 
    severity: warn
    allowAdditionalProperties: true

Then, there will be no warnings on examples like the one above.

I hope that makes sense.

[tatomyr]

Update. Probably we can catch cases like this and modify the rule's behaviour appropriately.