[FEATURE] Kafka operations: allow groupId and clientId to be a string or array of strings

[ivangsa]

Why do we need this improvement?

groupId and clientId are typed as Schema Object. But these are configuration
values, not a data schema. Expressing a consumer group name requires unnecessary
JSON Schema boilerplate when a plain string would do.

# what you have to write today
groupId:
  type: string
  enum: ['payments-consumer-group']
 
# what you actually mean
groupId: 'payments-consumer-group'

How will this change help?

The intent is immediately readable in the document.

Screenshots

No response

How could it be implemented/designed?

Allow groupId and clientId to accept a plain string, an array of strings,
or the existing Schema Object form.

# plain string
groupId: 'payments-consumer-group'
 
# array of strings
groupId:
  - 'payments-consumer-group-1'
  - 'payments-consumer-group-2'
 
# existing Schema Object form, still valid
groupId:
  type: string
  enum: ['payments-consumer-group']

In spec-json-schemas, the property definition becomes a oneOf:

"groupId": {
  "oneOf": [
    { "type": "string" },
    { "type": "array", "items": { "type": "string" }, "minItems": 1 },
    { "$ref": "http://asyncapi.com/definitions/3.0.0/schema.json" }
  ],
  "description": "Id of the consumer group."
}

The same change applies to clientId.

New and updated tooling should resolve the three forms in order: plain string
first, then array of strings, then treat an object as a Schema Object. A plain
string and an array can never be mistaken for a Schema Object, so existing
tooling that only handles the object form continues to work without any changes.

🚧 Breaking changes

No

👀 Have you checked for similar open issues?

• I checked and didn't find a similar issue

🏢 Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines

Are you willing to work on this issue?

Yes I am willing to submit a PR!

[dalelane]

The current support for a schema object is broader than just the ability to use an enum to list valid group ids. For example, pattern can be used to enforce a convention such as a required prefix, and description can be used for additional metadata.

I realise that you want to explicitly define a single group id, rather than describe the constraints for many possible valid group ids. But I don't agree that an enum is the only (or even the best) way to do this, when const is available.

I'm a little skeptical that the benefit of being able to say:

groupId: 'my-group-id'

instead of:

groupId:
    const: 'my-group-id'

is really worth the complexity of introducing a oneOf. const, to me, feels almost as concise, explicit, and readable - it clearly defines an intent that the group id should be a single constant string - and without the overhead of having to dynamically work out the meaning from the type of the value.

[ivangsa]

Thanks, I didn't realize const could be used here. That makes the current shape less verbose than I thought:

I still think a JSON Schema object is a strange shape for groupId / clientId, because in the common case these are application configuration values, not schemas for message data. But if const is the intended way to express a fixed value, then this is probably acceptable.

I’m OK closing this issue and focusing on the remaining Kafka binding issues.