Unions serialization.

[balabuev]

Please clarify somewhere how Union of Union is serialized. Also, how Union of Struct with subtypes is serialized.
As I undersnand, there should be several ".tag" properties in the same JSON object, which is not so easy to deduct.

[balabuev]

Its also not understood, why simplified Union serialization (as a string value in case of void tag) is not really used (even in deserializers) in generated SDK code.
And also, its quite confusing of how to use such simplified serialization, in case of a Union inside Union.

[braincore]

The .tag properties become nested under the appropriate field names. For example, given the following spec:

union U
    var1 V

union V
    varA

Serializing U outputs:

{
  ".tag": "var1",
  "var1: {
    ".tag": "varA"
  }
}

The compact union serialization format isn't understood by our client SDKs in any language besides Python because Dropbox server always sends down the more general form. That's done because we see the compact form as beneficial for writing requests by hand in a terminal, rather than for programmatic ease.

Why do we support it in Python? Because Dropbox's API servers are written in Python and the deserializers needs to support the compact form for incoming client requests: https://github.com/dropbox/stone/blob/master/stone/backends/python_rsrc/stone_serializers.py#L642

Ideally, all of our deserializers would support the compact form, but I suspect that will only happen once we/someone requires the use of a target language other than Python on their server-side.

[balabuev]

Are you sure? It seems to me that .Net SDK serializes your example as:

{
  ".tag": "var1",
  ".tag": "varA"
}

I didn't run the code, but I reviewed it. I'll check it more...

However, anyway, do unions has to inline struct fields or this is also only a compact format; for example, whether this:

union U
    var1 V

struct V
    x integer
    y integer

have to be serialized to this:

{
  ".tag": "var1",
  "x": 7,
  "y": 9
}

or general form is also valid:

{
  ".tag": "var1",
  "var1: {
    "x": 7,
    "y": 9
  }
}

[braincore]

I'm certain that's our intended behavior. @qimingyuan can verify the .NET SDK.

Unions have to inline struct fields, there's no compact/general form distinction.

[balabuev]

Ok, but what about structs with subtypes? To inline their fields inside a union still two ".tag" properties are required...

[braincore]

Structs with subtypes cannot be inlined. Instead, the serialization looks just like the first nested union example I provided. Let me know if you want an example.

[braincore]

By the way, thanks for the feedback. I've updated our documentation to be more explicit: https://github.com/dropbox/stone/blob/master/docs/json_serializer.rst#union

Feel free to re-open if you have further questions.