Spatial Visual-Meta consists single JSON file, or plain text appendix in a document, with a Layout section which uses ID’s for the Knowledge Objects to be places in space, viewed as ‘Nodes’ spatially.
Note: The name ‘Spatial Visual-Meta’ is of no importance, it is merely a means to talk about this approach, a placeholder.
Layouts
Crucially, multiple named layouts can arrange those same nodes in different spatial configurations and layouts can be called from body text using inline markers., similar to how citations can.
{
"layouts": [
{
"name": "Grill",
"positions": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"x": -570.28,
"y": -59.00,
"z": -1.71
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"x": 576.75,
"y": -536.43,
"z": -1.58
}
]
},
{
"name": "Timeline",
"positions": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"x": 100.00,
"y": 0.00,
"z": 0.00
}
]
}
]
}
Knowledge Objects
- Citations are data objects which contain References to citable, published books, papers, web pages etc. and which may or may not contain Abstracts, Quotes, notes or other addition information. The Citations are fully in BibTeX and the Layout used the BibTeX ID’s for the Citations. In academic documents it is expected that the citations will be listed in a References section.
- Defined Concepts, composed of the term (display text) and definition, along with further metadata. This can also be referred to as a ‘Glossary‘.
"nodes": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Visual-Meta",
"type": "glossary",
"description": "Metadata standard and approach created by Frode Hegland…",
"tag": "",
"urls": [],
"citationIdentifiers": []
},
],
Inline Markers in Body Text
The body text of the document can reference both citations and layouts using inline markers:
• Citations use square brackets: [1], [2], etc. These refer to citation nodes. The number maps to the citation’s position in the nodes array when filtered to type: “citation” only, sorted by order of first appearance in the text.
• Layouts use curly brackets with name: {Name}, {Another Name}, etc. These refer to specific spatial layouts.
Example body text:
Hegland argues that documents need richer metadata [1].
The relationship between these concepts becomes clear
when viewed spatially {Spatial Map}.
Node Definitions
All nodes share these fields:
- id — string, UUID generated at export time
- name — string, display label
- type — string, either “glossary” or “citation”
Glossary nodes (type: “glossary”) additionally have:
- description — string, the full definition
- tag — string, one of “person”, “label”, “institution”, or “”
- isLiked — boolean
- isHidden — boolean
- urls — array of strings
- citationIdentifiers — array of node id strings pointing to related citation nodes
Citation nodes (type: “citation”) additionally have:
- authors — array of strings, each in “Last, First” format
- year — string
- publication — string, venue or journal name
- doi — string, empty if unavailable
- abstract — string, empty if unavailable
- urls — array of strings
Layout Definitions
Each entry in the layouts array:
- name — string, human-readable label for this layout
- positions — array of position objects, each containing:
- id — string, matches a node’s id from the nodes array
- x — float, horizontal position
- y — float, vertical position
- z — float, depth position
A layout does not need to include every node. If a node has no entry in a layout’s positions array, it is simply not placed in that layout. The same node can appear in multiple layouts at different positions.
Build Process Example
Process for building from Author’s internal Mapping structure, presented as a guideline:
Step 1 — Build the node pool. For each node in DynamicView.nodes, search glossary.entries for an entry whose phrase matches the node’s name. Merge glossary fields into the node. For citation nodes, populate from the citation data source. Discard all source identifiers (from DynamicView, glossary, and citation sources).
Step 2 — Generate new UUIDs. For each completed node, generate a fresh UUID (v4) and assign it as the id field. This is the single ID system for the output. Build a mapping from old DynamicView identifier → new id for use in the next step.
Step 3 — Wire up citationIdentifiers. For any glossary node whose source glossary entry referenced citation nodes, replace the old citation identifiers with the new UUIDs from Step 2.
Step 4— Sort and export. Sort the nodes array alphabetically by name. Sort each layout’s positions array alphabetically by resolved node name. Write the output.
Additional Rules
- If a glossary entry has no matching DynamicView node, omit it.
- Do not include: connections, settings, collapsedNodes, isStruckthrough, definition, documentPath, date, or any identifier from the source files.
- The “visualmeta”: “1.0” field is a version marker for this format.