spec: Possible bug with example - adeo-kafka-request-reply-asyncapi

Hi!

I’m not sure, but looks like this example is broken - https://github.com/asyncapi/spec/blob/master/examples/adeo-kafka-request-reply-asyncapi.yml

I checked It in Studio - no warnings, but when I tried to parse this example using JAsyncAPI I enfaced with errors

I found two strange things:

  1. extensions
bindings:
      kafka:
        x-key.subject.name.strategy:
          type: string
          description: >
            We use the RecordNameStrategy to infer the messages schema. Use
            `key.subject.name.strategy=io.confluent.kafka.serializers.subject.RecordNameStrategy`
            in your consumer configuration.
        x-value.subject.name.strategy:
          type: string
          description: >
            We use the RecordNameStrategy to infer the messages schema. Use
            `value.subject.name.strategy=io.confluent.kafka.serializers.subject.RecordNameStrategy`
            in your consumer configuration.

This property name x-key.subject.name.strategy must not be interpreted as valid because of our regex ^x-[\w\d\-\_]+$ or not?

  1. Schema structure
CorrelationId:
      type: string
      format: uuid
      description: >-
        A unique Correlation ID defined from the `REQUEST_ID` or the
        `MESSAGE_ID` provided in the Costing Request.
      example: 1fa6ef40-8f47-40a8-8cf6-f8607d0066ef

I may be wrong, but draft-07 doesn’t have such field, only examples or not?

About this issue

  • Original URL
  • State: open
  • Created 5 months ago
  • Comments: 17 (17 by maintainers)

Commits related to this issue

Most upvoted comments

Regarding point 1, I see the regex we show in our documentation doesn’t correspond with the one enforced in our JSON Schema documents, which indeed allows for . characters. So I completely understand then why Studio is not complaining, but I don’t get why JAsyncAPI doesn’t, tbh. So in summary, we should either fix the docs or fix the regex. A decision should be taken.

@smoya @fmvilas @derberg I think that docs must be fixed, because we already released 3.0.0 with this regex - ^x-[\\w\\d\\.\\x2d_]+$

I’ll crate MR tonight

I agree, unless allowing dots in the extension name has an edge case I can’t see.

Regarding point 1, I see the regex we show in our documentation doesn’t correspond with the one enforced in our JSON Schema documents, which indeed allows for . characters. So I completely understand then why Studio is not complaining, but I don’t get why JAsyncAPI doesn’t, tbh. So in summary, we should either fix the docs or fix the regex. A decision should be taken.

Yes, you are right. We need to discuss and decide which pattern to use.

That’s why I requested clarification. Because are using description from out website and not digging into our JSON Schemas, to write specs, and that’s is a reason why I receive issues, with parsing errors, from users

Regarding point 2, yes you are right: there is no example field but examples.

I’ll create MR with fix for adeo example, tonight

Reason for the failed validation is RequesterCode and BuCode have example values as integer, NOT string.

i.e. should be the following:

    RequesterCode:
      type: string
      description: >-
        The Costing requester code (generally the BU Code). The requester code
        is useful to get the dedicated context (tenant).
      examples:
        - "1"
    BuCode:
      type: string
      description: The Business Unit code for which data are applicable.
      examples:
        - "1"

It’s a YAML syntax where lone numbers without characters are interpreted as integer not string by default as you see in the other examples.

However… The error codes SUCKS and does not explain it in studio 👎

Yep, I’m agree with you. Will close this issue as resolved, after MR with fix for regex will be merged

merged now btw! 🎉 🚀

so we must clarify this situation and decide what to do with properties from OAS schema

I think we are clear “enough” about that in https://www.asyncapi.com/docs/reference/specification/v3.0.0#schemaObject. The fact people is used to OAS and thinks not having those in the AsyncAPI Schema Object is a bug might be because they don’t read the docs (not hard feelings, just clarifying btw).

However, it might make sense to discuss if any of those extra fields (added in the OAS Schema) could also make sense into AsyncAPI Schema object. IMHO, taking the example keyword, it doesn’t because of redundancy. But what about the rest?

What is the amount of requests for adding those fields we receive? Can we list them? This could definitely help to understand those use cases.

I guess this could go into a new issue anyway.

Yep, I’m agree with you. Will close this issue as resolved, after MR with fix for regex will be merged

After that I’ll create new issue to refresh discussion about field from OAS schema and will provide related issues from jasyncapi and modelina