feat(asyncapi): update to AsyncAPI 3.1.0

docs/getting-started/5-asyncapi.md

@@ -1,6 +1,6 @@
 # AsyncAPI Support
 
-Spectral has a built-in AsyncAPI [v2](https://v2.asyncapi.com/docs/reference/specification/v2.6.0) and [v3](https://www.asyncapi.com/docs/reference/specification/v3.0.0) ruleset that you can use to validate your AsyncAPI files.
+Spectral has a built-in AsyncAPI [v2](https://v2.asyncapi.com/docs/reference/specification/v2.6.0) and [v3](https://www.asyncapi.com/docs/reference/specification/v3.1.0) ruleset that you can use to validate your AsyncAPI files.
 
 Add `extends: "spectral:asyncapi"` to your ruleset file to apply rules for AsyncAPI v2 and v3.
 

docs/guides/4-custom-rulesets.md

@@ -33,6 +33,7 @@ Formats are an optional way to specify which API description formats a rule, or
 - `aas2_6` (AsyncAPI v2.6.0)
 - `aas3` (AsyncAPI v3.x)
 - `aas3_0` (AsyncAPI v3.0.0)
+- `aas3_1` (AsyncAPI v3.1.x)
 - `oas2` (OpenAPI v2.0)
 - `oas3` (OpenAPI v3.x)
 - `oas3_0` (OpenAPI v3.0.x)

docs/reference/asyncapi-rules.md

@@ -675,7 +675,7 @@ Channel servers must be defined in the `servers` object.
 **Bad Example**
 
 ```yaml
-asyncapi: "3.0.0"
+asyncapi: "3.1.0"
 info:
   title: Awesome API
   description: A very well-defined API
@@ -693,7 +693,7 @@ channels:
 **Good Example**
 
 ```yaml
-asyncapi: "3.0.0"
+asyncapi: "3.1.0"
 info:
   title: Awesome API
   description: A very well-defined API

packages/formats/src/__tests__/asyncapi.test.ts

@@ -1,4 +1,4 @@
-import { aas2, aas2_0, aas2_1, aas2_2, aas2_3, aas2_4, aas2_5, aas2_6, aas3, aas3_0 } from '../asyncapi';
+import { aas2, aas2_0, aas2_1, aas2_2, aas2_3, aas2_4, aas2_5, aas2_6, aas3, aas3_0, aas3_1 } from '../asyncapi';
 
 describe('AsyncAPI format', () => {
   describe('AsyncAPI 2.x', () => {
@@ -126,29 +126,41 @@ describe('AsyncAPI format', () => {
     });
   });
   describe('AsyncAPI 3.0', () => {
-    it.each(['3.0.0'])('recognizes %s version correctly', version => {
+    it.each(['3.0.0', '3.0.3'])('recognizes %s version correctly', version => {
       expect(aas3({ asyncapi: version }, null)).toBe(true);
     });
-    it.each(['3.0.0'])('recognizes %s version correctly', version => {
+    it.each(['3.0.0', '3.0.3'])('recognizes %s version correctly', version => {
       expect(aas3_0({ asyncapi: version }, null)).toBe(true);
     });
+  });
 
-    it.each([
-      '2',
-      '2.3',
-      '2.0.0',
-      '2.1.0',
-      '2.1.37',
-      '2.2.0',
-      '2.3.0',
-      '2.4.0',
-      '2.4.3',
-      '2.5.0',
-      '2.5.4',
-      '2.7.0',
-      '2.7.4',
-    ])('does not recognize %s version', version => {
-      expect(aas3({ asyncapi: version }, null)).toBe(false);
+  describe('AsyncAPI 3.1', () => {
+    it.each(['3.1.0', '3.1.3'])('recognizes %s version correctly', version => {
+      expect(aas3({ asyncapi: version }, null)).toBe(true);
+      expect(aas3_1({ asyncapi: version }, null)).toBe(true);
+    });
+
+    it.each(['3.0.0', '3.0.3', '3.2.0', '3', '3.1', '3.1.', '3.1.01'])('does not recognize %s version', version => {
+      expect(aas3_1({ asyncapi: version }, null)).toBe(false);
+    });
+  });
+
+  describe('AsyncAPI 3.x', () => {
+    it.each(['3.2.0', '3.27.4'])('recognizes future %s versions correctly', version => {
+      expect(aas3({ asyncapi: version }, null)).toBe(true);
+      expect(aas3_0({ asyncapi: version }, null)).toBe(false);
+      expect(aas3_1({ asyncapi: version }, null)).toBe(false);
+    });
+
+    it.each(['2', '2.3', '2.0.0', '2.7.4', '3', '3.0', '3.1', '3.1.01', '4.0.0'])(
+      'does not recognize %s version',
+      version => {
+        expect(aas3({ asyncapi: version }, null)).toBe(false);
+      },
+    );
+
+    it('does not recognize an AsyncAPI 3.1 document as AsyncAPI 3.0', () => {
+      expect(aas3_0({ asyncapi: '3.1.0' }, null)).toBe(false);
     });
   });
 });

packages/formats/src/asyncapi.ts

@@ -14,6 +14,7 @@ const aas2_4Regex = /^2\.4(?:\.[0-9]*)?$/;
 const aas2_5Regex = /^2\.5(?:\.[0-9]*)?$/;
 const aas2_6Regex = /^2\.6(?:\.[0-9]*)?$/;
 const aas3_0Regex = /^3\.0(?:\.[0-9]*)?$/;
+const aas3_1Regex = /^3\.1(?:\.[0-9]*)?$/;
 
 const isAas2 = (document: unknown): document is { asyncapi: string } & Record<string, unknown> =>
   isPlainObject(document) && 'asyncapi' in document && aas2Regex.test(String((document as MaybeAAS2).asyncapi));
@@ -61,3 +62,7 @@ aas2_6.displayName = 'AsyncAPI 2.6.x';
 export const aas3_0: Format = (document: unknown): boolean =>
   isAas3(document) && aas3_0Regex.test(String((document as MaybeAAS3).asyncapi));
 aas3_0.displayName = 'AsyncAPI 3.0.x';
+
+export const aas3_1: Format = (document: unknown): boolean =>
+  isAas3(document) && aas3_1Regex.test(String((document as MaybeAAS3).asyncapi));
+aas3_1.displayName = 'AsyncAPI 3.1.x';

packages/rulesets/src/asyncapi/__tests__/asyncapi-3-document-resolved.test.ts

@@ -13,6 +13,109 @@ testRule('asyncapi-3-document-resolved', [
     },
     errors: [],
   },
+  {
+    name: 'valid AsyncAPI 3.1 document with resolved references and ROS 2 bindings',
+    document: {
+      asyncapi: '3.1.0',
+      info: {
+        title: 'Turtle telemetry',
+        version: '1.0.0',
+      },
+      servers: {
+        development: {
+          host: 'localhost',
+          protocol: 'ros2',
+          bindings: {
+            ros2: {
+              domainId: 0,
+              rmwImplementation: 'rmw_fastrtps_cpp',
+            },
+          },
+        },
+      },
+      channels: {
+        turtlePose: {
+          address: 'turtle/pose',
+          messages: {
+            TurtlePose: {
+              payload: {
+                type: 'object',
+              },
+            },
+          },
+        },
+      },
+      operations: {
+        publishPose: {
+          action: 'send',
+          channel: {
+            $ref: '#/channels/turtlePose',
+          },
+          messages: [{ $ref: '#/channels/turtlePose/messages/TurtlePose' }],
+          bindings: {
+            ros2: {
+              node: '/turtlesim',
+              role: 'publisher',
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'AsyncAPI 3.0 rejects ROS 2 bindings that are introduced in 3.1',
+    document: {
+      asyncapi: '3.0.0',
+      info: {
+        title: 'Turtle telemetry',
+        version: '1.0.0',
+      },
+      servers: {
+        development: {
+          host: 'localhost',
+          protocol: 'ros2',
+          bindings: {
+            ros2: {
+              domainId: 0,
+            },
+          },
+        },
+      },
+    },
+    errors: [
+      {
+        message: 'Property "ros2" is not expected to be here',
+        path: ['servers', 'development', 'bindings', 'ros2'],
+        severity: DiagnosticSeverity.Error,
+      },
+    ],
+  },
+  {
+    name: 'invalid AsyncAPI 3.1 info property is missing',
+    document: {
+      asyncapi: '3.1.0',
+    },
+    errors: [{ message: 'Object must have required property "info"', severity: DiagnosticSeverity.Error }],
+  },
+  {
+    name: 'valid future AsyncAPI 3.x document uses the latest known schema as fallback',
+    document: {
+      asyncapi: '3.2.0',
+      info: {
+        title: 'Future AsyncAPI document',
+        version: '1.0.0',
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'invalid future AsyncAPI 3.x document is validated by the fallback schema',
+    document: {
+      asyncapi: '3.2.0',
+    },
+    errors: [{ message: 'Object must have required property "info"', severity: DiagnosticSeverity.Error }],
+  },
   {
     name: 'valid case resolved case message',
     document: {

packages/rulesets/src/asyncapi/__tests__/asyncapi-3-document-unresolved.test.ts

@@ -13,6 +13,48 @@ testRule('asyncapi-3-document-unresolved', [
     },
     errors: [],
   },
+  {
+    name: 'invalid AsyncAPI 3.1 reference for info object is not allowed',
+    document: {
+      asyncapi: '3.1.0',
+      info: {
+        $ref: '#/components/x-titles/someTitle',
+      },
+      components: {
+        'x-titles': {
+          someTitle: 'some-title',
+        },
+      },
+    },
+    errors: [
+      {
+        message: 'Referencing in this place is not allowed',
+        path: ['info'],
+        severity: DiagnosticSeverity.Error,
+      },
+    ],
+  },
+  {
+    name: 'invalid reference in a future AsyncAPI 3.x document is validated by the fallback schema',
+    document: {
+      asyncapi: '3.2.0',
+      info: {
+        $ref: '#/components/x-titles/someTitle',
+      },
+      components: {
+        'x-titles': {
+          someTitle: 'some-title',
+        },
+      },
+    },
+    errors: [
+      {
+        message: 'Referencing in this place is not allowed',
+        path: ['info'],
+        severity: DiagnosticSeverity.Error,
+      },
+    ],
+  },
   {
     name: 'valid case unresolved case message',
     document: {

packages/rulesets/src/asyncapi/__tests__/asyncapi-3-tags.test.ts

@@ -26,4 +26,18 @@ testRule('asyncapi-3-tags', [
       },
     ],
   },
+  {
+    name: 'info tags property is missing in AsyncAPI 3.1',
+    document: {
+      asyncapi: '3.1.0',
+      info: {},
+    },
+    errors: [
+      {
+        message: 'AsyncAPI document must have non-empty "tags" array.',
+        path: ['info'],
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
 ]);

packages/rulesets/src/asyncapi/__tests__/asyncapi-latest-version.test.ts

@@ -1,12 +1,11 @@
 import { DiagnosticSeverity } from '@stoplight/types';
-import { latestVersion } from '../functions/utils/specs';
 import testRule from './__helpers__/tester';
 
 testRule('asyncapi-latest-version', [
   {
     name: 'valid case',
     document: {
-      asyncapi: latestVersion,
+      asyncapi: '3.1.0',
     },
     errors: [],
   },
@@ -18,7 +17,7 @@ testRule('asyncapi-latest-version', [
     },
     errors: [
       {
-        message: `The latest version is not used. You should update to the "${latestVersion}" version.`,
+        message: 'The latest version is not used. You should update to the "3.1.0" version.',
         path: ['asyncapi'],
         severity: DiagnosticSeverity.Information,
       },

packages/rulesets/src/asyncapi/functions/__tests__/asyncApiPayloadValidation.test.ts

@@ -1,10 +1,10 @@
-import { aas2_0 } from '@stoplight/spectral-formats';
+import { aas2_0, aas3, aas3_1 } from '@stoplight/spectral-formats';
 import asyncApiPayloadValidation from '../asyncApiPayloadValidation';
 
-function runPayloadValidation(targetVal: any) {
+function runPayloadValidation(targetVal: any, format = aas2_0) {
   return asyncApiPayloadValidation(targetVal, null, {
     path: ['components', 'messages', 'aMessage'],
-    document: { formats: new Set([aas2_0]) },
+    document: { formats: new Set([format]) },
   } as any);
 }
 
@@ -24,4 +24,38 @@ describe('asyncApiPayloadValidation', () => {
       },
     ]);
   });
+
+  test('validates payloads against the AsyncAPI 3.1 schema object definition', () => {
+    const results = runPayloadValidation(
+      {
+        type: 'object',
+        deprecated: 14,
+      },
+      aas3_1,
+    );
+
+    expect(results).toEqual([
+      {
+        message: '"deprecated" property type must be boolean',
+        path: ['components', 'messages', 'aMessage', 'deprecated'],
+      },
+    ]);
+  });
+
+  test('uses the latest known AsyncAPI 3.x schema object definition as fallback', () => {
+    const results = runPayloadValidation(
+      {
+        type: 'object',
+        deprecated: 14,
+      },
+      aas3,
+    );
+
+    expect(results).toEqual([
+      {
+        message: '"deprecated" property type must be boolean',
+        path: ['components', 'messages', 'aMessage', 'deprecated'],
+      },
+    ]);
+  });
 });