# protobuf

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [connect-full.txt](https://docs.redpanda.com/connect-full.txt)

---
title: protobuf
latest-connect-version: 4.93.0
latest-operator-version: v26.1.4
latest-console-tag: v3.7.3
latest-redpanda-tag: v26.1.9
docname: processors/protobuf
page-component-name: connect
page-version: master
page-component-version: master
page-component-title: Connect
page-relative-src-path: processors/protobuf.adoc
page-edit-url: https://github.com/redpanda-data/rp-connect-docs/edit/main/modules/components/pages/processors/protobuf.adoc
page-git-created-date: "2024-05-24"
page-git-modified-date: "2026-05-26"
---

<!-- Source: https://docs.redpanda.com/connect/components/processors/protobuf.md -->

**Available in:** Self-Managed

Handles conversions between JSON documents and protobuf messages using reflection, which allows you to make conversions from or to the target `.proto` files.

For more information about JSON mapping of protobuf messages, see [ProtoJSON Format](https://protobuf.dev/programming-guides/json/) and [Examples](#examples).

```yml
# Configuration fields, showing default values
label: ""
protobuf:
  operator: "" # No default (required)
  message: "" # No default (required)
  discard_unknown: false
  use_proto_names: false
  import_paths: []
  use_enum_numbers: false
```

## [](#performance-considerations)Performance considerations

Processing protobuf messages using reflection is less performant than using generated native code. For scenarios where performance is critical, consider using [Redpanda Connect plugins](https://github.com/benthosdev/benthos-plugin-example).

## [](#operators)Operators

### [](#to_json)`to_json`

Converts protobuf messages into a generic JSON structure, which makes it easier to manipulate the contents of the JSON document within Redpanda Connect.

### [](#from_json)`from_json`

Attempts to create a target protobuf message from a generic JSON structure.

## [](#fields)Fields

### [](#bsr)`bsr[]`

Buf Schema Registry configuration. Either this field or `import_paths` must be populated. Note that this field is an array, and multiple BSR configurations can be provided.

**Type**: `object`

**Default**: `[]`

### [](#bsr-api_key)`bsr[].api_key`

Buf Schema Registry server API key, can be left blank for a public registry.

> ⚠️ **CAUTION**
>
> This field contains sensitive information that usually shouldn’t be added to a configuration directly. For more information, see [Secrets](https://docs.redpanda.com/connect/configuration/secrets/).

**Type**: `string`

**Default**: `""`

### [](#bsr-module)`bsr[].module`

Module to fetch from a Buf Schema Registry e.g. 'buf.build/exampleco/mymodule'.

**Type**: `string`

### [](#bsr-url)`bsr[].url`

Buf Schema Registry URL, leave blank to extract from module.

**Type**: `string`

**Default**: `""`

### [](#bsr-version)`bsr[].version`

Version to retrieve from the Buf Schema Registry, leave blank for latest.

**Type**: `string`

**Default**: `""`

### [](#discard_unknown)`discard_unknown`

When set to `true`, the `from_json` operator discards fields that are unknown to the schema.

**Type**: `bool`

**Default**: `false`

### [](#import_paths)`import_paths[]`

A list of directories that contain `.proto` files, including all definitions required for parsing the target message. If left empty, the current directory is used. This processor imports all `.proto` files listed within specified or default directories.

**Type**: `array`

**Default**: `[]`

### [](#message)`message`

The fully-qualified name of the protobuf message to convert from or to JSON.

**Type**: `string`

### [](#operator)`operator`

The [operator](#operators) to execute.

**Type**: `string`

**Options**: `to_json`, `from_json`, `decode`

### [](#use_enum_numbers)`use_enum_numbers`

When set to `true`, the `to_json` operator deserializes enumeration fields as their numerical values instead of their string names. For example, an enum field with a value of `ENUM_VALUE_ONE` is represented as `1` in the JSON output.

**Type**: `bool`

**Default**: `false`

### [](#use_proto_names)`use_proto_names`

When set to `true`, the `to_json` operator deserializes fields exactly as named in schema file.

**Type**: `bool`

**Default**: `false`

## [](#examples)Examples

### [](#json-to-protobuf-using-schema-from-disk)JSON to Protobuf using Schema from Disk

If we have the following protobuf definition within a directory called `testing/schema`:

```protobuf
syntax = "proto3";
package testing;

import "google/protobuf/timestamp.proto";

message Person {
  string first_name = 1;
  string last_name = 2;
  string full_name = 3;
  int32 age = 4;
  int32 id = 5; // Unique ID number for this person.
  string email = 6;

  google.protobuf.Timestamp last_updated = 7;
}
```

And a stream of JSON documents of the form:

```json
{
	"firstName": "caleb",
	"lastName": "quaye",
	"email": "caleb@myspace.com"
}
```

We can convert the documents into protobuf messages with the following config:

```yaml
pipeline:
  processors:
    - protobuf:
        operator: from_json
        message: testing.Person
        import_paths: [ testing/schema ]
```

### [](#protobuf-to-json-using-schema-from-disk)Protobuf to JSON using Schema from Disk

If we have the following protobuf definition within a directory called `testing/schema`:

```protobuf
syntax = "proto3";
package testing;

import "google/protobuf/timestamp.proto";

message Person {
  string first_name = 1;
  string last_name = 2;
  string full_name = 3;
  int32 age = 4;
  int32 id = 5; // Unique ID number for this person.
  string email = 6;

  google.protobuf.Timestamp last_updated = 7;
}
```

And a stream of protobuf messages of the type `Person`, we could convert them into JSON documents of the format:

```json
{
	"firstName": "caleb",
	"lastName": "quaye",
	"email": "caleb@myspace.com"
}
```

With the following config:

```yaml
pipeline:
  processors:
    - protobuf:
        operator: to_json
        message: testing.Person
        import_paths: [ testing/schema ]
```

### [](#json-to-protobuf-using-buf-schema-registry)JSON to Protobuf using Buf Schema Registry

If we have the following protobuf definition within a BSR module hosted at `buf.build/exampleco/mymodule`:

```protobuf
syntax = "proto3";
package testing;

import "google/protobuf/timestamp.proto";

message Person {
  string first_name = 1;
  string last_name = 2;
  string full_name = 3;
  int32 age = 4;
  int32 id = 5; // Unique ID number for this person.
  string email = 6;

  google.protobuf.Timestamp last_updated = 7;
}
```

And a stream of JSON documents of the form:

```json
{
	"firstName": "caleb",
	"lastName": "quaye",
	"email": "caleb@myspace.com"
}
```

We can convert the documents into protobuf messages with the following config:

```yaml
pipeline:
  processors:
    - protobuf:
        operator: from_json
        message: testing.Person
        bsr:
          - module: buf.build/exampleco/mymodule
            api_key: xxx
```

### [](#protobuf-to-json-using-buf-schema-registry)Protobuf to JSON using Buf Schema Registry

If we have the following protobuf definition within a BSR module hosted at `buf.build/exampleco/mymodule`:

```protobuf
syntax = "proto3";
package testing;

import "google/protobuf/timestamp.proto";

message Person {
  string first_name = 1;
  string last_name = 2;
  string full_name = 3;
  int32 age = 4;
  int32 id = 5; // Unique ID number for this person.
  string email = 6;

  google.protobuf.Timestamp last_updated = 7;
}
```

And a stream of protobuf messages of the type `Person`, we could convert them into JSON documents of the format:

```json
{
	"firstName": "caleb",
	"lastName": "quaye",
	"email": "caleb@myspace.com"
}
```

With the following config:

```yaml
pipeline:
  processors:
    - protobuf:
        operator: to_json
        message: testing.Person
        bsr:
          - module: buf.build/exampleco/mymodule
            api_key: xxxx
```