Proto3 language guide also has a section about JSON mapping:
https://developers.google.com/protocol-buffers/docs/proto3#json

We will publish a more detailed JSON spec doc later.

Hello, has there been any progress on this? Or is it possible that I can help with this if there's already some text that we'd like to add?

Sorry, we are not ready to publish the doc yet. If you have specific questions about the JSON formatting of some proto types, can you post the questions here? If you are working on implementing a JSON serializer conforming to the spec, you can look at our conformance test which covers a lot of the JSON mapping details:
https://github.com/google/protobuf/blob/master/conformance/conformance_test.cc#L623

The json serialization does not contain message type information, so while parsing we need to provide a builder:
In Java:
JsonFormat.Parser
merge(String json, Builder builder);
merge(Reader json, Builder builder);

How can we make the json representation self-contained by encoding the message type info in it as well; so that parser can detect the message type to parse into?

I think #1690 is exactly about this but for C++.

@meta-coder Are you asking for a new API that looks like:

class Parser {
  public Message merge(String json);
}

? It's not clear to me how useful is this kind of API. Without knowing the type, how can you make use of the returned Message instance?

In a way, I was. Including the type of the message in the json representation can be helpful in parsing. For comparison, the default serialization mechanism used by Java's ObjectOutputStream is to write the class of the object and the class signature at the beginning of the encoding.
Anyway, I realize I could use `oneof' to achieve what I want. Thanks.

We have a service in JS that needs to implement protobuf to JSON and vice-versa for internal use and the UI.

We'd like to implement a canonical proto3 JSON serialiser/deserialiser.

I'll try to set up conformance tests, but something specifically for the spec would be really useful.

We currently have docs here: https://developers.google.com/protocol-buffers/docs/proto3#json
We also implemented our json conformance test here: https://github.com/protocolbuffers/protobuf/blob/master/conformance/conformance_test_impl.cc
Is it enough to write your conformance test? @ofpiyush

For unrelated reasons, we moved the service to Go and used it's serialiser/deserialiser. So I stopped looking into this.

Thanks for your help @TeBoring 👍

It appears that those who contributed to this issue have all found workarounds or are otherwise no longer blocked. I'm closing this issue, but feel free to reopen it with additional details if this is still a problem.