Skip to content

fix: allow $refs to component messages with special characters in names#1143

Open
armorbreak001 wants to merge 1 commit intoasyncapi:masterfrom
armorbreak001:bounty/1132-fix-ref-square-brackets
Open

fix: allow $refs to component messages with special characters in names#1143
armorbreak001 wants to merge 1 commit intoasyncapi:masterfrom
armorbreak001:bounty/1132-fix-ref-square-brackets

Conversation

@armorbreak001
Copy link
Copy Markdown

Fixes #1132

Problem

The parser incorrectly rejected valid $refs to component messages whose names contain square brackets (e.g., JMS-style names like test:[HandleFirst,HandleSecond]:SubscribeMessage).

Root cause: The ajv-formats library's uri-reference format validator rejects URI references containing square brackets, even though they are legal per RFC 3986 and RFC 6901. This caused a cascade of false validation failures:

  • The $ref value failed format validation → Reference schema rejected
  • Channel/message oneOf validation failed → reported as "Referencing in this place is not allowed"

Fix

In the unresolved schema validation, remove the format constraint from ReferenceObject.json definitions. The format check for uri-reference on $ref fields provides little practical benefit (Spectral's ref resolver already validates resolvability) and causes false positives for valid documents.

How to verify

const { Parser } = require("@asyncapi/parser");
const parser = new Parser();

const doc = {
  asyncapi: "3.0.0",
  info: { title: "Test", version: "1.0" },
  channels: {
    "test:[HandleFirst,HandleSecond]": {
      address: "test-queue",
      messages: {
        SubscribeMessage: {
          "$ref": "#/components/messages/test:[HandleFirst,HandleSecond]:SubscribeMessage"
        }
      }
    }
  },
  components: {
    messages: {
      "test:[HandleFirst,HandleSecond]:SubscribeMessage": {
        name: "SubscribeMessage",
        payload: { type: "object", properties: { data: { type: "string" } } }
      }
    }
  },
  operations: {}
};

const { document, diagnostics } = await parser.parse(doc);
// Before fix: diagnostics contains error "Referencing in this place is not allowed"
// After fix: document is parsed successfully, no errors

The ajv-formats uri-reference format validator incorrectly rejects valid URI
references containing square brackets ([, ]), which are legal per RFC 3986 and
RFC 6901. This caused false validation failures for $refs pointing to
components whose keys contain special characters (e.g. JMS message names like
"test:[HandleFirst,HandleSecond]").

Fixes asyncapi#1132
@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Apr 13, 2026

⚠️ No Changeset found

Latest commit: 9b60933

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@sonarqubecloud
Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant