Avroschema-wizard-plugin (Gradle) 🐘

Plugin to interact with schema-registry using API Schema registry.

Simplify schema registration under specific subjects (topic names) and conduct seamless compatibility checks. This plugin streamlines the integration of Avro schemas, enhancing your local testing process and ensuring smooth execution in integration tests and CI pipelines. Use it now to effortlessly manage enrollment and schema validation in your Kafka ecosystem!

Use cases

The plugin simplifies kafka consumer testing when using avro schemas, and also provides additional features such as compatibility check. It can be used in local testing, as well as in integration tests or CI.

Features:

• registration of schemes under subjects
• compatibility check

How to use 👣

build.gradle.kts:

plugins {
    id("io.github.rudikone.avroschema-wizard-plugin") version <version>
}

avroWizardConfig {
    schemaRegistryUrl.set("http://localhost:8081")
    configs {
        topic("my-first-topic") {
            searchAvroFilePath.set("$projectDir/src/main/resources/avro")
            protocol.set("ExampleProtocol")
            schema.set("FirstExampleRecordFromProtocol")
            subjectNameStrategy.set("TopicNameStrategy")
        }
        topic("my-second-topic") {
            searchAvroFilePath.set("$projectDir/src/main/resources/avro")
            protocol.set("ExampleProtocol")
            schema.set("SecondExampleRecordFromProtocol")
            subjectNameStrategy.set("RecordNameStrategy")
        }
        topic("my-third-topic") {
            searchAvroFilePath.set("$projectDir/src/main/resources/avro")
            schema.set("Example")
        }
    }
}

Register schemas:

The registerAllSchemas task registers Avro schemas in the Schema Registry based on your plugin configuration.

./gradlew registerAllSchemas

How It Works:

• For each topic() configuration:
  • If the protocol property is set, the task searches for a .avpr file with the name specified by protocol in the directory specified by searchAvroFilePath.
  • If only the schema property is set (and protocol is not), the task searches for a .avsc file with the name specified by schema in the searchAvroFilePath directory.
• The found schema is registered under the topic name (the name of the configuration) using the specified subjectNameStrategy.

This process is repeated for each topic configuration.

Output: For each successfully registered schema, the following message is printed: Registered <schema_name> with id: <id_from_registry> under subject <subject_name>

Notes:

• If no matching file is found, the task will fail with an error.
• Each schema is registered independently for every configured topic.
• If a schema with the same name is registered under multiple subjects, the id will be assigned to it once. See Documentation

See examples in tests.

Compatibility check:

The checkCompatibility task verifies if your Avro schemas are compatible with the latest registered schema under a given subject in the Schema Registry.

Batch Mode (for all topics)

./gradlew checkCompatibility --compatibility=<compatibility>

How It Works:

• For each topic() configuration:
  • If the protocol property is set, the task searches for a .avpr file with the name specified by protocol in the searchAvroFilePath directory.
  • If only the schema property is set (and protocol is not), the task searches for a .avsc file with the name specified by schema in the searchAvroFilePath directory.
• The found schema is checked for compatibility with the subject, which is derived from the topic name and subjectNameStrategy.
• The specified compatibility level is used for the check (if provided); otherwise, the default compatibility level is used.

This process is repeated for each topic configuration.

Single Subject/Schema Mode

./gradlew checkCompatibility --subject=<subject-name> --schema=<schema-name> --compatibility=<compatibility>

How It Works:

• The task searches for the topic configuration with the given schema name.
• If protocol is set in the configuration, it looks for a .avpr file; otherwise, it looks for a .avsc file as described above.
• The found schema is checked for compatibility with the specified subject.
• The specified compatibility level is used for the check (if provided); otherwise, the default compatibility level is used.
• If the subject does not exist in the Schema Registry, the task will fail with an error.

Output: For each successfully registered schema, the following message is printed: Schema <schema_name> is (not) compatible with subject <subject_name>. Compatibility: <compatibility>

Notes:

• If no matching file is found for the schema, the task will fail with an error.

See examples in tests.

Knowledge base 🔥 🔥 🔥

Use examples from the tests as a comprehensive knowledge base for Schema Evolution and Compatibility:

• BACKWARD
• FORWARD
• FULL

Properties:

avroWizardConfig:

Name	Description	Default value	Required
schemaRegistryUrl	Schema registry URL	"http://localhost:10081"	-
configs	Configs for topics	-	+

configs:

Name	Description	Default value	Required
searchAvroFilePath	Directory to search for file with extension .avcs or .avpr	build directory of the project	-
protocol	Name of .avpr file	-	-
schema	Name of .avsc file or record in protocol	-	+
subjectNameStrategy	Subject Name Strategy: TopicNameStrategy, RecordNameStrategy, TopicRecordNameStrategy	TopicNameStrategy	-

Contributing 🤝

Feel free to open an issue or submit a pull request for any bugs/improvements.

License 📄

This plugin is licensed under the MIT License - see the License file for details.