How to document/specify/provide schemas for nested data structures

[PietroPasotti]

Databags are flat string:string mappings.
Sometimes relation databags need or want more structure and therefore the values of that mapping are yaml/json/b64/pickle-encoded complex objects.
In our schemas we'd like to document what the structure of those complex objects are.

How do we document the type of encoding used?

[simskij]

the values of that mapping are yaml/json/b64/pickle-encoded complex objects

Do we have any examples of where it is something other than JSON? Should we? I'm not convinced. However, if we need this, the description field of a particular key/value pair seems like an excellent place to put this. WDYT?

[PietroPasotti]

In traefik it's yaml.
In serialized-data-interface it was all yaml. In traefik-route I used json IIRC (thinking later we'd move Traefik to json as well)
In other projects, I don't know, but I think we can't take that for granted.
Agreed, we should put that in the field description. What's ugly about this is that the 'example' will be harder to read and it will obfuscate the internal structure of the object, since to be truthful we have to write yaml/json/whatever instead of the (json) data structure.

[jnsgruk]

I think in general my feelings are:

• Don't nest unless you really need to
• If you really need to, use JSON

Any objections there?

[simskij]

Any objections there?

This is my point of view as well. People might use yaml, pickle or whatever, but if they want it to be part of the spec, I would be perfectly fine with making JSON serialized data structures a requirement.