Schema Registry

Learn how to produce Avro, Protobuf, and JSON Schema records with a schema registry, and check their replies.

Understand schema registry support

Gatling produces Avro, Protobuf, and JSON Schema keys and values with a schema registry, with Confluent’s serializers, so that the system under test reads them as it reads the records of its own producers.

You write the key or the value as JSON, with any Gatling body, and Gatling converts it with its schema, then serializes it with Confluent’s serializer for its format. Serialization is part of the response time of the request, see where serialization happens.

Add Confluent’s serializers

The plugin doesn’t bring Confluent’s serializers. Add the serializer of each format you use, from Confluent’s repository, https://packages.confluent.io/maven/, in the same scope as the Gatling dependencies:

Format Serializer dependency
Avro io.confluent:kafka-avro-serializer
Protobuf io.confluent:kafka-protobuf-serializer
JSON Schema io.confluent:kafka-json-schema-serializer

For example, for Avro:

<repositories>
  <repository>
    <id>confluent</id>
    <url>https://packages.confluent.io/maven/</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>io.confluent</groupId>
    <artifactId>kafka-avro-serializer</artifactId>
    <version>8.4.0</version>
    <scope>test</scope>
  </dependency>
</dependencies>
repositories {
  maven {
    url = "https://packages.confluent.io/maven/"
  }
}

dependencies {
  gatlingImplementation("io.confluent:kafka-avro-serializer:8.4.0")
}
resolvers += "Confluent" at "https://packages.confluent.io/maven/"
libraryDependencies += "io.confluent" % "kafka-avro-serializer" % "8.4.0" % "test,it"

Confluent’s serializers bring Confluent’s own build of the Kafka clients (org.apache.kafka:kafka-clients with a -ccs version), which can replace the Apache Kafka clients the plugin depends on. The plugin is tested with both. Gatling Enterprise runs your simulations with the Apache Kafka clients the plugin depends on, whatever version your project resolves locally.

The plugin is tested with Confluent’s serializers 8.4.0. Gatling works with Protobuf 3.x and 4.x, whichever version the Protobuf serializer brings.

When a simulation uses a format whose serializer is missing, it fails at startup, naming the dependency to add.

Configure the schema registry

Configure the schema registry on the protocol:

     
/*
 * Copyright 2011-2026 GatlingCorp (https://gatling.io)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import io.gatling.javaapi.core.*;
import java.util.Map;

import static io.gatling.javaapi.core.CoreDsl.*;
import static io.gatling.javaapi.kafka.KafkaDsl.*;

class KafkaSchemaRegistrySampleJava extends Simulation {

  {
//#registry
kafka
  .bootstrapServers("broker1:9092")
  .schemaRegistry("https://registry.example.com:8081")
  .schemaRegistryBasicAuth("user", "password")
  // properties of Confluent's serializers and deserializers
  .schemaRegistryProperty("auto.register.schemas", "false")
  .schemaRegistryProperties(Map.of("use.latest.version", "true"));
//#registry

//#avro
String orderSchema = """
  {
    "type": "record",
    "name": "Order",
    "fields": [
      {"name": "id", "type": "string"},
      {"name": "amount", "type": "double"},
      {"name": "coupon", "type": ["null", "string"], "default": null}
    ]
  }""";

kafka("Avro order")
  .send("orders")
  .value(avro(
    orderSchema,
    // a union's non-null value is wrapped in an object keyed by its type
    StringBody("{\"id\": \"#{orderId}\", \"amount\": #{amount}, \"coupon\": {\"string\": \"#{coupon}\"}}")
  ));
//#avro

//#protobuf
kafka("Protobuf order")
  .send("orders")
  .value(protobuf(
    """
    syntax = "proto3";
    message Order {
      string id = 1;
      double amount = 2;
    }""",
    StringBody("{\"id\": \"#{orderId}\", \"amount\": #{amount}}")
  ));
//#protobuf

//#json-schema
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchema(
    """
    {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "amount": {"type": "number"}
      }
    }""",
    StringBody("{\"id\": \"#{orderId}\", \"amount\": #{amount}}")
  ));
//#json-schema

//#subject
kafka("Avro order")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")));
kafka("Protobuf order")
  .send("orders")
  .value(protobufSubject("orders-value", ElFileBody("order.json")));
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchemaSubject("orders-value", ElFileBody("order.json")));
//#subject

//#key
kafka("Avro key")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")))
  // an Avro string, as JSON
  .key(avro("{\"type\": \"string\"}", StringBody("\"#{orderId}\"")));
//#key

//#decode
kafka("Check order")
  .requestReply("order-requests", "order-replies")
  .value(avroSubject("order-requests-value", ElFileBody("order.json")))
  .key("#{orderId}")
  // the checks read the reply's value as JSON
  .decodeAvroReply()
  .check(jsonPath("$.status").is("ACCEPTED"));
//#decode
  }
}
/*
 * Copyright 2011-2026 GatlingCorp (https://gatling.io)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import io.gatling.javaapi.core.CoreDsl.*
import io.gatling.javaapi.core.Simulation
import io.gatling.javaapi.kafka.KafkaDsl.*

class KafkaSchemaRegistrySampleKotlin : Simulation() {

  init {
//#registry
kafka
  .bootstrapServers("broker1:9092")
  .schemaRegistry("https://registry.example.com:8081")
  .schemaRegistryBasicAuth("user", "password")
  // properties of Confluent's serializers and deserializers
  .schemaRegistryProperty("auto.register.schemas", "false")
  .schemaRegistryProperties(mapOf("use.latest.version" to "true"))
//#registry

//#avro
val orderSchema = """
  {
    "type": "record",
    "name": "Order",
    "fields": [
      {"name": "id", "type": "string"},
      {"name": "amount", "type": "double"},
      {"name": "coupon", "type": ["null", "string"], "default": null}
    ]
  }"""

kafka("Avro order")
  .send("orders")
  .value(avro(
    orderSchema,
    // a union's non-null value is wrapped in an object keyed by its type
    StringBody("""{"id": "#{orderId}", "amount": #{amount}, "coupon": {"string": "#{coupon}"}}""")
  ))
//#avro

//#protobuf
kafka("Protobuf order")
  .send("orders")
  .value(protobuf(
    """
    syntax = "proto3";
    message Order {
      string id = 1;
      double amount = 2;
    }""",
    StringBody("""{"id": "#{orderId}", "amount": #{amount}}""")
  ))
//#protobuf

//#json-schema
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchema(
    """
    {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "amount": {"type": "number"}
      }
    }""",
    StringBody("""{"id": "#{orderId}", "amount": #{amount}}""")
  ))
//#json-schema

//#subject
kafka("Avro order")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")))
kafka("Protobuf order")
  .send("orders")
  .value(protobufSubject("orders-value", ElFileBody("order.json")))
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchemaSubject("orders-value", ElFileBody("order.json")))
//#subject

//#key
kafka("Avro key")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")))
  // an Avro string, as JSON
  .key(avro("""{"type": "string"}""", StringBody("\"#{orderId}\"")))
//#key

//#decode
kafka("Check order")
  .requestReply("order-requests", "order-replies")
  .value(avroSubject("order-requests-value", ElFileBody("order.json")))
  .key("#{orderId}")
  // the checks read the reply's value as JSON
  .decodeAvroReply()
  .check(jsonPath("\$.status").shouldBe("ACCEPTED"))
//#decode
  }
}
/*
 * Copyright 2011-2026 GatlingCorp (https://gatling.io)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import io.gatling.core.Predef._
import io.gatling.kafka.Predef._

class KafkaSchemaRegistrySampleScala extends Simulation {

//#registry
kafka
  .bootstrapServers("broker1:9092")
  .schemaRegistry("https://registry.example.com:8081")
  .schemaRegistryBasicAuth("user", "password")
  // properties of Confluent's serializers and deserializers
  .schemaRegistryProperty("auto.register.schemas", "false")
  .schemaRegistryProperties(Map("use.latest.version" -> "true"))
//#registry

//#avro
val orderSchema = """
  {
    "type": "record",
    "name": "Order",
    "fields": [
      {"name": "id", "type": "string"},
      {"name": "amount", "type": "double"},
      {"name": "coupon", "type": ["null", "string"], "default": null}
    ]
  }"""

kafka("Avro order")
  .send("orders")
  .value(avro(
    orderSchema,
    // a union's non-null value is wrapped in an object keyed by its type
    StringBody("""{"id": "#{orderId}", "amount": #{amount}, "coupon": {"string": "#{coupon}"}}""")
  ))
//#avro

//#protobuf
kafka("Protobuf order")
  .send("orders")
  .value(protobuf(
    """
    syntax = "proto3";
    message Order {
      string id = 1;
      double amount = 2;
    }""",
    StringBody("""{"id": "#{orderId}", "amount": #{amount}}""")
  ))
//#protobuf

//#json-schema
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchema(
    """
    {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "amount": {"type": "number"}
      }
    }""",
    StringBody("""{"id": "#{orderId}", "amount": #{amount}}""")
  ))
//#json-schema

//#subject
kafka("Avro order")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")))
kafka("Protobuf order")
  .send("orders")
  .value(protobufSubject("orders-value", ElFileBody("order.json")))
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchemaSubject("orders-value", ElFileBody("order.json")))
//#subject

//#key
kafka("Avro key")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")))
  // an Avro string, as JSON
  .key(avro("""{"type": "string"}""", StringBody("\"#{orderId}\"")))
//#key

//#decode
kafka("Check order")
  .requestReply("order-requests", "order-replies")
  .value(avroSubject("order-requests-value", ElFileBody("order.json")))
  .key("#{orderId}")
  // the checks read the reply's value as JSON
  .decodeAvroReply
  .check(jsonPath("$.status").is("ACCEPTED"))
//#decode
}
Option Description
schemaRegistry The URL of the schema registry, or several ones, comma-separated.
schemaRegistryBasicAuth The username and password of the registry’s basic authentication.
schemaRegistryProperty, schemaRegistryProperties Properties of Confluent’s serializers and deserializers, such as auto.register.schemas, use.latest.version, or value.subject.name.strategy. schema.registry.url is refused: use schemaRegistry instead.

Confluent’s serializers register the schema of a key or a value in the registry, under the subject that the subject name strategy derives from the topic, unless you change it with these properties. Refer to Confluent’s documentation for the available properties.

Produce Avro, Protobuf, and JSON Schema values

Pass a schema registry body to value, with the schema and the payload, a Gatling body that renders JSON.

Avro

avro takes an Avro schema, and a payload in Avro’s JSON encoding, where the non-null value of a union is wrapped in an object keyed by its type:

     
String orderSchema = """
  {
    "type": "record",
    "name": "Order",
    "fields": [
      {"name": "id", "type": "string"},
      {"name": "amount", "type": "double"},
      {"name": "coupon", "type": ["null", "string"], "default": null}
    ]
  }""";

kafka("Avro order")
  .send("orders")
  .value(avro(
    orderSchema,
    // a union's non-null value is wrapped in an object keyed by its type
    StringBody("{\"id\": \"#{orderId}\", \"amount\": #{amount}, \"coupon\": {\"string\": \"#{coupon}\"}}")
  ));
val orderSchema = """
  {
    "type": "record",
    "name": "Order",
    "fields": [
      {"name": "id", "type": "string"},
      {"name": "amount", "type": "double"},
      {"name": "coupon", "type": ["null", "string"], "default": null}
    ]
  }"""

kafka("Avro order")
  .send("orders")
  .value(avro(
    orderSchema,
    // a union's non-null value is wrapped in an object keyed by its type
    StringBody("""{"id": "#{orderId}", "amount": #{amount}, "coupon": {"string": "#{coupon}"}}""")
  ))
val orderSchema = """
  {
    "type": "record",
    "name": "Order",
    "fields": [
      {"name": "id", "type": "string"},
      {"name": "amount", "type": "double"},
      {"name": "coupon", "type": ["null", "string"], "default": null}
    ]
  }"""

kafka("Avro order")
  .send("orders")
  .value(avro(
    orderSchema,
    // a union's non-null value is wrapped in an object keyed by its type
    StringBody("""{"id": "#{orderId}", "amount": #{amount}, "coupon": {"string": "#{coupon}"}}""")
  ))

Protobuf

protobuf takes a .proto schema, whose first message is the value’s, and a payload in the Protobuf JSON mapping:

     
kafka("Protobuf order")
  .send("orders")
  .value(protobuf(
    """
    syntax = "proto3";
    message Order {
      string id = 1;
      double amount = 2;
    }""",
    StringBody("{\"id\": \"#{orderId}\", \"amount\": #{amount}}")
  ));
kafka("Protobuf order")
  .send("orders")
  .value(protobuf(
    """
    syntax = "proto3";
    message Order {
      string id = 1;
      double amount = 2;
    }""",
    StringBody("""{"id": "#{orderId}", "amount": #{amount}}""")
  ))
kafka("Protobuf order")
  .send("orders")
  .value(protobuf(
    """
    syntax = "proto3";
    message Order {
      string id = 1;
      double amount = 2;
    }""",
    StringBody("""{"id": "#{orderId}", "amount": #{amount}}""")
  ))

JSON Schema

jsonSchema takes a JSON schema, and a JSON payload:

     
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchema(
    """
    {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "amount": {"type": "number"}
      }
    }""",
    StringBody("{\"id\": \"#{orderId}\", \"amount\": #{amount}}")
  ));
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchema(
    """
    {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "amount": {"type": "number"}
      }
    }""",
    StringBody("""{"id": "#{orderId}", "amount": #{amount}}""")
  ))
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchema(
    """
    {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "amount": {"type": "number"}
      }
    }""",
    StringBody("""{"id": "#{orderId}", "amount": #{amount}}""")
  ))

The serializer only validates the payload against the schema with the schema registry property json.fail.invalid.schema set to true.

Use the schema of a subject

avroSubject, protobufSubject, and jsonSchemaSubject use the latest schema of a subject in the registry, instead of a schema in the simulation. Gatling reads it once per run, when the first request uses it.

     
kafka("Avro order")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")));
kafka("Protobuf order")
  .send("orders")
  .value(protobufSubject("orders-value", ElFileBody("order.json")));
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchemaSubject("orders-value", ElFileBody("order.json")));
kafka("Avro order")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")))
kafka("Protobuf order")
  .send("orders")
  .value(protobufSubject("orders-value", ElFileBody("order.json")))
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchemaSubject("orders-value", ElFileBody("order.json")))
kafka("Avro order")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")))
kafka("Protobuf order")
  .send("orders")
  .value(protobufSubject("orders-value", ElFileBody("order.json")))
kafka("JSON Schema order")
  .send("orders")
  .value(jsonSchemaSubject("orders-value", ElFileBody("order.json")))

The format of the subject’s schema must be the format of the body, and Gatling doesn’t resolve schema references: a schema referencing other schemas fails.

Produce schema registry keys

Keys accept the same schema registry bodies as values:

     
kafka("Avro key")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")))
  // an Avro string, as JSON
  .key(avro("{\"type\": \"string\"}", StringBody("\"#{orderId}\"")));
kafka("Avro key")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")))
  // an Avro string, as JSON
  .key(avro("""{"type": "string"}""", StringBody("\"#{orderId}\"")))
kafka("Avro key")
  .send("orders")
  .value(avroSubject("orders-value", ElFileBody("order.json")))
  // an Avro string, as JSON
  .key(avro("""{"type": "string"}""", StringBody("\"#{orderId}\"")))

Understand where serialization happens

Confluent’s serializers may call the schema registry, to register or look up a schema, so Gatling serializes the first key or value of a schema, topic, and format on a sender thread, never on the threads of the virtual users. Once the serializer has cached the schema, the virtual users serialize the next ones themselves, which spreads serialization over their threads.

When you set use.latest.version to true, or set latest.cache.ttl.sec, with schemaRegistryProperty, the serializer looks the schema up again after a while, so Gatling keeps serializing on the sender threads.

In both cases, serialization is part of the response time of the request.

Decode replies

When the system under test replies with Avro, Protobuf, or JSON Schema, decode the reply of a request-reply with decodeAvroReply, decodeProtobufReply, or decodeJsonSchemaReply, with the deserializer of Confluent’s serializer dependency:

     
kafka("Check order")
  .requestReply("order-requests", "order-replies")
  .value(avroSubject("order-requests-value", ElFileBody("order.json")))
  .key("#{orderId}")
  // the checks read the reply's value as JSON
  .decodeAvroReply()
  .check(jsonPath("$.status").is("ACCEPTED"));
kafka("Check order")
  .requestReply("order-requests", "order-replies")
  .value(avroSubject("order-requests-value", ElFileBody("order.json")))
  .key("#{orderId}")
  // the checks read the reply's value as JSON
  .decodeAvroReply()
  .check(jsonPath("\$.status").shouldBe("ACCEPTED"))
kafka("Check order")
  .requestReply("order-requests", "order-replies")
  .value(avroSubject("order-requests-value", ElFileBody("order.json")))
  .key("#{orderId}")
  // the checks read the reply's value as JSON
  .decodeAvroReply
  .check(jsonPath("$.status").is("ACCEPTED"))

The decoded reply is JSON, in the Protobuf JSON mapping for Protobuf, with the fields at their default value included:

  • bodyString, substring, regex, jsonPath, and jmesPath read the decoded JSON
  • bodyBytes, bodyLength, and bodyStream still read the record’s bytes

Decoding happens outside of the response time. A reply that can’t be decoded fails the request. consume and subscriptions don’t decode: their checks read the record’s value as is.

Edit this page on GitHub