Validate messages through AsyncApi
Note: This package only support AsyncApi Schema v2.0.0 and above.
npm i asyncapi-validator
- 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
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)
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
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 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: 'alex@mail.com',
})
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 |
{
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'
}
]
}