jsonpb: strictly document JSONPBMarshaler and JSONPBUnmarshaler behavior #662
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
neild
approved these changes
Jul 31, 2018
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.