Parser incorrectly rejects valid $refs to component messages with square brackets in names within channels.messages

[Lancetnik]

Description

The AsyncAPI parser incorrectly reports "Referencing in this place is not allowed" when using $ref within channels.{channelName}.messages.{messageName} to reference a component message whose name contains square brackets (e.g., msg:[HandleFirst,HandleSecond]).

Note: The parser correctly allows square brackets in channel names, operation names, and when referencing channels/operations. The issue is specifically limited to message references within channel definitions.

Background

This issue was discovered through reports from FastStream users (see related issues below) where AsyncAPI generators produce component message names containing square brackets when multiple subscriber handlers are registered for the same channel. The generated AsyncAPI documents are valid according to the AsyncAPI specification, but the parser incorrectly flags $ref values within channels.messages that reference these component messages as invalid.

How to Reproduce

{
  "asyncapi": "3.1.0",
  "info": {
    "title": "Test",
    "version": "1.0.0"
  },
  "channels": {
    "test:[HandleFirst,HandleSecond]": {
      "address": "test",
      "messages": {
        "SubscribeMessage": {
          "$ref": "#/components/messages/msg:[HandleFirst,HandleSecond]"
        }
      }
    }
  },
  "operations": {
    "test:[HandleFirst,HandleSecond]Subscribe": {
      "action": "receive",
      "channel": {
        "$ref": "#/channels/test:[HandleFirst,HandleSecond]"
      },
      "messages": [
        {
          "$ref": "#/channels/test:[HandleFirst,HandleSecond]/messages/SubscribeMessage"
        }
      ]
    }
  },
  "components": {
    "messages": {
      "msg:[HandleFirst,HandleSecond]": {
        "title": "TestMessage"
      }
    }
  }
}

Expected behavior: The document should validate successfully. The $ref in channels.test:[HandleFirst,HandleSecond].messages.SubscribeMessage should be accepted.

Observed behavior: The parser reports:

Error: Referencing in this place is not allowed
Path: channels/test:[HandleFirst,HandleSecond]/messages/SubscribeMessage

What Works Correctly

The parser correctly handles square brackets in:

• ✅ Channel names (e.g., test:[HandleFirst,HandleSecond])
• ✅ Operation names (e.g., test:[HandleFirst,HandleSecond]Subscribe)
• ✅ References to channels/operations (e.g., $ref: "#/channels/test:[HandleFirst,HandleSecond]")
• ✅ Message references in operations (e.g., $ref: "#/channels/test:[HandleFirst,HandleSecond]/messages/SubscribeMessage")

What Doesn't Work

• ❌ $ref values within channels.{channelName}.messages.{messageName} that reference component messages with square brackets in their names

Root Cause Analysis

According to RFC 6901 (JSON Pointer), square brackets are valid characters in JSON pointer paths. They should be percent-encoded as %5B and %5D when used in JSON pointers, but the AsyncAPI specification and many implementations accept them directly in $ref values.

The parser's validation logic appears to incorrectly flag $ref values containing square brackets as invalid specifically when they appear within channels.messages, even though:

1. Square brackets work fine in other contexts (channel names, operation names, etc.)
2. The referenced component message exists in the document
3. The JSON pointer syntax is correct

Related Issues

• FastStream Issue #2772: AsyncAPI generator produces unrenderable asyncapi.json if subscriber contains filter
• FastStream Issue #2447: Multiple subscriber handlers generate invalid AsyncAPI schema with square bracket channel names

Environment

• AsyncAPI Parser version: [version]
• AsyncAPI Specification version: 3.1.0 (and potentially 3.0.0 and 2.x.x)

Proposed Solution

The parser should accept $ref values containing square brackets within channels.messages when they correctly reference existing component messages in the document, following RFC 6901 guidelines for JSON pointers. The validation logic should treat square brackets in $ref values consistently across all contexts, not just selectively allow them in some places.