jsonpb: strictly document JSONPBMarshaler and JSONPBUnmarshaler behavior (#662)
Strictly document that custom JSONPBMarshaler and JSONPBUnmarshaler must
properly follow the JSON to proto specification:
https://developers.google.com/protocol-buffers/docs/proto3#json
These interfaces are currently necessary since there is no high-level API
for proto reflection. However, as we prepare to move to a world where there is
first-class support for proto reflection, these interfaces should be deprecated.
When we eventually have proto reflection, and implement jsonpb entirely
in terms of reflection, then it should not matter whether we called these
custom marshalers or not since they should both implement the same specification.
Note that this documentation is already implied by the fact that this whole
package implements the proto-JSON specification and in order for it to do so,
it implies that any custom interfaces it calls also follows the specification.
We strictly document this to dissuade improper implementations.
diff --git a/jsonpb/jsonpb.go b/jsonpb/jsonpb.go
index 57cde15..ada2b78 100644
--- a/jsonpb/jsonpb.go
+++ b/jsonpb/jsonpb.go
@@ -106,6 +106,9 @@
// way they are marshaled to JSON. Messages that implement this should
// also implement JSONPBUnmarshaler so that the custom format can be
// parsed.
+//
+// The JSON marshaling must follow the proto to JSON specification:
+// https://developers.google.com/protocol-buffers/docs/proto3#json
type JSONPBMarshaler interface {
MarshalJSONPB(*Marshaler) ([]byte, error)
}
@@ -114,6 +117,9 @@
// the way they are unmarshaled from JSON. Messages that implement this
// should also implement JSONPBMarshaler so that the custom format can be
// produced.
+//
+// The JSON unmarshaling must follow the JSON to proto specification:
+// https://developers.google.com/protocol-buffers/docs/proto3#json
type JSONPBUnmarshaler interface {
UnmarshalJSONPB(*Unmarshaler, []byte) error
}
