Usages of allOf within message payload could be flattened

[jamescrowley]

Describe the bug

I'm not sure if this is a bug or not, but for me, allOf is rendered in an unexpected way when used in the message payload. Can you confirm if this is deliberate or not? If not, I'll look to fix.

How to Reproduce

asyncapi: 2.0.0
info:
  title: MQTT API
  version: '2.0.0'

defaultContentType: application/json

channels:
  /v2/abc/data/pack_data:
    description: Publish logging data from devices
    publish:
      operationId: publishPackData
      message:
        name: pack_data
        payload:
          $ref: "#/components/schemas/pack_data"

components:
  schemas:
    pack_data:
      allOf:
      - $ref: "#/components/schemas/common_payload"
      - type: object
        properties:
          cycle_id:
            type: string
    common_payload:
      type: object
      properties:
        device_id:
            type: string
        site_id:
            type: string

Expected behavior

I'd expect the use of 'allOf' to be transparent in the documentation (ie as if everything had just been defined explicitly in-line).

ie

[github-actions[bot]]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

Makes sense, this is the part of the template responsible for schema -> https://github.com/asyncapi/html-template/blob/master/partials/schema-prop.html

[jamescrowley]

As allOf requires the message to validate the schema of each (as opposed to extend them), I'm starting to think that 'flattening' these may only make sense when 'additionalProperties' is set to true or is undefined for every element? @derberg thoughts?

[InTheCloudDan]

Just adding a 👍 here from conversation on Slack. I'm looking for this feature also. My current usage is pretty basic though and I haven't done any interacting with allOf and additionalProperties so not sure on the best approach to handling them.

[derberg]

@jamescrowley yeap, looking at https://json-schema.org/understanding-json-schema/reference/combining.html#id5 looks like there is no other option but flatten only if "additionalProperties": false is not present. Pretty complicated case as maybe there are other combinations too.

I checked quickly with OpenAPI and the swagger UI is flattening always

[InTheCloudDan]

Any update on this one? It would be useful feature to me.

[derberg]

@InTheCloudDan have a look on the thread in this PR https://github.com/asyncapi/html-template/pull/16 from @jamescrowley. We are pretty much stuck there, appriciate your input into discussion.

[WaleedAshraf]

I also have this problem. But for now, we are okay with two schemas in the view. In our case, first schema is always the same for all the messages, So, it's better hidden. Mostly we are only interested in seeing the second part.

I think best solution will be if on top somewhere, we can provide checkboxes

• [ ] merge allOf schemas
• [ ] expand all schemas
• [ ] collapse all schemas

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping: It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation. Thank you for your contributions :heart:

[FabienSailliet]

Has there been any progress on this issue? Would be really useful for me too

[derberg]

@FabienSailliet Hi, as you can see there was a PR for that https://github.com/asyncapi/generator/issues/115 but because of concerns mentioned in this issue and the PR, we did not come with an final conclusion how this shoudl be solved. What is your opinion on the topic?

[FabienSailliet]

It is to be noted that in the JSON Schema specification, they are stating that allOf is not to be used to extend schemas:

While it might be surprising, allOf can not be used to “extend” a schema to add more details to it in the sense of object-oriented inheritance.

They later say:

There are some proposals to address this in the next version of the JSON schema specification.

But they do not give more details about it, so maybe it could be better to wait for something on their side, I did not check if there were some discussions about it.

In my opinion, I think that if a property is described in multiple objects to be merged, the resulting merged object should contain the most specific given definition, and we should be allowed to do this only if the definitions are compatible (we cannot merge a property that should be an array on one side and an integer on another). By doing it this way, we can have objects allowing additional properties or not, as long as they are not incompatible.

[WaleedAshraf]

"unevaluatedProperties" in draft-2019 solves the problem of using "additionalProperties" with "allOf".

Example,

{
  "$schema": "http://json-schema.org/draft/2019-09/schema",
  "allOf": [
    {
      "type": "object",
      "properties": {
        "veggieName": {
          "type": "string",
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "veggieLike": {
              "type": "boolean",
            }
          }
        }
      }
    }
  ],
  "unevaluatedProperties": false,
}

Adding any additional prop to any of allOf schema will fail the validation. Test it here: https://www.jsonschemavalidator.net/s/MxFv67dv

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping: It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation. Thank you for your contributions :heart:

[elnipa]

Any update on this one? A solution would be highly appreciated to have the same behavior as in Swagger/Redoc for our openAPI rest API.

[derberg]

@elnipa could you show some examples? I'm not very familiar with how these tools handle it and what you refer to exactly. Thanks 🙇🏼

[elnipa]

@elnipa could you show some examples? I'm not very familiar with how these tools handle it and what you refer to exactly. Thanks 🙇🏼

Sure, in Redoc the attributes within allOf are flattened and only oneOf attributes are splitted. Compare for the following example:

  exampleChannel:
    description: example channel
    publish:
      message:
        payload:
          allOf:
            - type: object
              properties:
                foo:
                  type: string
            - type: object
              properties:
                bar:
                  type: string
            - oneOf:
                - type: object
                  properties:
                    option1:
                      type: boolean
                - type: object
                  properties:
                    option2:
                      type: integer

asyncAPI

openAPI (Redoc)

[derberg]

@elnipa thanks a lot, it helps!

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping: It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation. Thank you for your contributions :heart:

[Z5eyhS0uubejR0SVmX2O]

I second the alignment with redoc which @elnipa is proposing.

Added a demo here: https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/Z5eyhS0uubejR0SVmX2O/Show-Redoc-Behavior-for-OneOf/main/openapi3.yaml

OpenAPI3: https://github.com/Z5eyhS0uubejR0SVmX2O/Show-Redoc-Behavior-for-OneOf/blob/main/openapi3.yaml Equivalent AsyncAPI: https://github.com/Z5eyhS0uubejR0SVmX2O/Show-Redoc-Behavior-for-OneOf/blob/main/asyncapi.yaml

[derberg]

anyone wants to give this one a try again? I guess some work from @jamescrowley could be reused

[Z5eyhS0uubejR0SVmX2O]

Going along with this, it would be super nice if the title of the object in the OneOf/AllOf rendered as Redoc does. I updated my examples to include this.

[Z5eyhS0uubejR0SVmX2O]

Identified further concern with how properties in addition to those defined in OneOf/AllOf are rendered, added to the examples I link to (just so I can provide a URL that shows how redoc-cli renders it).

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping: It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation. Thank you for your contributions :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping: It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation. Thank you for your contributions :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping: It will be closed in 60 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation. Thank you for your contributions :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[magicmatatjahu]

I don't know if we should handle that issue in the near future. allOf in the JSON Schema doesn't mean that "objects" should merged but the payload itself should be compatible with all schemas defined under allOf and this is a big difference, because during merging we may forget some elements and the final schema will not be correct referring to the original. WDYT @derberg @fmvilas? Of course oneOf we should try to visualise in better way (we have separate issue for that - https://github.com/asyncapi/asyncapi-react/issues/278), but that problem is only related to the allOf

[derberg]

I'm supporting merging only if this is optional as I stated above because there might be people that designed their schemas in a way that it will always be valid when we merge in one.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: