feat!: add support for AsyncAPI v3

README.md

@@ -214,9 +214,10 @@ Parser-JS API implements a global API definition for all AsyncAPI parser impleme
 
 The following table shows a compatibility matrix between this parser, and the [Parser-API](https://github.com/asyncapi/parser-api), as well as the AsyncAPI spec version supported by each release of this parser.
 
-| Parser-JS | Parser-API                                                           | Spec 2.x |
-|-----------|----------------------------------------------------------------------|----------|
-| 2.x       | [1.x](https://github.com/asyncapi/parser-api/blob/master/docs/v1.md) | ✓        |
+| Parser-JS | Parser-API                                                            | Spec 2.x | Spec 3.x |
+|-----------|-----------------------------------------------------------------------|----------|----------|
+| 2.x       | [1.x](https://github.com/asyncapi/parser-api/blob/v1.0.0/docs/v1.md)  | ✓        |          |
+| 3.x       | [3.x](https://github.com/asyncapi/parser-api/blob/v3.0.0/docs/api.md) | ✓        | ✓        |
 
 - `✓` Fully supported version.
 - `-` The AsyncAPI Spec version has features the Parser-JS can't use but the rest are fully supported.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asyncapi/parser",
-  "version": "2.1.0",
+  "version": "3.0.0-next-major-spec.13",
   "description": "JavaScript AsyncAPI parser.",
   "bugs": {
     "url": "https://github.com/asyncapi/parser-js/issues"
@@ -41,7 +41,7 @@
     "prepublishOnly": "npm run generate:assets"
   },
   "dependencies": {
-    "@asyncapi/specs": "^5.1.0",
+    "@asyncapi/specs": "^6.0.0-next-major-spec.9",
     "@openapi-contrib/openapi-schema-to-json-schema": "~3.2.0",
     "@stoplight/json-ref-resolver": "^3.1.5",
     "@stoplight/spectral-core": "^1.16.1",

src/custom-operations/anonymous-naming.ts

@@ -1,6 +1,6 @@
 import { xParserMessageName, xParserSchemaId } from '../constants';
 import { traverseAsyncApiDocument } from '../iterator';
-import { setExtension } from '../utils';
+import { setExtension, setExtensionOnJson } from '../utils';
 
 import type { 
   AsyncAPIDocumentInterface,
@@ -59,12 +59,15 @@ function assignUidToComponentSchemas(document: AsyncAPIDocumentInterface) {
     setExtension(xParserSchemaId, schema.id(), schema);
   });
 }
-  
+
 function assignUidToAnonymousSchemas(doc: AsyncAPIDocumentInterface) {
   let anonymousSchemaCounter = 0;
   function callback(schema: SchemaInterface) {
+    const json = schema.json() as any;
+    const isMultiFormatSchema = json.schema !== undefined;
+    const underlyingSchema = isMultiFormatSchema ? json.schema : json;
     if (!schema.id()) {
-      setExtension(xParserSchemaId, `<anonymous-schema-${++anonymousSchemaCounter}>`, schema);
+      setExtensionOnJson(xParserSchemaId, `<anonymous-schema-${++anonymousSchemaCounter}>`, underlyingSchema);
     }
   }
   traverseAsyncApiDocument(doc, callback);

src/custom-operations/apply-traits.ts

@@ -2,7 +2,7 @@ import { JSONPath } from 'jsonpath-plus';
 
 import { mergePatch } from '../utils';
 
-import type { v2 } from '../spec-types';
+import type { v2, v3 } from '../spec-types';
 
 const v2TraitPaths = [
   // operations
@@ -17,26 +17,54 @@ const v2TraitPaths = [
 ];
 
 export function applyTraitsV2(asyncapi: v2.AsyncAPIObject) {
-  applyAllTraits(asyncapi, v2TraitPaths);
+  applyAllTraitsV2(asyncapi, v2TraitPaths);
+}
+
+function applyAllTraitsV2(asyncapi: Record<string, any>, paths: string[]) {
+  const visited: Set<unknown> = new Set();
+  paths.forEach(path => {
+    JSONPath({
+      path,
+      json: asyncapi,
+      resultType: 'value',
+      callback(value) {
+        if (visited.has(value)) {
+          return;
+        }
+        visited.add(value);
+        applyTraitsToObjectV2(value);
+      },
+    });
+  });
+}
+
+function applyTraitsToObjectV2(value: Record<string, unknown>) {
+  if (Array.isArray(value.traits)) {
+    for (const trait of value.traits) {
+      for (const key in trait) {
+        value[String(key)] = mergePatch(value[String(key)], trait[String(key)]);
+      }
+    }
+  }
 }
 
 const v3TraitPaths = [
   // operations
-  '$.channels.*.[publish,subscribe]',
-  '$.components.channels.*.[publish,subscribe]',
+  '$.operations.*',
+  '$.components.operations.*',
   // messages
-  '$.channels.*.[publish,subscribe].message',
-  '$.channels.*.[publish,subscribe].message.oneOf.*',
-  '$.components.channels.*.[publish,subscribe].message',
-  '$.components.channels.*.[publish,subscribe].message.oneOf.*',
+  '$.channels.*.messages.*',
+  '$.operations.*.messages.*',
+  '$.components.channels.*.messages.*',
+  '$.components.operations.*.messages.*',
   '$.components.messages.*',
 ];
 
-export function applyTraitsV3(asyncapi: v2.AsyncAPIObject) { // TODO: Change type when we will have implemented types for v3
-  applyAllTraits(asyncapi, v3TraitPaths);
+export function applyTraitsV3(asyncapi: v3.AsyncAPIObject) {
+  applyAllTraitsV3(asyncapi, v3TraitPaths);
 }
 
-function applyAllTraits(asyncapi: Record<string, any>, paths: string[]) {
+function applyAllTraitsV3(asyncapi: Record<string, any>, paths: string[]) {
   const visited: Set<unknown> = new Set();
   paths.forEach(path => {
     JSONPath({
@@ -48,18 +76,28 @@ function applyAllTraits(asyncapi: Record<string, any>, paths: string[]) {
           return;
         }
         visited.add(value);
-        applyTraits(value);
+        applyTraitsToObjectV3(value);
       },
     });
   });
 }
 
-function applyTraits(value: Record<string, unknown> & { traits?: any[] }) {
-  if (Array.isArray(value.traits)) {
-    for (const trait of value.traits) {
-      for (const key in trait) {
-        value[String(key)] = mergePatch(value[String(key)], trait[String(key)]);
-      }
+function applyTraitsToObjectV3(value: Record<string, unknown>) {
+  if (!Array.isArray(value.traits)) {
+    return;
+  }
+
+  // shallow copy of object
+  const copy = { ...value };
+  // reset the object but preserve the reference
+  for (const key in value) {
+    delete value[key];
+  }
+
+  // merge root object at the end
+  for (const trait of [...copy.traits as any[], copy]) {
+    for (const key in trait) {
+      value[String(key)] = mergePatch(value[String(key)], trait[String(key)]);
     }
   }
-}
+}

src/custom-operations/index.ts

@@ -1,33 +1,52 @@
-import { applyTraitsV2 } from './apply-traits';
+import { applyTraitsV2, applyTraitsV3 } from './apply-traits';
 import { resolveCircularRefs } from './resolve-circular-refs';
-import { parseSchemasV2 } from './parse-schema';
+import { parseSchemasV2, parseSchemasV3 } from './parse-schema';
 import { anonymousNaming } from './anonymous-naming';
 
 import type { RulesetFunctionContext } from '@stoplight/spectral-core';
 import type { Parser } from '../parser';
 import type { ParseOptions } from '../parse';
 import type { AsyncAPIDocumentInterface } from '../models';
 import type { DetailedAsyncAPI } from '../types';
+import type { v2, v3 } from '../spec-types';
+import { checkCircularRefs } from './check-circular-refs';
 
 export async function customOperations(parser: Parser, document: AsyncAPIDocumentInterface, detailed: DetailedAsyncAPI, inventory: RulesetFunctionContext['documentInventory'], options: ParseOptions): Promise<void> {
   switch (detailed.semver.major) {
   case 2: return operationsV2(parser, document, detailed, inventory, options);
-  // case 3: return operationsV3(parser, document, detailed, options);
+  case 3: return operationsV3(parser, document, detailed, inventory, options);
   }
 }
 
 async function operationsV2(parser: Parser, document: AsyncAPIDocumentInterface, detailed: DetailedAsyncAPI, inventory: RulesetFunctionContext['documentInventory'], options: ParseOptions): Promise<void> {
+  checkCircularRefs(document);
+
   if (options.applyTraits) {
-    applyTraitsV2(detailed.parsed);
+    applyTraitsV2(detailed.parsed as v2.AsyncAPIObject);
   }
   if (options.parseSchemas) {
     await parseSchemasV2(parser, detailed);
   }
 
-  // anonymous naming and resolving circular refrences should be done after custom schemas parsing
+  // anonymous naming and resolving circular references should be done after custom schemas parsing
   if (inventory) {
     resolveCircularRefs(document, inventory);
   }
   anonymousNaming(document);
 }
 
+async function operationsV3(parser: Parser, document: AsyncAPIDocumentInterface, detailed: DetailedAsyncAPI, inventory: RulesetFunctionContext['documentInventory'], options: ParseOptions): Promise<void> {
+  checkCircularRefs(document);
+
+  if (options.applyTraits) {
+    applyTraitsV3(detailed.parsed as v3.AsyncAPIObject);
+  }
+  if (options.parseSchemas) {
+    await parseSchemasV3(parser, detailed);
+  }
+  // anonymous naming and resolving circular references should be done after custom schemas parsing
+  if (inventory) {
+    resolveCircularRefs(document, inventory);
+  }
+  anonymousNaming(document);
+}

src/custom-operations/parse-schema.ts

@@ -22,6 +22,24 @@ const customSchemasPathsV2 = [
   '$.components.messages.*',
 ];
 
+const customSchemasPathsV3 = [
+  // channels
+  '$.channels.*.messages.*.payload',
+  '$.channels.*.messages.*.headers',
+  '$.components.channels.*.messages.*.payload',
+  '$.components.channels.*.messages.*.headers',
+  // operations
+  '$.operations.*.messages.*.payload',
+  '$.operations.*.messages.*.headers',
+  '$.components.operations.*.messages.*.payload',
+  '$.components.operations.*.messages.*.headers',
+  // messages
+  '$.components.messages.*.payload',
+  '$.components.messages.*.headers.*',
+  // schemas 
+  '$.components.schemas.*',
+];
+
 export async function parseSchemasV2(parser: Parser, detailed: DetailedAsyncAPI) {
   const defaultSchemaFormat = getDefaultSchemaFormat(detailed.semver.version);
   const parseItems: Array<ToParseItem> = [];
@@ -65,6 +83,68 @@ export async function parseSchemasV2(parser: Parser, detailed: DetailedAsyncAPI)
   return Promise.all(parseItems.map(item => parseSchemaV2(parser, item)));
 }
 
+export async function parseSchemasV3(parser: Parser, detailed: DetailedAsyncAPI) {
+  const defaultSchemaFormat = getDefaultSchemaFormat(detailed.semver.version);
+  const parseItems: Array<ToParseItem> = [];
+
+  const visited: Set<unknown> = new Set();
+  customSchemasPathsV3.forEach(path => {
+    JSONPath({
+      path,
+      json: detailed.parsed,
+      resultType: 'all',
+      callback(result) {
+        const value = result.value;
+        if (visited.has(value)) {
+          return;
+        }
+        visited.add(value);
+
+        const schema = value.schema;
+        if (!schema) {
+          return;
+        }
+
+        let schemaFormat = value.schemaFormat;
+        if (!schemaFormat) {
+          return;
+        }
+        schemaFormat = getSchemaFormat(value.schemaFormat, detailed.semver.version);
+
+        parseItems.push({
+          input: {
+            asyncapi: detailed,
+            data: schema,
+            meta: {
+              message: value,
+            },
+            path: [...splitPath(result.path), 'schema'],
+            schemaFormat,
+            defaultSchemaFormat,
+          },
+          value,
+        });
+      },
+    });
+  });
+
+  return Promise.all(parseItems.map(item => parseSchemaV3(parser, item)));
+}
+
+async function parseSchemaV3(parser: Parser, item: ToParseItem) {
+  const originalData = item.input.data;
+  const parsedData = await parseSchema(parser, item.input);
+  if (item.value?.schema !== undefined) {
+    item.value.schema = parsedData;
+  } else {
+    item.value = parsedData;
+  }
+  // save original payload only when data is different (returned by custom parsers)
+  if (originalData !== parsedData) {
+    item.value[xParserOriginalPayload] = originalData;
+  }
+}
+
 async function parseSchemaV2(parser: Parser, item: ToParseItem) {
   const originalData = item.input.data;
   const parsedData = item.value.payload = await parseSchema(parser, item.input);

src/document.ts

@@ -1,4 +1,4 @@
-import { AsyncAPIDocumentV2, AsyncAPIDocumentV3 } from './models';
+import { AsyncAPIDocumentV2, AsyncAPIDocumentV3, ParserAPIVersion } from './models';
 import { unstringify } from './stringify';
 import { createDetailedAsyncAPI } from './utils';
 
@@ -11,13 +11,14 @@ import {
 import type { AsyncAPIDocumentInterface } from './models';
 import type { OldAsyncAPIDocument } from './old-api';
 import type { DetailedAsyncAPI, AsyncAPIObject } from './types';
+import { v2, v3 } from 'spec-types';
 
 export function createAsyncAPIDocument(asyncapi: DetailedAsyncAPI): AsyncAPIDocumentInterface {
   switch (asyncapi.semver.major) {
   case 2:
-    return new AsyncAPIDocumentV2(asyncapi.parsed, { asyncapi, pointer: '/' });
-    // case 3:
-    //   return new AsyncAPIDocumentV3(asyncapi.parsed, { asyncapi, pointer: '/' });
+    return new AsyncAPIDocumentV2(asyncapi.parsed as v2.AsyncAPIObject, { asyncapi, pointer: '/' });
+  case 3:
+    return new AsyncAPIDocumentV3(asyncapi.parsed as v3.AsyncAPIObject, { asyncapi, pointer: '/' });
   default:
     throw new Error(`Unsupported AsyncAPI version: ${asyncapi.semver.version}`);
   }
@@ -42,7 +43,7 @@ export function isAsyncAPIDocument(maybeDoc: unknown): maybeDoc is AsyncAPIDocum
   }
   if (maybeDoc && typeof (maybeDoc as AsyncAPIDocumentInterface).json === 'function') {
     const versionOfParserAPI = (maybeDoc as AsyncAPIDocumentInterface).json()[xParserApiVersion];
-    return versionOfParserAPI === 1;
+    return versionOfParserAPI === ParserAPIVersion;
   }
   return false;
 }

src/models/asyncapi.ts

@@ -9,9 +9,12 @@ import type { SchemasInterface } from './schemas';
 import type { SecuritySchemesInterface } from './security-schemes';
 import type { ServersInterface } from './servers';
 
-import type { v2 } from '../spec-types';
+import type { v2, v3 } from '../spec-types';
 
-export interface AsyncAPIDocumentInterface extends BaseModel<v2.AsyncAPIObject>, ExtensionsMixinInterface {
+// https://github.com/asyncapi/parser-api/releases/tag/v3.0.0
+export const ParserAPIVersion = 3;
+
+export interface AsyncAPIDocumentInterface extends BaseModel<v2.AsyncAPIObject | v3.AsyncAPIObject>, ExtensionsMixinInterface {
   version(): string;
   defaultContentType(): string | undefined;
   hasDefaultContentType(): boolean;

src/models/channel.ts

@@ -7,7 +7,7 @@ import type { ServersInterface } from './servers';
 
 export interface ChannelInterface extends BaseModel, BindingsMixinInterface, DescriptionMixinInterface, ExtensionsMixinInterface {
   id(): string;
-  address(): string;
+  address(): string | null | undefined;
   servers(): ServersInterface;
   operations(): OperationsInterface;
   messages(): MessagesInterface;

src/models/external-documentation.ts

@@ -0,0 +1,9 @@
+import type { BaseModel } from './base';
+import type { DescriptionMixinInterface, ExtensionsMixinInterface } from './mixins';
+
+export interface ExternalDocumentationInterface 
+  extends BaseModel, DescriptionMixinInterface, ExtensionsMixinInterface {
+
+  id(): string | undefined;
+  url(): string;
+}