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.

[daemonkeeper]

Checking this referenced issue only now, I think my comment from ag2ai/faststream#2772 (comment) would be a much better fit here.

[AceTheCreator]

Hey @Lancetnik 👋🏽

After digging into this, the error originates in the parser library, not the react-component. The parser uses Spectral for validation, and this is a Spectral validation error triggered by the [] characters in the $ref paths.

The root cause: [ and ] are not valid unencoded in URI fragment paths (RFC 3986). When Spectral's resolver encounters a $ref like #/channels/test:[HandleFirst,HandleSecond], it fails to resolve it, which causes the schema validator to surface "Referencing in this place is not allowed".

The fix is to percent-encode the brackets in $ref values ([ → %5B, ] → %5D). The object keys themselves don't need to change, only the $ref strings since those are URI references.

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

[Lancetnik]

@AceTheCreator thank you a lot!

[Lancetnik]

I just confused why we have different rules for $refs in different places

[AceTheCreator]

@Lancetnik can I close this issue?

[Lancetnik]

@AceTheCreator sure, thank you! I think, parser Issue should be enough :)

[Lancetnik]

Btw, nice work with extensions
Finally, we implemented "try it out" feature in FastStream - https://github.com/ag2ai/faststream/releases/tag/0.6.7
Using https://github.com/Shepard2154/asyncapi-try-it-plugin
A lot of positive feedback there already - users really like Swagger experience