Include serialization format version in serialization

[enikao]

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.

[enikao]

What's the name of the version field? version? format_version? lioncore_version? something else?

[dslmeinte]

serializationFormatVersion, or versionOfSerializationFormat? (Preferably something camel-cased, not snake-cased.)

[enikao]

Decision via Slack vote: serializationFormatVersion

Rationale: Very specific, little room for interpretation.