It is not clear enough what "JSON Serialization" is

[anatoly-scherbakov]

Context

#579 (for JSON-LD 1.1 API) or json-ld/yaml-ld#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? 🤔

[gkellogg]

We definitely need to clean this up. Probably, clarify that the API methods return the JsonLdRecord (or sequence of JsonLdRecord) which is the WebIDL description of the internal representation, although internal representation includes map, array, number, or JSON Literal.

Probably something in the API section that generally says that the default serialization of the resulting internal representation is JSON and that processors MUST return this value when application/json or a subtype is expected.

[gkellogg]

Discussed on [today's call](https://json-ld.org/minutes/2024-07-10/#55).

Anatoly Scherbakov: The issue about JSON Serialization: #605 ✪

#605 -> Issue 605 It is not clear enough what "JSON Serialization" is (by anatoly-scherbakov) [spec:editorial] [ErratumRaised] ✪

Gregg Kellogg: Perhaps extract the json serialization for responding to a content type request. ✪

Anatoly Scherbakov: We could specify a "serialize()" function to do this, if it takes a content type. ✪

... The API can describe when to serialize.

... I wanted to be sure that we agree that an expand function should return a datastructure, and not a serialization.

Pierre-Antoine Champin: I misunderstood what you said before, and agree that we should fix the API definitions. ✪

Niklas Lindström: Also agree to fix, but "do less". :) ✪

... I understand anatoly-scherbakov's concerns about how to define this, but also worry about what this could disrupt.

[anatoly-scherbakov]

1. What if we replace every incarnation of JSON Serialization with

• Object Representation,
• or, perhaps, External Representation (in contrast to Internal Representation)?

2. If we try doing so, how to do that? Via an Erratum? Can we just change the index.html file of the spec and that's it?

I've prepared a PR for this simple change: #608