1# Custom types
2
3Custom types is a gogo protobuf extensions that allows for using a custom
4struct type to decorate the underlying structure of the protocol message.
5
6# How to use
7
8## Defining the protobuf message
9
10```proto
11message CustomType {
12 optional ProtoType Field = 1 [(gogoproto.customtype) = "T"];
13}
14
15message ProtoType {
16 optional string Field = 1;
17}
18```
19
20or alternatively you can declare the field type in the protocol message to be
21`bytes`:
22
23```proto
24message BytesCustomType {
25 optional bytes Field = 1 [(gogoproto.customtype) = "T"];
26}
27```
28
29The downside of using `bytes` is that it makes it harder to generate protobuf
30code in other languages. In either case, it is the user responsibility to
31ensure that the custom type marshals and unmarshals to the expected wire
32format. That is, in the first example, gogo protobuf will not attempt to ensure
33that the wire format of `ProtoType` and `T` are wire compatible.
34
35## Custom type method signatures
36
37The custom type must define the following methods with the given
38signatures. Assuming the custom type is called `T`:
39
40```go
41func (t T) Marshal() ([]byte, error) {}
42func (t *T) MarshalTo(data []byte) (n int, err error) {}
43func (t *T) Unmarshal(data []byte) error {}
44func (t *T) Size() int {}
45
46func (t T) MarshalJSON() ([]byte, error) {}
47func (t *T) UnmarshalJSON(data []byte) error {}
48
49// only required if the compare option is set
50func (t T) Compare(other T) int {}
51// only required if the equal option is set
52func (t T) Equal(other T) bool {}
53// only required if populate option is set
54func NewPopulatedT(r randyThetest) *T {}
55```
56
57Check [t.go](test/t.go) for a full example
58
59# Warnings and issues
60
61`Warning about customtype: It is your responsibility to test all cases of your marshaling, unmarshaling and size methods implemented for your custom type.`
62
63Issues with customtype include:
64 * <a href="https://github.com/gogo/protobuf/issues/199">A Bytes method is not allowed.<a/>
65 * <a href="https://github.com/gogo/protobuf/issues/132">Defining a customtype as a fake proto message is broken.</a>
66 * <a href="https://github.com/gogo/protobuf/issues/147">proto.Clone is broken.</a>
67 * <a href="https://github.com/gogo/protobuf/issues/125">Using a proto message as a customtype is not allowed.</a>
68 * <a href="https://github.com/gogo/protobuf/issues/200">cusomtype of type map can not UnmarshalText</a>
69 * <a href="https://github.com/gogo/protobuf/issues/201">customtype of type struct cannot jsonpb unmarshal</a>
70 * <a href="https://github.com/gogo/protobuf/issues/477">Customtype field does not get a generated 'getter' method</a>
71 * <a href="https://github.com/gogo/protobuf/issues/478">Repeated customtype fields generate slices without pointer to the custom type </a>
View as plain text