Spatial Visual-Meta consists of a 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 are normally added to an academic document using square brackets: [1], [2], etc. This is an inspiration to the way the user can also now refer to multiple Layouts in the body of the document:
• 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 “”
- 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.
Why this Shape
Nodes are defined once and positioned many times. An AI or reader encountering {Timeline} or {Spatial Map} in body text can look up the layout by that name, resolve each position’s id back to the node pool, and reconstruct the full spatial view with names, definitions, and citation data — all from a single file with one clean ID system. Citations work the same way references do in academic papers. Layouts work the same way but for spatial views, making them a first-class citable element of the document.
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 — Build layouts. The default layout comes from DynamicView.layout.nodePositions. Each entry in DynamicView.customLayouts becomes an additional layout. For every position entry, replace the old DynamicView id with the new UUID using the mapping from Step 2. Round x, y, z to two decimal places.
Step 4 — 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 5 — 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.