It's more likely we'll update the docs at this point. But leaving to @rsc to decide.

I see.

For what it's worth, I'll comment that I found it surprising that a func json.Indent which is supposed to take poorly formatted/unformatted JSON input, would seemingly randomly produce slightly different output (before I read the docs fully). I expected, as part of indenting/formatting, that any unformatted variation of the same JSON input would produce same output.

It'd also be consistent with other funcs in encoding/json (like json.Encoder.Encode and json.MarshalIndent), as well as go/format.Source formatting, I believe.

Also, this is the additional code I needed to add to my code to produce expected/consistent output:

@@ -21,6 +21,14 @@ func run() error {

        var out bytes.Buffer
        err = json.Indent(&out, in, "", "\t")
        if err != nil {
                return err
        }
+       // TODO: Maybe not here; see https://github.com/golang/go/issues/13520.
+       // Add a newline, if there isn't one already.
+       if l := out.Len(); l != 0 && out.Bytes()[l-1] != '\n' {
+               err = out.WriteByte('\n')
+               if err != nil {
+                       return err
+               }
+       }

That wouldn't be needed if json.Indent behaved as documented.

I think I like the behavior as documented better, and would hope the implementation is fixed (since that would make json.Indent slightly better), but I'll leave to decide what's best overall to you.

Well that's sad. It has been that way back at least to Go 1.2 (I don't have earlier Go versions on my Mac). It looks like all trailing spaces are preserved, not just a single newline.

Conflicted about changing this. Still thinking.

It looks like all trailing spaces are preserved, not just a single newline.

You're right. In that case, I'll need to change my code to be quite non-trivial in order to be able to use the result of json.Indent in a predictable manner (i.e., always having a single trailing newline), and do so in an efficient manner (i.e., avoiding copying memory ala strings.TrimSpace(out.String())):

    ...

    var out bytes.Buffer
    err = json.Indent(&out, in, "", "\t")
    if err != nil {
        return err
    }
    // TODO: Maybe not here; see https://github.com/golang/go/issues/13520.
    // Trim all whitespace at the end. Then add a single newline.
    i := trimRightSpace(out.Bytes())
    out.Truncate(i)
    err = out.WriteByte('\n')
    if err != nil {
        return err
    }

    ...
}

// trimRightSpace returns index i, such that s[0:i] is a subslice of s
// by slicing off all trailing white space, as defined by Unicode.
func trimRightSpace(s []byte) int {
    i := lastIndexFunc(s, unicode.IsSpace, false)
    if i >= 0 && s[i] >= utf8.RuneSelf {
        _, wid := utf8.DecodeRune(s[i:])
        i += wid
    } else {
        i++
    }
    return i
}

// lastIndexFunc is the same as bytes.LastIndexFunc except that if
// truth==false, the sense of the predicate function is inverted.
func lastIndexFunc(s []byte, f func(r rune) bool, truth bool) int {
    for i := len(s); i > 0; {
        r, size := rune(s[i-1]), 1
        if r >= utf8.RuneSelf {
            r, size = utf8.DecodeLastRune(s[0:i])
        }
        i -= size
        if f(r) == truth {
            return i
        }
    }
    return -1
}

Here's an updated playground link:

https://play.golang.org/p/pJpGqNhgz7

Sure, that works. So does:

err = json.Indent(&out, bytes.TrimSpace(in), "", "\t")
out.WriteByte('\n')