It is not clear enough what "JSON Serialization" is

Context

https://github.com/w3c/json-ld-api/issues/579 (for JSON-LD 1.1 API) or https://github.com/json-ld/yaml-ld/issues/143 (for YAML-LD, which derives from JSON-LD) seem to stem from a common issue: a reader of the API specification might be unclear about what is meant under "JSON Serialization" in the spec.

§ 1.5 Example Conventions says:

Note that in the examples used in this document, output is of necessity shown in serialized form as JSON. While the algorithms describe operations on the JSON-LD internal representation, when they as displayed as examples, the JSON serialization is used. In particular, the internal representation use of maps are represented using JSON objects.

A programmer will likely expect that JSON Serialization is a string. For instance, Working With JSON Data in Python → Serializing JSON says:

What happens after a computer processes lots of information? It needs to take a data dump. Accordingly, the json library exposes the dump() method for writing data to files. There is also a dumps() method (pronounced as “dump-s”) for writing to a Python string.

The explanation in the API will not convince the reader otherwise. § 9.1 The JsonLdProcessor Interface →expand() instructs the implementation, at item 9), to

Resolve the promise with expanded output transforming expanded output from the internal representation to a JSON serialization.

Thus, expand() output type must be a String. Right?

No. Because the same § 9.1 The JsonLdProcessor Interface section, in its IDL block, specifies:

static Promise<sequence<JsonLdRecord>> expand(
    JsonLdInput input,
    optional JsonLdOptions options = {});

In fact, the expand() return value is a sequence of JsonLdRecord objects, which probably are represented as map (or as an object, or as a dict) in the programming language powering an implementation.

Alternatives

Change the wording in the specification, replacing JSON Serialization with, for instance,
- JSON Data
- JSON Structure
- JSON object (unlikely though: the spec already uses that term)
Explain explicitly the non-standard meaning of JSON Serialization term in the spec
- Directly in the text of the 1.1 specification (if that is possible)
- As an Erratum to the 1.1 specification
- As a part of the 1.2 specification

Also

I think we need to also very explicitly explain the difference among

JsonLdRecord, on the one hand,
and internal representation, on the other,

with an example.

Decision

(TODO: subject to discussion)

In the placeholder above, I will summarize what we've come up with, for future reference.

What do you think? :thinking:

w3c / json-ld-api