@scalar/asyncapi-validator 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @scalar/asyncapi-validator
+
+## 0.1.0
+
+### Minor Changes
+
+- [#9967](https://github.com/scalar/scalar/pull/9967): Add `@scalar/asyncapi-validator`, a package that validates AsyncAPI documents (2.x and 3.x) against the AsyncAPI Specification. It is built on `@scalar/json-schema-validator` and uses the official schemas from `@asyncapi/specs`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present Scalar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# Scalar AsyncAPI Validator
+
+[![Version](https://img.shields.io/npm/v/%40scalar/asyncapi-validator)](https://www.npmjs.com/package/@scalar/asyncapi-validator)
+[![Downloads](https://img.shields.io/npm/dm/%40scalar/asyncapi-validator)](https://www.npmjs.com/package/@scalar/asyncapi-validator)
+[![License](https://img.shields.io/npm/l/%40scalar%2Fasyncapi-validator)](https://www.npmjs.com/package/@scalar/asyncapi-validator)
+[![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
+
+Validate AsyncAPI documents against the AsyncAPI Specification. Supports AsyncAPI 2.x and 3.x.
+
+Built on [`@scalar/json-schema-validator`](https://www.npmjs.com/package/@scalar/json-schema-validator), using the official schemas from [`@asyncapi/specs`](https://www.npmjs.com/package/@asyncapi/specs).
+
+---
+
+Scalar is an open-source API platform for teams who want beautiful developer interfaces without vendor lock-in.
+
+- **[API References](https://scalar.com/products/api-references/getting-started)** — Interactive API documentation from OpenAPI and AsyncAPI specs.
+- **[Developer Docs](https://scalar.com/products/docs/getting-started)** — Write in Markdown/MDX, generate API references, sync with two-way Git.
+- **[SDK Generator](https://scalar.com/products/sdk-generator/getting-started)** — Type-safe SDKs and CLIs in TypeScript, Python, Go, PHP, Java, and Ruby.
+- **[API Client](https://scalar.com/products/api-client/getting-started)** — Open-source, offline-first Postman alternative built on OpenAPI.
+
+20M+ monthly npm installs · 15,500+ GitHub stars · MIT licensed · [scalar.com](https://scalar.com)
+
+---
+
+## Installation
+
+```bash
+npm add @scalar/asyncapi-validator
+```
+
+## Usage
+
+Pass a JSON string, a YAML string, or an object:
+
+```ts
+import { validate } from '@scalar/asyncapi-validator'
+
+const result = validate({
+  asyncapi: '3.0.0',
+  info: {
+    title: 'Hello World',
+    version: '1.0.0',
+  },
+})
+
+console.log(result.valid)
+
+if (!result.valid) {
+  console.log(result.errors)
+}
+```
+
+The AsyncAPI version is read from the document's `asyncapi` field, and the matching schema is chosen automatically.
+
+### Schema-level validation
+
+This is schema-level validation. As the AsyncAPI project notes, JSON Schema alone cannot express every rule of the specification, so a valid result here does not guarantee a semantically complete document.
+
+### Throw on error
+
+```ts
+import { validate } from '@scalar/asyncapi-validator'
+
+try {
+  validate(document, { throwOnError: true })
+} catch (error) {
+  // Handle the first validation error
+}
+```
+
+## Community
+
+We are API nerds. You too? Let's chat on Discord: <https://discord.gg/scalar>
+
+## License
+
+The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).

package/dist/detect-version.d.ts

@@ -0,0 +1,16 @@
+import { type AsyncApiVersion } from './specifications.js';
+/**
+ * Detects the AsyncAPI version of a document by reading its top-level `asyncapi`
+ * field (a version string like `"3.0.0"`).
+ *
+ * We keep one schema per minor version, so any patch release validates against
+ * its minor: `3.1.4` is checked against the `3.1.0` schema. Returns the matching
+ * supported version, or `undefined` when none exists.
+ *
+ * The fallback matches on major and minor only, so a prerelease like `3.0.0-rc1`
+ * also resolves to `3.0.0`. That is deliberate — there are no prerelease schemas
+ * to validate against — but it means the returned version can be more precise
+ * than the document's own `asyncapi` field.
+ */
+export declare function detectVersion(document: unknown): AsyncApiVersion | undefined;
+//# sourceMappingURL=detect-version.d.ts.map

package/dist/detect-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-version.d.ts","sourceRoot":"","sources":["../src/detect-version.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,kBAAkB,CAAA;AAEzE;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAwB5E"}

package/dist/detect-version.js

@@ -0,0 +1,34 @@
+import { isObject } from '@scalar/helpers/object/is-object';
+import { AsyncApiVersions } from './specifications.js';
+/**
+ * Detects the AsyncAPI version of a document by reading its top-level `asyncapi`
+ * field (a version string like `"3.0.0"`).
+ *
+ * We keep one schema per minor version, so any patch release validates against
+ * its minor: `3.1.4` is checked against the `3.1.0` schema. Returns the matching
+ * supported version, or `undefined` when none exists.
+ *
+ * The fallback matches on major and minor only, so a prerelease like `3.0.0-rc1`
+ * also resolves to `3.0.0`. That is deliberate — there are no prerelease schemas
+ * to validate against — but it means the returned version can be more precise
+ * than the document's own `asyncapi` field.
+ */
+export function detectVersion(document) {
+    if (!isObject(document)) {
+        return undefined;
+    }
+    const version = document.asyncapi;
+    if (typeof version !== 'string') {
+        return undefined;
+    }
+    // Exact match first (the common case).
+    if (AsyncApiVersions.includes(version)) {
+        return version;
+    }
+    // Otherwise fall back to the schema for the same major.minor.
+    const [major, minor] = version.split('.');
+    return AsyncApiVersions.find((supported) => {
+        const [supportedMajor, supportedMinor] = supported.split('.');
+        return supportedMajor === major && supportedMinor === minor;
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Error messages used by the validator.
+ *
+ * Kept local to this package on purpose: error messages should live where they
+ * are used and be copied rather than imported across packages.
+ */
+export declare const ERRORS: {
+    readonly EMPTY_OR_INVALID: "Can't find JSON, YAML or filename in data.";
+    readonly ASYNCAPI_VERSION_NOT_SUPPORTED: "Can't find a supported AsyncAPI version in the provided document, the `asyncapi` field must be a supported version string.";
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,MAAM;;;CAIT,CAAA"}

package/dist/errors.js

@@ -0,0 +1,10 @@
+/**
+ * Error messages used by the validator.
+ *
+ * Kept local to this package on purpose: error messages should live where they
+ * are used and be copied rather than imported across packages.
+ */
+export const ERRORS = {
+    EMPTY_OR_INVALID: "Can't find JSON, YAML or filename in data.",
+    ASYNCAPI_VERSION_NOT_SUPPORTED: "Can't find a supported AsyncAPI version in the provided document, the `asyncapi` field must be a supported version string.",
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { AsyncApiVersions as supportedVersions } from './specifications.js';
+export type { AsyncApiVersion, ErrorObject, ThrowOnErrorOption, ValidationOutcome } from './types.js';
+export { type ValidateOptions, validate } from './validate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,IAAI,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACxE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAClG,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { AsyncApiVersions as supportedVersions } from './specifications.js';
+export { validate } from './validate.js';

package/dist/specifications.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The AsyncAPI versions supported by the validator.
+ *
+ * When `@asyncapi/specs` adds a new version, add it here and bump the dependency.
+ */
+export type AsyncApiVersion = '2.0.0' | '2.1.0' | '2.2.0' | '2.3.0' | '2.4.0' | '2.5.0' | '2.6.0' | '3.0.0' | '3.1.0';
+/**
+ * The AsyncAPI JSON Schemas keyed by version, sourced from `@asyncapi/specs`.
+ *
+ * These are bundled and self-contained, so Ajv can compile each one without
+ * resolving external files.
+ *
+ * We use the "without $id" variant on purpose: the standard bundle embeds the
+ * draft-07 meta-schema with its own `$id`, which collides with Ajv's built-in
+ * draft-07 ("reference resolves to more than one schema"). The `$id`-free
+ * variant compiles cleanly while still resolving every internal reference.
+ *
+ * The cast keeps the emitted declarations from depending on `@asyncapi/specs`'
+ * transitive `@types/json-schema`.
+ */
+export declare const AsyncApiSpecifications: Record<AsyncApiVersion, Record<string, unknown>>;
+export declare const AsyncApiVersions: AsyncApiVersion[];
+//# sourceMappingURL=specifications.d.ts.map

package/dist/specifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specifications.d.ts","sourceRoot":"","sources":["../src/specifications.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAA;AAErH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,EAAgD,MAAM,CACvF,eAAe,EACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACxB,CAAA;AAED,eAAO,MAAM,gBAAgB,EAA0C,eAAe,EAAE,CAAA"}

package/dist/specifications.js

@@ -0,0 +1,17 @@
+import asyncapiSpecs from '@asyncapi/specs';
+/**
+ * The AsyncAPI JSON Schemas keyed by version, sourced from `@asyncapi/specs`.
+ *
+ * These are bundled and self-contained, so Ajv can compile each one without
+ * resolving external files.
+ *
+ * We use the "without $id" variant on purpose: the standard bundle embeds the
+ * draft-07 meta-schema with its own `$id`, which collides with Ajv's built-in
+ * draft-07 ("reference resolves to more than one schema"). The `$id`-free
+ * variant compiles cleanly while still resolving every internal reference.
+ *
+ * The cast keeps the emitted declarations from depending on `@asyncapi/specs`'
+ * transitive `@types/json-schema`.
+ */
+export const AsyncApiSpecifications = asyncapiSpecs.schemasWithoutId;
+export const AsyncApiVersions = Object.keys(AsyncApiSpecifications);

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+import type { ValidationOutcome as GenericValidationOutcome } from '@scalar/json-schema-validator';
+import type { AsyncApiVersion } from './specifications.js';
+export type { ErrorObject } from '@scalar/json-schema-validator';
+export type { AsyncApiVersion } from './specifications.js';
+export type ThrowOnErrorOption = {
+    /**
+     * If `true`, the function will throw an error if the document is invalid.
+     *
+     * @default false
+     */
+    throwOnError?: boolean;
+};
+/**
+ * The result of validating an AsyncAPI document.
+ */
+export type ValidationOutcome = GenericValidationOutcome<AsyncApiVersion>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,IAAI,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAElG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEvD,YAAY,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAEhE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEvD,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,wBAAwB,CAAC,eAAe,CAAC,CAAA"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,17 @@
+import type { AnyObject } from '@scalar/types/utils';
+import type { ThrowOnErrorOption, ValidationOutcome } from './types.js';
+export type ValidateOptions = ThrowOnErrorOption;
+/**
+ * Validates a single AsyncAPI document against the AsyncAPI Specification.
+ *
+ * Schema validation is delegated to `@scalar/json-schema-validator`; version
+ * detection is AsyncAPI-specific.
+ *
+ * This is schema-level validation. As the AsyncAPI project notes, JSON Schema
+ * alone cannot express every rule of the specification, so a valid result here
+ * does not guarantee a semantically complete document.
+ *
+ * @param document - A JSON string, a YAML string, or an object.
+ */
+export declare function validate(document: string | AnyObject, options?: ValidateOptions): ValidationOutcome;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAKpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAEpE,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAA;AAchD;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,iBAAiB,CAEnG"}

package/dist/validate.js

@@ -0,0 +1,29 @@
+import { createSpecificationValidator } from '@scalar/json-schema-validator';
+import { detectVersion } from './detect-version.js';
+import { ERRORS } from './errors.js';
+import { AsyncApiSpecifications } from './specifications.js';
+const validateDocument = createSpecificationValidator({
+    schemas: AsyncApiSpecifications,
+    detectVersion,
+    errors: { emptyOrInvalid: ERRORS.EMPTY_OR_INVALID, versionNotSupported: ERRORS.ASYNCAPI_VERSION_NOT_SUPPORTED },
+    // The AsyncAPI schema pins the `asyncapi` field to an exact version (a
+    // `const`), so a patch release (e.g. 3.1.4) has to be normalized to its minor
+    // before schema validation. Return a shallow copy so the caller's document is
+    // left untouched.
+    prepareDocument: (specification, version) => specification.asyncapi === version ? specification : { ...specification, asyncapi: version },
+});
+/**
+ * Validates a single AsyncAPI document against the AsyncAPI Specification.
+ *
+ * Schema validation is delegated to `@scalar/json-schema-validator`; version
+ * detection is AsyncAPI-specific.
+ *
+ * This is schema-level validation. As the AsyncAPI project notes, JSON Schema
+ * alone cannot express every rule of the specification, so a valid result here
+ * does not guarantee a semantically complete document.
+ *
+ * @param document - A JSON string, a YAML string, or an object.
+ */
+export function validate(document, options) {
+    return validateDocument(document, options);
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@scalar/asyncapi-validator",
+  "description": "Validate AsyncAPI documents against the AsyncAPI Specification",
+  "license": "MIT",
+  "author": "Scalar (https://github.com/scalar)",
+  "homepage": "https://github.com/scalar/scalar",
+  "bugs": "https://github.com/scalar/scalar/issues/new/choose",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scalar/scalar.git",
+    "directory": "packages/asyncapi-validator"
+  },
+  "keywords": [
+    "asyncapi",
+    "scalar",
+    "validator",
+    "typescript"
+  ],
+  "version": "0.1.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@asyncapi/specs": "^6.11.1",
+    "yaml": "^2.9.0",
+    "@scalar/helpers": "0.11.2",
+    "@scalar/json-schema-validator": "0.1.0",
+    "@scalar/types": "0.18.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^24.1.0",
+    "@vitejs/plugin-vue": "^6.0.8",
+    "tailwindcss": "^4.3.3",
+    "vite": "8.1.5",
+    "vue": "^3.5.40",
+    "@scalar/use-codemirror": "0.14.15",
+    "@scalar/themes": "0.17.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    "dev": "pnpm playground",
+    "playground": "cd playground && vite",
+    "test": "vitest --run",
+    "types:check": "tsgo --noEmit"
+  }
+}