fix: resolve $refs and validate AsyncAPI 3 Multi Format Schema Object

[vadyvas]

What/Why/How?

AsyncAPI 3 allows two shapes for headers, payload, and components.schemas: a Schema Object, or a Multi Format Schema Object that holds the schema in schema and its format in schemaFormat.

The type definitions used an anonymous node type for the multi-format shape. Two defects followed:

1. resolveType normalizes only types that pass isNamedType, so it returned the anonymous type unchanged. The schema property kept the raw string 'Schema'.
2. The walker demotes a type without a name to scalar and stops. It never entered schema, so the bundler never found the $ref inside it.

Found in https://github.com/Redocly/redocly/pull/26390

Reference

https://www.asyncapi.com/docs/reference/specification/v3.0.0#multiFormatSchemaObject
https://www.asyncapi.com/docs/reference/specification/v3.0.0#messageObject
https://www.asyncapi.com/docs/reference/specification/v3.0.0#componentsObject

Testing

• added e2e test

Screenshots (optional)

Check yourself

• This PR follows the contributing guide
• All new/updated code is covered by tests
• Core code changed? - Tested with other Redocly products (internal contributions only)
• New package installed? - Tested in different environments (browser/node)
• Documentation update has been considered

Security

• The security impact of the change has been considered
• Code follows company security practices and guidelines

---

Note

Low Risk
Type-system fix for AsyncAPI 3 schema walking only; no auth, data, or runtime behavior outside bundling/validation.

Overview
Fixes bundle (and walking/validation) skipping $refs inside AsyncAPI 3 Multi Format Schema Objects.

Anonymous inline types for the { schema, schemaFormat } shape were not named, so resolveType left schema as a raw string and the walker treated the node as a scalar. This adds a named MultiFormatSchema type and uses it for headers, payload, message-trait headers, and components.schemas when the value has a schema property (plain Schema Objects still work). An e2e bundle fixture covers multi-format, default-format, and plain schema cases.

^{Reviewed by Cursor Bugbot for commit 4bb46f2. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 4bb46f2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@redocly/openapi-core	Patch
@redocly/cli	Patch
@redocly/client-generator	Patch
@redocly/respect-core	Patch

Not sure what this means? Click here to learn what changesets are.

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

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	77.73% (🎯 77%)	11763 / 15132
🔵	Statements	77.8% (🎯 77%)	12588 / 16179
🔵	Functions	82.42% (🎯 81%)	2401 / 2913
🔵	Branches	71.19% (🎯 71%)	8646 / 12144

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/core/src/types/asyncapi3.ts	61.9%	21.42%	33.33%	61.9%	186, 254, 483-511

Generated in workflow #11446 for commit 4bb46f2 by the Vitest Coverage Report Action

[github-actions]

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.01x ± 0.01
cli-next	▓ 1.00x ± 0.01	▓ 1.02x ± 0.01	▓ 1.00x (Fastest)

[github-actions]

📦 A new experimental 🧪 version v0.0.0-snapshot.1787151744 of Redocly CLI has been published for testing.

Install with NPM:

npm install @redocly/cli@0.0.0-snapshot.1787151744

⚠️ Note: This is a development build and may contain unstable features.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 4bb46f2. Configure here.}

[cursor]

NamedSchemas pollutes Schema definitions

Low Severity

NamedSchemas is now a Schema-vs-MultiFormatSchema discriminator for components.schemas, but the shared draft-7 Schema type still points definitions at the string NamedSchemas. In AsyncAPI 3 that makes nested JSON Schema definitions accept Multi Format shapes, even though those entries must remain plain Schema Objects.

Additional Locations (1)

• packages/core/src/types/asyncapi3.ts#L613-L614

 

^{Reviewed by Cursor Bugbot for commit 4bb46f2. Configure here.}