asyncapi-validator

Validate messages through AsyncApi

Note: This package only support AsyncApi Schema v2.0.0 and above.

npm i asyncapi-validator

Features

• Validate your messages against your AsyncApi Document
• Validate your AsyncApi Document against AsyncApi Schema definition
• Load your AsyncApi Schema from local file or any URL
• Supports AsyncApi in JSON and YAML format
• Supports AsyncApi v2.0.0 and above

Content

• Class Methods
  • AsyncApiValidator.fromSource()
    • Options
• Instance Methods / Properties
  • .validate()
  • .validateByMessageId() - deprecated
  • .schema
• Example usage with .validate() method
• Example usage with .validateByMessageId() method
• Errors
  • Error Example

Class Methods

AsyncApiValidator.fromSource()

/** 
 * Load and Parse the schema from source.
 * @param {string | Object} source - local PATH or URL of schema or schema Object
 * @param {Object} options - options for validation
 * @returns {Promise}
 */
AsyncApiValidator.fromSource(source, options)

Options

| value | type | | description | |-----|----|----|---| | msgIdentifier | string | required | Name of the parameter whose value will be used as "key" in .validate() method. Recommendation is to use "name" as described in message-object. You can also use Specification Extensions. | | ignoreArray | boolean | optional | If true, then if schema is defined as an array and payload is an object, then payload will be placed inside an array before validation. | | path | string | optional | Path to the AsyncApi document. |

Instance Methods and Properties

.validate()

You should provide msgIdentifier in AsyncApiValidator options.

/**
 * Method to validate the Payload against schema definition.
 * @param {string} key - required - message key (as per msgIdentifier)
 * @param {Object} payload - required - payload of the message
 * @param {string} channel - required - name of the channel/topic
 * @param {string} operation - required - publish | subscribe | send | receive
 * @returns {boolean}
 */
.validate(key, payload, channel, operation)

.validateByMessageId() - deprecated

This method is deprecated as messageId was removed in AsyncApi v3.0.0. More details here asyncapi/spec/issues/978 .

Here messageId should be as defined in AsyncApi Schema v2.4.0. To use this method, your AsyncApi Schema version should be >= v2.4.0 and <3.0.0.

/**
 * Method to validate the Payload against schema definition.
 * @param {string} key - required - messageId
 * @param {Object} payload - required - payload of the message
 * @returns {boolean}
 */
.validateByMessageId(key, payload)

.schema

.schema property can be used to access AsyncApi schema in JSON format and with all the refs resolved.

Example usage with .validate() method

Schema

asyncapi: 3.0.0
info:
  title: Streetlights Kafka API
  version: 1.0.0
channels:
  lightingMeasured:
    messages:
      lightMeasured:
        $ref: '#/components/messages/lightMeasured'
operations:
  sendLightMeasurement:
    action: send
    channel:
      $ref: '#/channels/lightingMeasured'
    messages:
      - $ref: '#/channels/lightingMeasured/messages/lightMeasured'
components:
  messages:
    lightMeasured:
      x-unique-id: lightMeasured
      payload:
        $ref: '#/components/schemas/lightMeasuredPayload'
  schemas:
    lightMeasuredPayload:
      type: object
      properties:
        lumens:
          type: integer
          minimum: 0
          description: Light intensity measured in lumens.

const AsyncApiValidator = require('asyncapi-validator')
let va = await AsyncApiValidator.fromSource('./api.yaml', {msgIdentifier: 'x-unique-id'})

// validate 'lightMeasured' on channel 'lightingMeasured' with operation 'send'
va.validate('lightMeasured', {
  lumens: 0,
  sentAt: '2019-08-24T14:15:22Z'
}, 'lightingMeasured', 'send')

In above example, "msgIdentifier" is "'x-unique-id". That is why, "lightMeasured" is used as "key" in "va.validate()" method.

Example usage with .validateByMessageId() method

Schema

asyncapi: 2.4.0

info:
  title: User Events
  version: 1.0.0

channels:
  user-events:
    description: user related events
    publish:
      message:
        messageId: UserRemoved
        payload:
          type: object
          properties:
            userEmail:
              type: string
            userId:
              type: string

const AsyncApiValidator = require('asyncapi-validator')
let va = await AsyncApiValidator.fromSource('./api.yaml')

// validate messageId 'UserRemoved'
va.validateByMessageId('UserRemoved', {
  userId: '123456789',
  userEmail: '[email protected]',
})

Errors

Error thrown from asyncapi-validator will have these properties.

| key | type | value | description | |---------|--------|-------------------------|-----------------------------------------------------------------------------------------------------------------| | name | string | AsyncAPIValidationError | AsyncAPIValidationError | | key | string | | "key" of payload against which schema is validated | | message | string | | errorsText from AJV | | errors | array | | Array of errors from AJV |

Error Example

{
  AsyncAPIValidationError: data.type must be equal to one of the allowed values at MessageValidator.validate (.....
  name: 'AsyncAPIValidationError',
  key: 'hello',
  errors:
    [
      { keyword: 'enum',
        dataPath: '.type',
        schemaPath: '#/properties/type/enum',
        params: [Object],
        message: 'must be equal to one of the allowed values'
      }
    ]
}