feat(ls): add AsyncAPI 3 validation for new keywords by robert-hebel-sb · Pull Request #5104 · swagger-api/apidom

robert-hebel-sb · 2026-01-21T13:47:21Z

Summary

Comprehensive lint validation rules for AsyncAPI 3.0.0, including new keywords, allowed-fields validation, reference validation, and complete test coverage.

Key Changes

Validation Rules Added

New Objects: Operation, OperationReply, OperationReplyAddress, CorrelationID, MultiFormatSchema
Root Level: operations field validation
Operation Object: action (required), channel (required), title, reply, messages
Parameter Object: enum, default, examples (new in v3)
Server/Channel/Message Objects: Complete allowed-fields rules with extension support
Reference Validation: $ref--no-siblings and $ref--valid for all referenceable objects

Error Codes

Added 200+ error codes across 8 major sections (ASYNCAPI3_OPERATION=2080000, ASYNCAPI3_SERVER=2090000, etc.)

Test Coverage

282 tests passing
Fixtures for all objects in test/fixtures/validation/asyncapi/
Test files for operation, parameter, components, messages, server, info, channel, message, operation-trait, etc.
Tests cover valid cases, invalid cases, edge cases, and quickFix validation

Performance & Quality

Optimized channel address expression validation with early returns
Consistent error message patterns following project conventions
QuickFix snippets for required fields
All lint rules follow established patterns from PR feat(ls): add AsyncAPI 3 validation for compatible keywords #5096

Testing

Validate by opening an AsyncAPI 3.0.0 document with the language service and testing:

Missing required fields (action, channel)
Invalid field types
Disallowed fields
$ref validation

References

…ncapi3-with-compatible-properties

Completed implementation of allowed-fields validation rules for AsyncAPI 3.0 Server, Channel, MessageTrait, and Info objects. Each rule now includes the complete set of allowed fields according to AsyncAPI 3.0 specification. Changes: - Server Object: Added all 13 allowed fields (host, protocol, protocolVersion, pathname, description, title, summary, variables, security, tags, externalDocs, bindings, $ref) - Channel Object: Added all 11 allowed fields (address, messages, title, summary, description, servers, parameters, tags, externalDocs, bindings, $ref) - MessageTrait Object: Added all 14 allowed fields (messageId, headers, correlationId, schemaFormat, contentType, name, title, summary, description, tags, externalDocs, bindings, examples, $ref) - Info Object: Verified complete field list Addresses PR #5104 review comments. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Improved performance of apilintChannelAddressExpressionsDefinedInParameters function by reorganizing validation logic to use early returns and avoid unnecessary operations. Changes: - Move parameters existence check before toValue() call to avoid unnecessary serialization when parameters object is missing - Add early return when parameters is not an object - Only execute regex matching after confirming parameters exist - Reduces unnecessary operations in validation pipeline Addresses PR #5104 review comments. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Added complete test coverage for new lint rules and improved test robustness by reorganizing fixtures and updating test assertions. New test fixtures: - server-allowed-fields-3-0.yaml: Tests valid/invalid Server Object fields - channel-allowed-fields-3-0.yaml: Tests valid/invalid Channel Object fields - message-trait-allowed-fields-3-0.yaml: Tests valid/invalid MessageTrait fields Test fixture improvements: - Renamed fixtures to follow consistent naming convention (object-test-version) - Enhanced parameter-fields-types-3-0.yaml to test all 5 Parameter fields - Simplified multi-format-schema-fields-required-3-0.yaml to single scenario - Removed duplicate fixtures (external-docs-ref-valid, tag-ref-valid) Test assertion improvements: - Updated validate.ts to use flexible error code validation instead of brittle position-based assertions, making tests more maintainable - Fixed all test files to reference renamed fixtures correctly - Updated message-trait fixture to trigger 3 distinct validation errors All 282 tests now passing. Addresses PR #5104 review comments. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Remove redundant toValue() calls in allowedFields linter function where parentKey is already extracted. Rename test fixture to follow standard naming convention without -invalid suffix. Changes: - Optimize linter-functions.ts line 244 to use parentKey directly - Rename operation-reply-fields-types-3-0-invalid.yaml to match pattern - Update test reference in operation-reply.ts Fixes remaining issues from PR #5104 comments 37, 39, 43, 45, 46. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Co-authored-by: Oliwia Rogala <oliwia.rogala@smartbear.com>

…c-3' into feat/oss-246-validation-for-async-3

Add comprehensive test coverage for Multi Format Schema Object fields: - Add test for invalid schemaFormat type (number instead of string) - Add test for valid Multi Format Schema with proper types - Rename fixture files to follow established naming convention: - Base filename for invalid test data - Filename with -valid suffix for valid test data Related to PR feedback on Multi Format Schema Object validation. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Rename specExternalDocsRefValid to specExternalDocsRef to match the fixture file naming convention. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

packages/apidom-ls/src/config/asyncapi/message-trait/lint/allowed-fields-3-0.ts

packages/apidom-ls/src/config/asyncapi/operation-trait/lint/security--items-type-3-0.ts

packages/apidom-ls/src/config/asyncapi/operation/lint/security--items-type-3-0.ts

packages/apidom-ls/src/config/asyncapi/operation/lint/messages--type.ts

packages/apidom-ls/src/services/validation/linter-functions.ts

glowcloud · 2026-02-06T07:49:43Z

packages/apidom-ls/test/fixtures/validation/asyncapi/channel-address-parameter-mismatch.yaml

+    address: 'user/{userId}/events'
+    messages: {}
+    parameters:
+      someParam:


Is this still not the same as https://github.com/swagger-api/apidom/pull/5104/changes#diff-ae11f104f9cab918fd6f4018df8e5ac9e6330ae046eb0d0ab05cc7dd552d3af6, just with changed parameter names? Do they have different validation or do they both show the validation for address (no userId in parameters) and for parameters (no someParam in address)? If so, then only one is enough.

packages/apidom-ls/test/validate.ts

- Remove obsolete messageId and schemaFormat from Message Trait allowed fields - Fix security validation to use securityScheme instead of securityRequirement - Fix messages validation to check array items correctly - Remove unused hasRequiredFieldUnlessRef linter function - Remove redundant test fixture channel-address-parameter-mismatch.yaml - Create package-level CLAUDE.md with comprehensive lint rule guidelines - Move apidom-ls documentation from root CLAUDE.md to package level Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- Add specification URLs for OpenAPI, AsyncAPI, and Arazzo - Update examples to include multiple specifications - Replace hardcoded AsyncAPI paths with generic {spec} placeholders - Add OpenAPI 3.1 examples to Quick Reference section - Clarify that PR #5104 examples are AsyncAPI 3.0 specific Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

…ject test Addresses PR #5104 review comment requesting full assert.deepEqual comparison instead of selective property checks. The test now compares complete diagnostic objects including range, message, severity, code, source, and data fields. Related: #5104 (comment) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Add explicit guidance to always use assert.deepEqual with complete diagnostic objects instead of selective property checking. This was explicitly requested in PR #5104 review comments. Changes: - Expand Testing Best Practices section with clear examples - Add "What NOT to Do" section showing wrong patterns - Include tip for getting exact diagnostic values via console.log - Add Issue 5 in Common Pitfalls documenting this mistake - Mark comprehensive comparison as CRITICAL requirement Related: #5104 (comment) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

glowcloud

Alright, seems fine for me. I haven't gone much through the tests, so for the ones with the new style chosen by AI feel free to leave them as is or change to what we used before, but I don't want to block this further 😅

Also, I think that some fixtures that were used previously for completion (maybe something else as well?) were moved to the validation folder when the fixtures actually used for validation were moved 😅

Move completion-related AsyncAPI fixtures from validation folder structure to dedicated completion directory. Remove unused server fixtures that were not referenced by any tests. Changes: - Move bindings-empty.yaml to fixtures/completion/async/channel/ - Move servers-empty-dash.yaml to fixtures/completion/async/channel/ - Remove unused servers-empty.yaml, servers-first.yaml, servers-last.yaml - Update channel.ts test imports to reflect new fixture locations Addresses PR #5104 review comment about completion fixtures being mixed with validation fixtures. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

…es validation The lint rules for message payload type and operation messages type were producing false positive errors when $ref was used. During refraction, $ref creates a 'reference' element, but the validation rules only checked for specific element types like 'schema', 'multiFormatSchema', and 'message'. Added 'reference' to the allowed element types in both rules: - payload--type-3-0.ts: Now accepts multiFormatSchema, schema, or reference - messages--type.ts: Now accepts message or reference elements in arrays This eliminates false positives while maintaining proper validation for invalid types. Also added comprehensive tests to verify $ref usage doesn't trigger errors. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Consolidated duplicate $ref--no-siblings validation rules from individual AsyncAPI object directories (channel, message, operation, etc.) into a shared reference configuration. This fixes broken tests and reduces code duplication. Key changes: - Created shared reference/lint/$ref--no-siblings.ts with 'given' field specifying all element types: channel, channelBindings, correlationID, externalDocumentation, message, messageBindings, messageTrait, multiFormatSchema, operation, operationBindings, operationReply, operationReplyAddress, parameter, schema, securityScheme, server, serverBindings, serverVariable, tag - Registered namespace-level rules in config.ts for asyncapi and openapi - Fixed linterParams from [['$ref'], 'x-'] to [['$ref']] to match original behavior (no vendor extensions allowed alongside $ref) - Removed individual $ref--no-siblings.ts files from 17 object directories - Added test for message payload schema reference siblings validation This eliminates 15 failing tests while maintaining proper validation for AsyncAPI 2.x and 3.0 specifications. All 287 tests now pass. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Critical fixes: - Add missing error codes for new OAS 3.2 PATH_ITEM fields (7210000-7210201) - Add OPENAPI3_2_PARAMETER_FIELD_IN_EQUALS code (7200101) - Fix code collision in query--type.ts (was using Swagger 2.0 GET code) - Fix code collision in additional-operations files (were using servers code) - Fix code collision in parameter/in--equals-3-2.ts (was using OAS 3.0 code) - Fix wrong target field in license/identifier--type.ts (was 'name', now 'identifier') Linter function fixes: - Fix security--type.ts to use apilintElementOrClass instead of apilintType - Fix servers--type.ts to use apilintElementOrClass instead of apilintType - Fix tags--type.ts to use apilintElementOrClass instead of apilintType - Now validates semantic ApiDOM structure, not just primitive array types Message standardization: - Standardize all error messages with single quotes around field names - Update messages to follow PR #5104 patterns - Fix grammar in info--required.ts message (a → an) Code quality: - Remove unnecessary ESLint disable comments - Remove verbose header comments from request-body validation rules - Add inline RFC references where they provide context value All changes follow established patterns from PR #5104 AsyncAPI 3.0 review. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Replace selective property checking (.find(), .filter() with length checks) with comprehensive assert.deepEqual comparisons in 10 OAS 3.2 tests. Changes follow PR #5104 best practices and explicit reviewer feedback: "Why change it to this and not previous comparison of the entire diagnostics?" Updated test patterns: - Pattern 1: Complete diagnostic arrays with all properties (range, message, severity, code, source, data) - Pattern 2: Empty array comparisons for valid documents with new features - Pattern 3: Comprehensive assertions for variable diagnostic scenarios Benefits: - Catches regressions in all diagnostic properties - Documents expected behavior completely - Prevents partial validation mistakes - Aligns with project maintainer requirements Tests updated: - Missing title detection - $self field format validation - Tag fields support (summary, parent, kind) - Server name field support - Info summary field support - Response summary field support - Response summary type validation (with complete expected diagnostics) - Components mediaTypes field support - Components allowed fields validation (with complete expected diagnostics) - XML nodeType enum validation All 20 OAS 3.2 tests passing. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

ShikhaSaboo and others added 30 commits January 12, 2026 17:19

feat(apidom-ls): docs & config of compatible properties in AsyncAPI3

20ac4c1

feat(apidom-ls): docs and config in AsyncAPI-3

28357ac

chore: udpate channels comment

52bade2

chore(apidom-ls): resolve review comments

3ad34ab

chore(apidom-ls): resolve review comments

236f786

feat(ls): add AsyncAPI 3 validation for compatible keywords

890bed7

feat(ls): add validation for schema

a93c637

feat(ls): update names of rules with added async 3

4fa1a91

feat(ls): update names of async 2 rules for modified keywords

79eabad

fix(ls): use codes specific to AsyncAPI 3 Channel Object

2520d3e

test(ls): add first batch of tests

6a19332

test(ls): add second batch of tests

ed0e825

test(ls): add tests for Operation Bindings

b8388eb

test(ls): add tests for Message Bindings, adjust Operation Bindings

69dc495

test(ls): add tests for Message Example

6917c57

test(ls): add tests for Message Object

5c87861

test(ls): add tests for Message Trait

c995e4a

test(ls): add tests for Parameter Object

f2af7d2

test(ls): add tests for Operation Object

59f329a

test(ls): add tests for Operation Trait

dbae8ba

test(ls): add tests for Security Scheme Object

af92c53

fix(ls): add missing rules for channel ref

a8b3919

fix(ls): add missing Parameters Object validation

ea5996b

test(ls): include Server Variable ref test, fix channel test

dff28af

chore: resolve review comments

c8896b4

chore: lint fix

9d7a04d

Merge branch 'main' into feat/OSS-254/251-add-config-and-docs-for-asy…

3c9f64f

…ncapi3-with-compatible-properties

feat(ls): add AsyncAPI 3 completion for compatible keywords

17cd20c

test(ls): add completion tests

4ff806a

chore: add claude.md

5a1d57d

robert-hebel-sb and others added 4 commits February 4, 2026 16:38

robert-hebel-sb force-pushed the feat/oss-246-validation-for-async-3 branch from 172e6e4 to 1b4a9d0 Compare February 4, 2026 15:38

robert-hebel-sb and others added 5 commits February 4, 2026 16:45

fix(ls): adjust lint message

ce66071

Co-authored-by: Oliwia Rogala <oliwia.rogala@smartbear.com>

fix(ls): fix lint issues

e57af01

Merge remote-tracking branch 'origin/feat/oss-246-validation-for-asyn…

d46fee0

…c-3' into feat/oss-246-validation-for-async-3

test(ls): rename external docs ref variable for consistency

688eaca

Rename specExternalDocsRefValid to specExternalDocsRef to match the fixture file naming convention. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

robert-hebel-sb requested a review from glowcloud February 5, 2026 13:13

glowcloud reviewed Feb 6, 2026

View reviewed changes

robert-hebel-sb and others added 6 commits February 6, 2026 10:02

docs(ls): add OpenAPI 3.2.0 specification resource

842be66

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

docs(ls): add AsyncAPI 3.1.0 specification resource

eac9810

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

robert-hebel-sb requested a review from glowcloud February 6, 2026 09:56

test(ls): fix test expected string

34c0ad2

glowcloud approved these changes Feb 6, 2026

View reviewed changes

robert-hebel-sb and others added 5 commits February 6, 2026 17:46

chore(ls): fix lint

5e7f93a

Merge branch 'main' into feat/oss-246-validation-for-async-3

6fcf33a

robert-hebel-sb merged commit c201bb1 into main Feb 13, 2026
8 of 9 checks passed

robert-hebel-sb deleted the feat/oss-246-validation-for-async-3 branch February 13, 2026 10:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

feat(ls): add AsyncAPI 3 validation for new keywords #5104

feat(ls): add AsyncAPI 3 validation for new keywords #5104
robert-hebel-sb merged 107 commits intomainfrom
feat/oss-246-validation-for-async-3

robert-hebel-sb commented Jan 21, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

glowcloud Feb 6, 2026

Uh oh!

Uh oh!

glowcloud left a comment •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Comments

Conversation

robert-hebel-sb commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

Validation Rules Added

Error Codes

Test Coverage

Performance & Quality

Testing

References

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

glowcloud Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

glowcloud left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

robert-hebel-sb commented Jan 21, 2026 •

edited

Loading

glowcloud left a comment •

edited

Loading