How do LW specs relate to specific bindings / implementations

[enikao]

We could separate LionWeb in three levels:

1. The ideas and semantics[1], independent of any of actual binding and implementation (e.g. "There are synchronous queries, asynchronous client->repo commands, asynchronous repo->client events, a command AddProperty, and a related event PropertyAdded")
2. Binding these ideas and semantics to a specific protocol (e.g. "delta in JSON over WebSocket", "bulk in XML over HTTP", "bulk and delta in Protobuf over MessageQueue")
3. Implementing the ideas, semantics, and protocol binding in a specific host language (e.g. "Java client for bulk Protobuf over HTTP with OAuth", "TS delta client in JSON over WebSocket")

Then we should be clear how much leeway we give in higher levels for lower level interpretation (e.g. "encoding of unset optional parameters is binding-specific").
We would also need to allow adjustments in lower levels (e.g. "WebSocket simulates synchronous messaging by splitting up a Query message into QueryRequest and QueryRespose messages").

[1] On might call them "Concepts", but that term would be ambiguous.

Questions:

• Do we want to follow a specific separation? Which one?
• If yes, which parts are in scope? Primary or secondary?

[enikao]

Related for 3): #43

[enikao]

Q:

• Are these levels helpful for external consumers, or only for internal discussion?

It's a lot harder to understand two documents (conceptual spec + binding) than one integrated document.

It's awkward to force non-fitting mechanisms on an interface layer (e.g. forced async messages on http, or error response messages on http instead of 500 response).

Decision Proposal

In the delta introduction, we mention the default binding is json over async text-based protocol (like WebSocket); such transports MUST adhere to the json schema.. We mention any non-obvious relations between the spec and the linked json schema.
Other bindings MUST implement the same semantics as described in the spec.

[enikao]

The issue I mentioned about LW spec scope is #148

On 2023-07-07, we decided to describe conceptual features and precise serialization format, but not more. This corresponds to level 4.

[enikao]

I wrote up a lot of protocol-specific design assumptions in #429

[enikao]

Another one about LW spec scope: #241 (comment)

[enikao]

Proposed wording in spec:

This protocol is agnostic of its underlying transport or technical implementation. By default, this protocol uses JSON encoding over a text-based, single channel, stateful, bi-directional, asynchronous, reliable, and trustworthy transport.[15] Any transport that fits these criteria (e.g. WebSocket[16]) MUST use the same encoding.

https://github.com/LionWeb-io/specification/blob/big-delta-chunks2/delta/description.adoc#channel-characteristics

[dslmeinte]

Proposed wording in spec:

This protocol is agnostic of its underlying transport or technical implementation. By default, this protocol uses JSON encoding over a text-based, single channel, stateful, bi-directional, asynchronous, reliable, and trustworthy transport.[15] Any transport that fits these criteria (e.g. WebSocket[16]) MUST use the same encoding.

https://github.com/LionWeb-io/specification/blob/big-delta-chunks2/delta/description.adoc#channel-characteristics

Is it an idea to asterisk the MUST to explain that we explicitly do this to “encourage” compatibility of implementations?

[enikao]

Is it an idea to asterisk the MUST to explain that we explicitly do this to “encourage” compatibility of implementations?

Good idea, I'll add to this issue (428) as rationale.