Schema JSON for Delta Structures #338

pjmolina · 2025-03-07T15:06:07Z

Schema JSON for Delta Structures

This PR provides:

An Essential format representation for Delta Protocol Structures delta-protocol.ess. This file was created manually converting from the C# implementation.
A JSON Schema serialization from (1) derived automatically by Essential applying a transformation. derived/delta.json.schema It can used for OpenAPI specs, f.e.

Validation

Sample online validator for JSON Schema: https://json-schema.hyperjump.io/

Discussion

Translation considerations from C# to Essential:

The tranlation removed some type aliases to types used in C# and interfaces.
The inheritance structure is still preserved in this version.

Design considerations

Inheritance and interfaces are convenient on C# but not really needed on JSON. We should consider pros & cons about preserving it or flattening the inheritance to simple structures.
Non public types and intermediate types & abstractions can be avoided from the final JSON Schema to make it as simple as possible.
There are many concepts with some kind of variant permutations. Any simplification we can come up will definelty increase adoption chances.

delta/json-schema/delta-protocol.ess

enikao · 2025-03-07T15:46:06Z

Shall we have abstract base types?

Shall we group our messages through types like IDeltaContent, IDeltaQuery, INodeCommand etc?

Pro:

Useful for processing them, probably in most host languages
Shows the semantic structure of our messages
We do need some of them (e.g. ISingleDeltaCommand as type to use inside CompositeCommand)

Con:

Not strictly needed
Blows up already big spec
It's easier to add more interfaces in an implementation than to remove them

Decision: We won't have abstract base types if not absolutely needed

#346

enikao · 2025-03-07T15:58:57Z

Shall we have convenience types?

Some classes like DeltaProperty or DeltaContainment are only in because the combination of (in case of DeltaProperty) string Parent + MetaPointer Property appears in lots of places. Do we want them in the schema?

NOTE: Some other types like SerializedNode or MetaPointer also appear at different places, but we do need them -- they represent first-class concepts.

Pro:

Useful for processing them, at least in C#
Schema becomes less verbose

Con:

Schema becomes more complicated
Flat structures map more directly to the spec
Easier to change if we have to fix only one usage
Binary formats (e.g. protobuf) deal better with flat structures

Decision: Flatten types, don't use convenience structures

#347

enikao · 2025-03-07T16:02:41Z

Please feel free to edit my comments above to add more pros/cons.

enikao · 2025-03-07T16:06:17Z

delta/json-schema/delta-protocol.ess

@@ -0,0 +1,842 @@
+namespace Lion.WebCore.Serialization


As discussed with Pedro, we don't want to merge this file in the end. It's just more convenient to discuss the structures in this format than raw JSONSchema.

delta/json-schema/json-schema.adoc

dslmeinte · 2025-03-08T12:13:08Z

delta/json-schema/json-schema.adoc

+the inheritance to simple structures.
+2. Non public types and intermediate types & abstractions can be avoided 
+from the final JSON Schema to make it as simple as possible.
+3. There are many concepts with some kind of variant permutations. 


Agree: some kind of usage of traits/mixins might be useful to cut down on the apparent complexity due to the sheer number of variations.

delta/json-schema/json-schema.adoc

dslmeinte · 2025-03-10T11:02:05Z

delta/json-schema/json-schema.adoc

 from the final JSON Schema to make it as simple as possible.
 3. There are many concepts with some kind of variant permutations. 
-Any simplification we can come up will definelty increase adoption chances.
+Any simplification we can come up will definetly increase adoption chances.


It’s definitely “definitely” ;)

oh my good. Fixing! ;-)

dslmeinte · 2025-03-10T11:03:10Z

delta/json-schema/delta-protocol.ess

@@ -20,6 +20,13 @@ namespace Lion.WebCore.Serialization
 	}
 	class SerializedNode
 	{
+		string Id;


Wouldn’t it be useful to have a type alias Id?

I don't think there are type aliases in JsonSchema

But this is (C#-like) Essential code.

... which will never be merged, as per #338 (comment)

dslmeinte · 2025-03-10T11:04:00Z

delta/json-schema/derived/delta.json.schema

-      "required": []
+      "properties": {
+        "Id": {
+          "type": "string"


Wouldn’t it be useful to have an explicit type Id? btw: We have a JSON Schema for the serialization format: https://github.com/LionWeb-io/specification/blob/main/2023.1/serialization/serialization.schema.json

I agree that this would be useful, "type": LionWebId" is more informative.

enikao · 2025-03-10T12:04:20Z

I would like to mainly discuss structure here, not human language style

delta/json-schema/derived/delta.json.schema

Renamed to end with schema.json so all the tools understand this is a JSON Schema.

… pjmolina/delta-json-schema

enikao · 2025-04-03T20:29:38Z

Example instances at https://github.com/LionWeb-io/lionweb-integration-testing/tree/niko/delta-api/delta

joswarmer · 2025-04-04T10:13:48Z

The DeltaSerializationChunk only has nodes. Shouldn't this be the SerializationChunk as we defined in the bulk protocol, including SerializationVersion, used languages etc. ?

enikao · 2025-04-04T13:40:24Z

The DeltaSerializationChunk only has nodes. Shouldn't this be the SerializationChunk as we defined in the bulk protocol, including SerializationVersion, used languages etc. ?

In the most recent version, I changed that to be just the array of nodes.
I think the LW version should be part of login, we won't change it during one participation -- so we don't need to re-transmit every time.
The list of languages was always redundant, and I don't see much value for it in delta.

That's my reasoning, but I don't have a very strong opinion on it. Mentioning the LW version opens another option for inconsistency, but I could live with it.

enikao · 2025-04-05T20:03:29Z

I merge this with #288, as they develop together

enikao · 2025-04-05T21:50:43Z

The DeltaSerializationChunk only has nodes. Shouldn't this be the SerializationChunk as we defined in the bulk protocol, including SerializationVersion, used languages etc. ?

I put this into #358

Schema JSON for Delta Structures

36ba520

pjmolina requested review from dslmeinte and enikao March 7, 2025 15:06

pjmolina self-assigned this Mar 7, 2025

pjmolina added the delta label Mar 7, 2025

enikao reviewed Mar 7, 2025

View reviewed changes

delta/json-schema/delta-protocol.ess Outdated Show resolved Hide resolved

enikao reviewed Mar 7, 2025

View reviewed changes

dslmeinte requested changes Mar 8, 2025

View reviewed changes

pjmolina added 2 commits March 10, 2025 11:42

fix typos

408e5c4

fix missing properties in SerializedNode

9c4d652

pjmolina requested review from dslmeinte and enikao March 10, 2025 10:53

dslmeinte reviewed Mar 10, 2025

View reviewed changes

pjmolina and others added 2 commits March 10, 2025 13:25

"definitely" fix

155f456

started to update delta JSON schema (wip)

8969f98

dslmeinte reviewed Apr 3, 2025

View reviewed changes

delta/json-schema/derived/delta.json.schema Outdated Show resolved Hide resolved

Niko Stotz and others added 5 commits April 3, 2025 09:59

completed first version of delta JSON schema

fc5e33e

fixed formatting

b73e0dd

Fixed JSON errors (missing quotes and trailing commas.

ab80710

Renamed to end with schema.json so all the tools understand this is a JSON Schema.

Merge remote-tracking branch 'origin/pjmolina/delta-json-schema' into…

eafbb51

… pjmolina/delta-json-schema

fixed some schema issues

892fa26

consolidated delta json schemata

42c66bf

fixed JSON schema issues, added SignOnRequest.deltaProtocolVersion

b440dad

removed discussion files

1c21a9a

enikao merged commit 323b6e5 into niko/delta-api-spec Apr 5, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Schema JSON for Delta Structures #338

Schema JSON for Delta Structures #338

pjmolina commented Mar 7, 2025

enikao commented Mar 7, 2025 •

edited

Loading

enikao commented Mar 7, 2025 •

edited

Loading

enikao commented Mar 7, 2025

enikao Mar 7, 2025 •

edited

Loading

dslmeinte Mar 8, 2025

dslmeinte Mar 10, 2025

pjmolina Mar 10, 2025

dslmeinte Mar 10, 2025

enikao Mar 10, 2025

dslmeinte Mar 10, 2025

enikao Mar 10, 2025

dslmeinte Mar 10, 2025 •

edited

Loading

joswarmer Apr 4, 2025

enikao commented Mar 10, 2025

enikao commented Apr 3, 2025

joswarmer commented Apr 4, 2025

enikao commented Apr 4, 2025

enikao commented Apr 5, 2025

enikao commented Apr 5, 2025

Schema JSON for Delta Structures #338

Schema JSON for Delta Structures #338

Conversation

pjmolina commented Mar 7, 2025

Schema JSON for Delta Structures

Validation

Discussion

Design considerations

enikao commented Mar 7, 2025 • edited Loading

Shall we have abstract base types?

enikao commented Mar 7, 2025 • edited Loading

Shall we have convenience types?

enikao commented Mar 7, 2025

enikao Mar 7, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dslmeinte Mar 10, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

enikao commented Mar 10, 2025

enikao commented Apr 3, 2025

joswarmer commented Apr 4, 2025

enikao commented Apr 4, 2025

enikao commented Apr 5, 2025

enikao commented Apr 5, 2025

enikao commented Mar 7, 2025 •

edited

Loading

enikao commented Mar 7, 2025 •

edited

Loading

enikao Mar 7, 2025 •

edited

Loading

dslmeinte Mar 10, 2025 •

edited

Loading