Repo API: Node serialization

[enikao]

Aspects

• Nodes form a graph -> several pointers to the same node
• Because of partial loading, we might have dangling pointers -> target might not be loaded

Detailed discussions

• Repo API: Node IDs #31 TODO
• Repo API: Node representation #33
• Repo API: Property value encondings #34
• Repo API: Represent dangling pointers #35
• Repo API: Store additional resolve info? #36

Format

All nodes are repesented by a flat list.
All links to other nodes (both containment and reference) are represented by their id.

Each node has the following fields:

• id: The id of the node
• concept: Refers to the id of the type of the node
• properties: Map with
  • key: id of the property
  • value: string value of the property
• children: Map with
  • key: id of the containment link
  • value: id of the contained node
• references: Map with
  • key: id of the reference link
  • value: List of Maps with
    • reference: id of the referenced node, or null if id of the referenced node is not available
    • resolveInfo: resolve info as string, or null if no resolve info is available
• parent: id of parent node

Example

Similar to example in #36, but using property/link ids

{
  "serializationFormatVersion": "1",
  "nodes": [
    {
      "id": "11",
      "concept": "1000_1001",
      "parent": "abc",
      "properties": {
      },
      "children": {},
      "references": {
        "1000_1001-3001": [
          {
            "reference": "23",
            "resolveInfo": "Lassie"
          },
        ],
        "1000_1001-3002": [
          {
            "reference": "19",
            "resolveInfo": "Main street 23, 123 FarFarAway"
          }
        ],
        "1000_10-01": [
          {
            "reference": "342",
            "resolveInfo": null
          }
        ]
      }
    },
    {
      "id": "99",
      "concept": "1000_1002",
      "parent": "abc",
      "properties": {
        "1000_1002-1001": "Lassie"
      },
      "children": {},
      "references": []
    },
    {
      "id": "19",
      "concept": "2000_addr",
      "parent": "def",
      "properties": {
        "addr_com-example-3": "Main street",
        "addr_com-example-2": "23",
        "addr_com-example-0": "123",
        "addr_com-example-1": "FarFarAway"
      },
      "children": {},
      "references": []
    },
    {
      "id": "342",
      "concept": "internal_TechnicalPermission",
      "parent": "internal_permissionStore"
      "properties": {
        "internal_TechnicalPermission_data": "ICAgIHsKICAgICAgImlkIjogIjM0MiIsCiAgICAgICJ0eXBlIjogIlRlY2huaWNhbFBlcm1pc3Npb24iLAogICAgfQo="
      },
      "children": {},
      "references": []
    }
  ]
}

[enikao]

Do we need a fourth list for annotations, that work the same as containments?
E.g.

{
  "id": "99",
  "type": "Dog",
  "properties": {
    "name": "Lassie"
  },
  "containments": {
    "eyes": [
      "23", "55"
    ]
  },
  "references": {
    "owner": {
      "34": "Joe"
    }
  },
  "annotations": {
    "character": "79"
  }
}

[enikao]

How do we store several children in the same role?

List

{
  "id": "99",
  "type": "Dog",
  "containments": {
    "eyes": [
      "23", "55"
    ]
  }
}

Duplicate keys

(I think JSON allows that.)

{
  "id": "99",
  "type": "Dog",
  "containments": {
    "eyes": "23",
    "eyes": "55"
  }
}

[enikao]

Rename type field?

Once we introduce a typesystem, people tend to get confused by "typesystem type" vs. "metalevel type".

Potential other field names include

• concept
• meta

[dslmeinte]

Or metaType?

(Can we make a poll on GitHub?)

[enikao]

Decision on type field via Slack vote: rename to concept

Rationale: type might be confused with calculated type (as provided by a typesystem). meta is too ambiguous.

[enikao]

How do we store several children in the same role?

Has been decided to use Lists

[enikao]

Do we need a fourth list for annotations, that work the same as containments?

Annotations are postponed (#13)

[enikao]

Complete spec in https://github.com/LIonWeb-org/organization/blob/main/lioncore/serialization.adoc