1. from_recap
  2. to_recap
  3. Examples
    1. Recap to Protobuf
    2. Protobuf to Recap
  4. Type Conversion
    1. From Recap to Protobuf
    2. From Protobuf to Recap
  5. Aliases
  6. Limitations and Constraints

Recap uses the ProtobufConverter class to convert between Recap types and Protobuf types. ProtobufConverter has two main methods: from_recap and to_recap.


This method converts a Recap type to a Protobuf type.

def from_recap(self, struct_type: StructType) -> File:

The from_recap method checks whether the input Recap type has an alias and collects all the necessary Message and Enum types that need to be declared in the Proto file. It verifies all subpackages are under the root package and constructs the proto file with the correct nesting.


This method converts a Protobuf type to a Recap type.

def to_recap(
    protobuf_schema_str: str,
) -> StructType:

The to_recap method is designed to take in Protobuf types and translate them into equivalent Recap types.


Recap to Protobuf

from recap.converters.protobuf import ProtobufConverter
from recap.types import StructType, StringType, IntType

# Define a Recap schema
recap_schema = StructType(
        IntType(name="age", bits=32),

# Convert to Protobuf schema
protobuf_schema = ProtobufConverter().from_recap(recap_schema)

Protobuf to Recap

from recap.converters.protobuf import ProtobufConverter

# Define an Protobuf schema
protobuf_schema = """
syntax = "proto3";
package build.recap.example;
message Person {
    string name = 1;
    int32 age = 2;

# Convert to Recap schema
recap_schema = ProtobufConverter().to_recap(protobuf_schema)

Type Conversion

From Recap to Protobuf

This table shows the corresponding Protobuf types for each Recap type.

Recap Type Protobuf Type
NullType google.protobuf.NullValue
BoolType bool
IntType (signed and bits <= 32) int32
IntType (signed and bits <= 64) int64
IntType (unsigned and bits <= 32) uint32
IntType (unsigned and bits <= 64) uint64
FloatType (bits <= 32) float
FloatType (bits <= 64) double
StringType (bytes <= 2_147_483_647) string
BytesType (bytes <= 2_147_483_647) bytes
ListType Repeated Field
MapType MapField
UnionType OneOf
StructType Message
EnumType Enum

From Protobuf to Recap

This table shows the corresponding Recap types for each Protobuf type.

Protobuf Type Recap Type
google.protobuf.NullValue NullType
bool BoolType
int32 IntType(signed=True, bits=32)
int64 IntType(signed=True, bits=64)
uint32 IntType(signed=False, bits=32)
uint64 IntType(signed=False, bits=64)
float FloatType(bits=32)
double FloatType(bits=64)
string StringType(bytes=2_147_483_647, variable=True)
bytes BytesType(bytes=2_147_483_647, variable=True)
Repeated Field ListType
MapField MapType
OneOf UnionType
Message StructType
Enum EnumType


Recap aliases are converted to Protobuf package and message names. An alias is converted to a Protobuf message called Baz in the package. Likewise, a Protobuf message called Baz in the package is converted to a Recap alias

Limitations and Constraints

The Recap type system is more expressive than the Protobuf type system. Consequently, there are some Recap types which cannot be represented in Protobuf, or which are represented less precisely. For instance, IntType with bits > 64 cannot be represented in Protobuf, as Protobuf only supports 32-bit and 64-bit integers.

The conversion functions raise a ValueError exception if the conversion is not possible.