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

Allow plain string in Message Example Object field payload for non-json payloads (like xml, yaml) #1038

Open
timonback opened this issue Feb 23, 2024 · 8 comments
Labels

Comments

@timonback
Copy link

Describe the bug

Hi, we are implementing the spec to create a Message Example Object for xml.
The field payload assumes a Map[string, any], which only works for json.

How is i.e. an xml payload represented?

payload Map[string, any] The value of this field MUST validate against the Message Object's payload field.

To Reproduce

See sample document

Expected behavior

We assume that a plain string (or any) should also be allowed.

Sample document

{
  "name": "SimpleSignup",
  "summary": "A simple UserSignup example message",
  "headers": {
    "correlationId": "my-correlation-id",
    "applicationInstanceId": "myInstanceId"
  },
  "payload": "<xml><with_field>value</with_files></xml>"
}
Copy link

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

@GreenRover
Copy link
Collaborator

Please have a look at the multi format schema object:
https://www.asyncapi.com/docs/reference/specification/v3.0.0#multiFormatSchemaObject

This makes your api a little bit more valid.
But xml is still no valid and official supported schema type.
There are a lot of discussion why not. But in short, xml knows attributes and childs. This can not be handled by tooling.

@timonback
Copy link
Author

Thank you @GreenRover for the reference link.
Specifying a complete schema for xml is probably a bit overkill for us, but we will discuss.
(Based on a java class, we only want to generate an xml example)

But in short, xml knows attributes and childs

So true, we came across the same issue with the xml attributes.


I tested a bit more, and changing the SchemaObjects field type value to string (instead of object) does the trick so that AsyncApi Studio does validate (through asyncapi/parser) positively.

"io.github.springwolf.examples.kafka.dtos.XmlPayloadDto": {
  "type": "string",
  "properties": {
    "someEnum": {
      "type": "string",
      "enum": [
        "FOO1",
        "FOO2",
        "FOO3"
      ]
    },
    "someLong": {
      "type": "integer",
      "format": "int64"
    },
    "someString": {
      "type": "string"
    }
  },
  "examples": [
    "<io.github.springwolf.examples.kafka.dtos.XmlPayloadDto><someEnum>FOO1</someEnum><someLong>0</someLong><someString>string</someString></io.github.springwolf.examples.kafka.dtos.XmlPayloadDto>"
  ]
}

@GreenRover
Copy link
Collaborator

Can you please provide the full schema. Because what you provide looks more like a bug in studio.

@timonback
Copy link
Author

Sure, here it is:

{
  "asyncapi": "3.0.0",
  "info": {
    "title": "Springwolf example project - Kafka",
    "version": "1.0.0",
    "description": "Springwolf example project to demonstrate springwolfs abilities, including **markdown** support for descriptions.",
    "contact": {
      "name": "springwolf",
      "url": "https://github.com/springwolf/springwolf-core",
      "email": "[email protected]"
    },
    "license": {
      "name": "Apache License 2.0"
    },
    "x-generator": "springwolf"
  },
  "defaultContentType": "application/json",
  "servers": {
    "kafka": {
      "host": "kafka:29092",
      "protocol": "kafka"
    }
  },
  "channels": {
    "xml-topic": {
      "messages": {
        "io.github.springwolf.examples.kafka.dtos.XmlPayloadDto": {
          "$ref": "#/components/messages/io.github.springwolf.examples.kafka.dtos.XmlPayloadDto"
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HeadersNotDocumented": {
        "type": "object",
        "properties": { },
        "examples": [
          { }
        ],
        "x-json-schema": {
          "$schema": "https://json-schema.org/draft-04/schema#",
          "type": "object"
        }
      },
      "io.github.springwolf.examples.kafka.dtos.XmlPayloadDto": {
        "type": "object",
        "properties": {
          "someEnum": {
            "type": "string",
            "enum": [
              "FOO1",
              "FOO2",
              "FOO3"
            ]
          },
          "someLong": {
            "type": "integer",
            "format": "int64"
          },
          "someString": {
            "type": "string"
          }
        },
        "examples": [
          "<io.github.springwolf.examples.kafka.dtos.XmlPayloadDto><someEnum>FOO1</someEnum><someLong>0</someLong><someString>string</someString></io.github.springwolf.examples.kafka.dtos.XmlPayloadDto>"
        ],
        "x-json-schema": {
          "$schema": "https://json-schema.org/draft-04/schema#",
          "properties": {
            "someEnum": {
              "enum": [
                "FOO1",
                "FOO2",
                "FOO3"
              ],
              "type": "string"
            },
            "someLong": {
              "format": "int64",
              "type": "integer"
            },
            "someString": {
              "type": "string"
            }
          },
          "type": "object"
        }
      }
    },
    "messages": {
      "io.github.springwolf.examples.kafka.dtos.XmlPayloadDto": {
        "headers": {
          "$ref": "#/components/schemas/HeadersNotDocumented"
        },
        "payload": {
          "schemaFormat": "application/vnd.aai.asyncapi+json;version=3.0.0",
          "schema": {
            "$ref": "#/components/schemas/io.github.springwolf.examples.kafka.dtos.XmlPayloadDto"
          }
        },
        "contentType": "text/xml",
        "name": "io.github.springwolf.examples.kafka.dtos.XmlPayloadDto",
        "title": "XmlPayloadDto",
        "bindings": {
          "kafka": {
            "bindingVersion": "0.4.0"
          }
        }
      }
    }
  },
  "operations": {
    "xml-topic_receive_receiveExamplePayload": {
      "action": "receive",
      "channel": {
        "$ref": "#/channels/xml-topic"
      },
      "title": "xml-topic_receive",
      "description": "Showcases a xml based message",
      "bindings": {
        "kafka": {
          "bindingVersion": "0.4.0"
        }
      },
      "messages": [
        {
          "$ref": "#/channels/xml-topic/messages/io.github.springwolf.examples.kafka.dtos.XmlPayloadDto"
        }
      ]
    }
  }
}

@timonback
Copy link
Author

Any update on this?
Should I duplicate the issue in studio?

@timonback
Copy link
Author

timonback commented Jun 21, 2024

Update: the related PR has been merged in parser-js: asyncapi/parser-js#1007
EDIT: actually, it was only updated, not merged yet

Copy link

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

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 ❤️

@github-actions github-actions bot added the stale label Oct 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants