@asyncapi/specs

    3.2.1 • Public • Published

    npm npm

    If you are currently using version 2, check out migration guideline to version 3. You might be able to update it without any change.

    AsyncAPI

    This is a mono repository, which provides all the JSON Schema documents for validating AsyncAPI documents.

    Overview

    • This repository contains JSON Schema files for all the versions of AsyncAPI specification.
    • These JSON Schema files do not reflect 1:1 the specification and shouldn't be treated as specification itself but rather as a tool (e.g., for validation).
    • These JSON Schema files shouldn't be used as the only tool for validating AsyncAPI documents because some rules described in the AsyncAPI specification can't be described with JSON Schema.
    • In addition, this repo provides JavaScript and Go modules that make it easier to access JSON Schema files through code.

    Custom Validation Needs

    If you decide to validate AsyncAPI documents only with the JSON Schema files provided in this repo, your AsyncAPI documents will not be properly validated. It's recommended to use AsyncAPI JavaScript Parser that uses the AsyncAPI JSON Schema files for validation but also implements additional custom validations.

    The following additional custom validations need to be provided:

    • Variables provided in the URL property have a corresponding variable object defined and its example is correct.
    • operationIds are not duplicated in the document.
    • messageIds are not duplicated in the document.
    • Server security is declared properly and the name has a corresponding securitySchemes definition in components with the same name.
    • Server securitySchemes is an empty array when the security type requires it.
    • Parameters specified in the channel name have corresponding parameters object defined.
    • Channel names do not contain URL parameters.
    • All servers listed for a channel in the servers property are declared in the top-level servers object.
    • Tags specified in any object have no duplicates. Check must be done for: the top-level object, operations (publish and subscribe), operation traits, channels, messages, and message traits.

    At the moment, AsyncAPI JavaScript parser do not cover all validation cases yet All test cases and parsers coverage can be found here

    Installation

    NodeJS

    npm install @asyncapi/specs

    Go

    go get github.com/asyncapi/spec-json-schemas/v2

    Usage

    NodeJS

    Grab a specific AsyncAPI version:

    const asyncapi = require('@asyncapi/specs/schemas/2.0.0');
    
    // Do something with the schema.

    Get a list of versions:

    const versions = require('@asyncapi/specs');
    
    console.log(versions);
    // Outputs:
    //
    // {
    //   '1.0.0': [Object],
    //   '1.1.0': [Object]
    // }
    
    const asyncapi = versions['1.1.0'];
    
    // Do something with the schema.

    Go

    Grab a specific AsyncAPI version:

    import "github.com/asyncapi/spec_json_schemas/v2"
    
    func Do() {
        schema, err := spec_json_schemas.Get("1.1.0")
        if err != nil {
            panic(err)
        }
    
        // Do something with the schema
    }

    Repository structure

    This is the current project structure explained.

    • ./definitions - contain all the individual schemas that will automatically be bundled together to provide the schemas in ./schemas.
    • ./tools/bundler - is the tool that bundles all the individual schemas together.
    • ./schemas - contain all automatically bundled and complete schemas for each AsyncAPI version. These schemas should NOT be manually changed as they are automatically generated. Any changes should be done in ./definitions.

    Schema Bundling

    Changes should not be done manually to the schemas in ./schemas, but instead be done in their individual definitions located in ./definitions.

    These definitions are automatically bundled together on new releases through the npm script prepublishOnly, which ensures the project is build. This is where the bundler is called.

    For example, for 2.2.0, the bundler starts with the asyncapi.json file and recursively goes through all references ($ref) to create the appropriate bundled version.

    Creating a new version

    To create a new version, simply run the following command:

    npm run startNewVersion --new-version=x.x.x
    

    Where x.x.x is the new version you want to create.

    The manual process of creating a new version is to:

    1. Duplicate the latest version (y.y.y) under definitions (so we have the correct base to make changes from).
    2. Rename the folder to the new version (x.x.x).
    3. Search and replace in the new duplicated folder for y.y.y and replace it with x.x.x.
    4. Edit the index.js file adding a new line with the new version. I.e. '2.5.0': require('./schemas/2.5.0.json'),.
    5. Edit the schemas/all.schema-store.json file adding a new entry under the oneOf keyword with the new version. I.e.:
      {
         "allOf":[
            {
               "properties":{
                  "asyncapi":{
                     "const":"2.5.0"
                  }
               }
            },
            {
               "$ref":"http://asyncapi.com/schema-store/2.5.0.json"
            }
         ]
      }

    Keywords

    none

    Install

    npm i @asyncapi/specs

    DownloadsWeekly Downloads

    159,807

    Version

    3.2.1

    License

    Apache-2.0

    Unpacked Size

    14 MB

    Total Files

    868

    Last publish

    Collaborators

    • fmvilas
    • derberg
    • asyncapi-bot