asyncapi / asyncapi/bindings

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

Open
#303 2 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
No language data
Stars
79
Forks
81
PR merge metrics
No merged PRs in 30d

Description

### 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.

```yaml
# 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.

```yaml
# 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`:

```json
"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?

- [x] I checked and didn't find a similar issue

### 🏢 Have you read the Contributing Guidelines?

- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)

### Are you willing to work on this issue?

Yes I am willing to submit a PR!

Contributor guide

Open the contributing guide

Research direction

Start in the spec-json-schemas property definitions for Kafka operations and trace how tooling reads groupId and clientId. Check validation and resolution behavior for the plain string, string array, and existing Schema Object forms; done means both properties accept all three without breaking the existing object form.

Written by the indexing model from the issue text.

Assessment

Tech stack
json, yaml
Domain
api, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.