encoding/json: document that Encoder.Encode produces JSON values as single text line

[dolmen]

Proposal Details

The encoding/json Encoder outputs JSON values as single lines of text since its original version and this is a design choice (see @rsc claim). This makes it an early implementation of the JSON Lines standard.

However this feature is undocumented: nothing about the absence of \n in doc for Encoder, Encoder.Encode (or json.Marshal). As this is undocumented, users can't rely on this implementation detail (but I expect many rely on it anyway).

This proposal is about extending the Encoder.Encode documentation to guarantee that no raw \n or \r is produced inside a JSON value.

[gabyhelp]

Similar Issues

• encoding/json: Encoder adds trailing newlines #7767

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[mauri870]

I don't think this needs to be a proposal as it only affects documentation. Taking it out of the proposal process.

[mauri870]

cc @dsnet @mvdan per https://dev.golang.org/owners

[dolmen]

I marked this as a proposal because it engages the Go project to preserve the behaviour in the future, so it might need discussing instead of just discussing the wording in a CL.

Also: I don't know if there are already regression tests that enforce this feature. So this might be a bit more than just documentation.

[ianlancetaylor]

We basically can't change this kind of thing at this point anyhow. We don't need a proposal to retain the current behavior.

[dsnet]

Agreed. Let's document this. I think the behavior is reasonable as a default, but there are some people that would like to avoid the newlines, but that can be a potential option in v2. See go-json-experiment/json#40 for context.

[gopherbot]

Change https://go.dev/cl/597976 mentions this issue: encoding/json: document compact json output in Encoder.Encode