rephrase `JSON.parse` more generally in terms of `String`-convertible value parameter

[ltcmelo]

As of the 2025 edition, 25.5.1 JSON.parse ( text [ , reviver ] ) reads as:

"This function parses a JSON text (a JSON-formatted String) and..."

Yet, based on a few implementations and official tests cases (e.g. text-non-string-primitive and text-object), the text parameter of JSON.parse doesn't need to be a String; even though, it's expect the text is convertible to an String — in fact, step 1 of this abstract operations is:

"1. Let jsonString be ? ToString(text)."

Perhaps the description of function JSON.parse should be rephrased more generally in terms of an ECMAScript language value that can be converted to an String?

[michaelficarra]

I don't think we need that kind of precision in the summary. This text is meant to be less complete than the algorithm steps, while not being incorrect. This function does parse a JSON-formatted String, and it also converts its input to String before doing that.

[ltcmelo]

I think that specifications should be as precise as possible. Also, since the summary indicates the parameter's types, I'd consider it to be incorrect (not just imprecise): Although this function does parse a JSON-formatted String, which is an ECMA value of String type, it parses values of other ECMA types as well; in a formalized ECMA implementation/verifier (that uses that parameter type), this description won't always "type check".

I created PR https://github.com/tc39/ecma262/pull/3322 with a suggested change, in case you find it useful.

[bakkot]

Different levels of precision are appropriate to different parts of the specification. The algorithm steps are the source of truth for the behavior, and must be precise; the informal descriptions, on the other hand, are intended to be useful guides for readers, and can in many cases reasonably elide details like type coercions.