We might change the format of the serialization over time.
Does it make sense to store the format version in each serialization, or shall it be transported otherwise?
Example without version info:
[
{
"type": "LIonCore_M3_Metamodel",
"id": "txjxNU9yRzEuyghtmgJK_l-nF93qWt7d1vErz5RbLow",
...
},
{
"type": "LIonCore_M3_PrimitiveType",
"id": "INhBvWyXvxwNsePuX0rdNGB_J9hi85cTb1Q0APXCyJ0",
...
}
]Example including version info:
{
"format_version": "1",
"nodes": [
{
"type": "LIonCore_M3_Metamodel",
"id": "txjxNU9yRzEuyghtmgJK_l-nF93qWt7d1vErz5RbLow",
...
},
{
"type": "LIonCore_M3_PrimitiveType",
"id": "INhBvWyXvxwNsePuX0rdNGB_J9hi85cTb1Q0APXCyJ0",
...
}
]
}Questions
- Can we require (as per JSON spec) the format version to always be the first entry?
-> We can enforce by having only two entries on highest level
- How is this usually done in web context?
Arguments
pro:
- We know of any piece of serialized nodes how to interpret them, no matter whether we got it from a file, some protocol, web form, whatever.
con:
- Might duplicate info transmitted somewhere else (e.g. some HTTP header or URL), and we need to deal with inconsistent info.
Decision
We include one version number in serialization format.
This version is a single integer, to be incremented with each new version.
A new version might be needed if the LIonCore M3, the serialization format, or both change.
The version must be the first entry in the top-level node serialization JSON object named serializationFormatVersion, as in:
{
"serializationFormatVersion": 1,
"nodes": [
{
"concept": "LIonCore_M3_Metamodel",
"id": "txjxNU9yRzEuyghtmgJK_l-nF93qWt7d1vErz5RbLow",
...
},
]
}Rationale: Both the LIonCore M3 and the serialization format might change in the future. Most probably, they both change together (e.g. if we introduced a list of annotations for each node). If only the M3 changed and the serialization format stayed the same, it's acceptable to have two versions with the same serialization formats. Encoding M3 and serialization format number separately would introduce additional complexity through combinatorics of the two versions.
We want to be explicit about which version of both M3 and serialization format was used to write a serialization, such that the reader does not need to guess or detect it implicitly. The reader needs this information at the earliest possible time.
We might change the format of the serialization over time.
Does it make sense to store the format version in each serialization, or shall it be transported otherwise?
Example without version info:
[ { "type": "LIonCore_M3_Metamodel", "id": "txjxNU9yRzEuyghtmgJK_l-nF93qWt7d1vErz5RbLow", ... }, { "type": "LIonCore_M3_PrimitiveType", "id": "INhBvWyXvxwNsePuX0rdNGB_J9hi85cTb1Q0APXCyJ0", ... } ]Example including version info:
{ "format_version": "1", "nodes": [ { "type": "LIonCore_M3_Metamodel", "id": "txjxNU9yRzEuyghtmgJK_l-nF93qWt7d1vErz5RbLow", ... }, { "type": "LIonCore_M3_PrimitiveType", "id": "INhBvWyXvxwNsePuX0rdNGB_J9hi85cTb1Q0APXCyJ0", ... } ] }Questions
-> We can enforce by having only two entries on highest level
Arguments
pro:
con:
Decision
We include one version number in serialization format.
This version is a single integer, to be incremented with each new version.
A new version might be needed if the LIonCore M3, the serialization format, or both change.
The version must be the first entry in the top-level node serialization JSON object named
serializationFormatVersion, as in:{ "serializationFormatVersion": 1, "nodes": [ { "concept": "LIonCore_M3_Metamodel", "id": "txjxNU9yRzEuyghtmgJK_l-nF93qWt7d1vErz5RbLow", ... }, ] }Rationale: Both the LIonCore M3 and the serialization format might change in the future. Most probably, they both change together (e.g. if we introduced a list of
annotationsfor each node). If only the M3 changed and the serialization format stayed the same, it's acceptable to have two versions with the same serialization formats. Encoding M3 and serialization format number separately would introduce additional complexity through combinatorics of the two versions.We want to be explicit about which version of both M3 and serialization format was used to write a serialization, such that the reader does not need to guess or detect it implicitly. The reader needs this information at the earliest possible time.