They are probably incompatible. Values: "integer" "string"

[dregof]

Describe the bug

Can't generate the api docs sucessfully due to a compatibility validation error with the following behaviour:

I'm using allOf, have an object with an array of items. This items have a property as integer and I want to override each item by another custom object that also have the same property but as a string.

Expected behavior

No errors.

Current behavior

Get the following error:

[ERROR] Error: Could not resolve values for path:"properties.errors.items.properties.code.type". They are probably incompatible. Values: "integer" "string" at throwIncompatible (...\node_modules\json-schema-merge-allof\src\index.js:95:9) at ...\node_modules\json-schema-merge-allof\src\index.js:320:11 at Array.forEach () at mergeSchemas (...\node_modules\json-schema-merge-allof\src\index.js:301:13) at properties (...\node_modules\json-schema-merge-allof\src\index.js:116:42) at ...\node_modules\json-schema-merge-allof\src\complex-resolvers\properties.js:27:16 at Array.reduce () at mergeSchemaGroup (...\node_modules\json-schema-merge-allof\src\complex-resolvers\properties.js:24:18) at Object.resolver (...\node_modules\json-schema-merge-allof\src\complex-resolvers\properties.js:71:19) at callGroupResolver (...\node_modules\json-schema-merge-allof\src\index.js:119:35) [INFO] Docusaurus version: 3.4.0

Possible solution

The compatibility validation is no needed in this case as you try to replace the whole schema by other. The types could not match at all and this could be intentionally the objective of the substitution.

Steps to reproduce

yarn docusaurus gen-api-docs all

with the following piece of openapi:

    CustomErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            payload:
              allOf:
                - $ref: '#/components/schemas/ErrorResponsePayload'
                - type: object
                  properties:
                    data:
                      allOf:
                        - $ref: '#/components/schemas/ErrorResponseData'
                        - type: object
                          properties:
                            errors:
                              type: array
                              description: List of errors
                              items:
                                $ref: '#/components/schemas/CustomError'

    ErrorResponse:
      type: object
      properties:
        payload:
          $ref: '#/components/schemas/ErrorResponsePayload'
        status:
          $ref: '#/components/schemas/ResponseStatus'
    ErrorResponsePayload:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ErrorResponseData'
      description: Error response payload
    ErrorResponseData:
      type: object
      properties:
        errors:
          type: array
          description: List of errors
          items:
            $ref: '#/components/schemas/Error'
      description: Error response data
    Error:
      type: object
      properties:
        code:
          type: integer
          description: Internal error code
          example: '500'
        message:
          type: string
          description: Main error message.
          example: 'INTERNAL_SERVER_ERROR'
        details:
          type: string
          description: Contains additional details of the error.
          example: 'A system error has occurred, please forgive the inconvenience.'
      description: Error detail

    CustomError:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          enum:
            - ERROR_1
            - ERROR_2
          example: ERROR_1

where Error schema has 'code' as integer and CustomError has 'code' as string (enum).

Context

I could visualize a swagger preview with other tools without any issue so I discard openapi codification error.

Your Environment

• Version used: Docusaurus version 3.4.0 and also tested in 3.5.2
• Environment name and version: node v20.15.1

[sserrata]

Hi @dregof, our plugin tries to be as un-opinionated as possible when it comes to allOf, particularly when schemas are incompatible. That said, just because other tools like SwaggerUI, Redoc, etc., don't throw an error, doesn't mean there isn't an issue with your spec. Some tools are just more opinionated and may implement some automatic merging/handling of such cases which may or may not align with what you expect.

Have you inspected exactly how other tools process the incompatibility? Does the end result match what you expect or designed?