What is @asyncapi/avro-schema-parser?
@asyncapi/avro-schema-parser is an npm package designed to parse Avro schemas within the context of AsyncAPI documents. It allows developers to integrate Avro schema parsing capabilities into their AsyncAPI workflows, enabling seamless schema validation and manipulation.
What are @asyncapi/avro-schema-parser's main functionalities?
Parse Avro Schema
This feature allows you to parse an Avro schema string into a JavaScript object. The code sample demonstrates how to use the AvroSchemaParser to parse a simple Avro schema for a 'User' record.
const { AvroSchemaParser } = require('@asyncapi/avro-schema-parser');
const parser = new AvroSchemaParser();
const avroSchema = `{
"type": "record",
"name": "User",
"fields": [
{ "name": "name", "type": "string" },
{ "name": "age", "type": "int" }
]
}`;
parser.parse(avroSchema).then(parsedSchema => {
console.log(parsedSchema);
}).catch(err => {
console.error(err);
});
Validate Avro Schema
This feature allows you to validate an Avro schema string. The code sample demonstrates how to use the AvroSchemaParser to validate a simple Avro schema for a 'User' record.
const { AvroSchemaParser } = require('@asyncapi/avro-schema-parser');
const parser = new AvroSchemaParser();
const avroSchema = `{
"type": "record",
"name": "User",
"fields": [
{ "name": "name", "type": "string" },
{ "name": "age", "type": "int" }
]
}`;
parser.validate(avroSchema).then(() => {
console.log('Schema is valid');
}).catch(err => {
console.error('Schema is invalid:', err);
});
Other packages similar to @asyncapi/avro-schema-parser
avsc
The 'avsc' package is a comprehensive library for working with Avro schemas in JavaScript. It provides functionalities for schema parsing, validation, and serialization/deserialization of Avro data. Compared to @asyncapi/avro-schema-parser, 'avsc' offers a broader range of features for general Avro schema manipulation but does not specifically integrate with AsyncAPI documents.
avro-js
The 'avro-js' package is another library for working with Avro schemas in JavaScript. It supports schema parsing, validation, and data serialization/deserialization. While 'avro-js' is similar to 'avsc' in terms of functionality, it is known for its ease of use and simplicity. However, it does not provide specific integration with AsyncAPI documents like @asyncapi/avro-schema-parser.
Avro Schema Parser
An AsyncAPI schema parser for Avro 1.x schemas.
Installation
npm install @asyncapi/avro-schema-parser
Usage
const parser = require('@asyncapi/parser')
const avroSchemaParser = require('@asyncapi/avro-schema-parser')
parser.registerSchemaParser(avroSchemaParser);
const asyncapiWithAvro = `
asyncapi: 2.0.0
info:
title: Example with Avro
version: 0.1.0
channels:
example:
publish:
message:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
payload: # The following is an Avro schema in YAML format (JSON format is also supported)
type: record
name: User
namespace: com.company
doc: User information
fields:
- name: displayName
type: string
- name: email
type: string
- name: age
type: int
`
await parser.parse(asyncapiWithAvro)
Usage with remote references
const parser = require('@asyncapi/parser')
const avroSchemaParser = require('@asyncapi/avro-schema-parser')
parser.registerSchemaParser(avroSchemaParser)
const asyncapiWithAvro = `
asyncapi: 2.0.0
info:
title: Example with Avro
version: 0.1.0
channels:
example:
publish:
message:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
payload:
$ref: 'https://schemas.example.com/user'
`
await parser.parse(asyncapiWithAvro)
Usage with local references
const parser = require('@asyncapi/parser')
const avroSchemaParser = require('@asyncapi/avro-schema-parser')
parser.registerSchemaParser(avroSchemaParser)
const asyncapiWithAvro = `
asyncapi: 2.0.0
info:
title: Example with Avro
version: 0.1.0
channels:
example:
publish:
message:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
payload:
$ref: 'local/path/to/file/user'
`
await parser.parse(asyncapiWithAvro)
Usage with Confluent Schema Registry
Create an API key
Copy the key and the secret
Use them on your AsyncAPI document
const parser = require('@asyncapi/parser')
const avroSchemaParser = require('@asyncapi/avro-schema-parser')
parser.registerSchemaParser(avroSchemaParser)
const asyncapiWithAvro = `
asyncapi: 2.0.0
info:
title: Example with Avro
version: 0.1.0
channels:
example:
publish:
message:
schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
payload:
$ref: 'https://LY422RBU2HN6JQ5T:+f8wz9a0iM06AX7xfwbzSM9YPw/JIkr22Cvl5EKT5Hb1d/nz5nOpbXV/vZC+Iz5c@example.europe-west3.gcp.confluent.cloud/subjects/test/versions/1/schema'
`
await parser.parse(asyncapiWithAvro)
Features
Additional attributes not defined in the Avro Specification are permitted and are treated as a metadata by the specification. To improve human readability of generated AsyncAPI documentation and to leverage more features from the JSON schema we included support for the extra attributes that can be added into Avro document.
example
- Can be used to define the example value from the business domain of given field. Value will be propagated into examples attribute of JSON schema and therefore will be picked for the generated "Example of payload" when using some AsyncAPI documentation generator.
Support for names and namespaces
If, at the top level of the Avro schema, the 'name' attribute is defined, it will be copied to the corresponding JSON schema's 'x-parser-schema-id' attribute. If the Avro schema also has the 'namespace' attribute defined, then that schema's fully qualified name will be put into that attribute. The fully qualified name is defined by the namespace, followed by a dot, followed by the name.
If there are two schemas that resolve to the same fully qualified name, only the last one will be returned by the parser. Make sure names of your schemas are unique.
If no name attribute is present, the 'x-parser-schema-id' will have a generated unique id with a name like 'anonymous-schema-1' generated by the main parser. 'x-parser-schema-id' is one of the custom extensions supported by the parser.
Limitations
Float and double-precision numbers
JSON numbers (RFC 4627, section 2.4) don't define any limit to the scale and/or precision of numbers. That said, we can enforce limits on int
and long
but we can't enforce them on float
and double
because they can't accurately be represented on JSON Schema.
Hardcoded key and secret
This is not a limitation of this package per se but of the JSON Reference RFC. So far, you can only hardcode the values for key
and secret
on the $ref
URL.