Specification: Ballerina Protobuf Library

Owners: @daneshk @MadhukaHarith92
Reviewers: @daneshk
Created: 2021/11/17
Updated: 2022/02/08
Edition: Swan Lake

Introduction

This is the specification for the Protobuf standard library of Ballerina language, which provides APIs to represent a set of pre-defined protobuf types.

The Protobuf library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant Github tag.

If you have any feedback or suggestions about the library, start a discussion via a GitHub issue or in the Slack channel. Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under /docs/proposals. Proposals under discussion can be found with the label type/proposal in Github.

The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug.

Contents

  1. Overview
  2. Wrappers
  3. Duration
  4. Struct
  5. Timestamp
  6. Empty
  7. Any

1. Overview

This specification elaborates on the pre-defined record types and functions available in the Protobuf library.

2. Wrappers

This provides APIs to represent google/protobuf/wrappers.proto. The protobuf module supports 5 wrapper types; string, int, float, boolean, and bytes.

2.1. String type

The ContextStringStream is a context representation record of a string stream.

The ContextString is a context representation record of a string value.

2.2. Integer type

The ContextIntStream is a context representation record of an integer stream.

The ContextInt is a context representation record of an integer value.

2.3. Float type

The ContextFloatStream is a context representation record of a float stream.

The ContextFloat is a context representation record of a float value.

2.4. Boolean type

The ContextBooleanStream is a context representation record of a boolean stream.

The ContextBoolean is a context representation record of a boolean value.

2.5. Bytes type

The ContextBytesStream is a context representation record of a byte array stream.

The ContextBytes is a context representation record of a byte array.

3. Duration

This provides APIs to represent google/protobuf/duration.proto.

The ContextDurationStream is a context representation record of a duration stream.

The ContextDuration is a context representation record of a duration. The content is a time duration represented using time:Seconds. The time:Seconds is a subtype of Ballerina decimal type.

4. Struct

This provides APIs to represent google/protobuf/struct.proto.

The ContextStructStream is a context representation record of a struct stream.

The ContextStruct is a representation record of a struct.

5. Timestamp

This provides APIs to represent google/protobuf/timestamp.proto.

The ContextTimestampStream is a context representation record of a timestamp stream.

The ContextTimestamp is a representation record of a timestamp.

6. Empty

This provides APIs to represent google/protobuf/empty.proto.

The ContextNil is a representation record of a gRPC Empty message.

Empty represents an empty record.

7. Any

This provides APIs to represent google/protobuf/any.proto.

The Any record is the Ballerina representation of the protobuf Any type. The typeUrl is the unique identifier of the serialized message, and the value contains the serialized message content. The type of the value entry defines as ValueType, which represent all the Ballerina types that support as subtypes of Any.

There are two APIs to serialize and deserialize the Any type values as follows.

The ContextAny is a context representation record of Any Ballerina record.

The ContextAnyStream is the stream representation that contains a stream of Any records as the content.