Termboard JSON Format

The Termboard JSON format is an open and transparent structure that allows for full interoperability with other applications and AI models. It captures not only the semantics (Terms and Relations) but also the complete visual layout, styling, and metadata of a project.

TIP

This guide is intended for developers or AI models looking to programmatically generate or parse Termboard project files.

High-Level Structure

A Termboard JSON file consists of two primary objects: metadata and data. While the application can parse files where terms and relations are at the root, the standard project format uses the following structure:

{
  "metadata": { ... },
  "data": {
    "terms": [ ... ],
    "relations": [ ... ]
  }
}

NOTE

Termboard also supports a metaInfo key as an alias for metadata for backward compatibility.

---

Metadata

The metadata (or metaInfo) object defines the project's identity, document-level settings, and visual schema.

Property	Type	Description
id	string	Unique identifier for the project.
name	string	Display name of the project.
author	string	Name of the creator.
description	string	Brief overview of the project content.
updateDateTime	string	ISO 8601 timestamp of the last update.
xFields	array	Definitions of Extra Fields (see below).
xFieldsSettings	object	Maps XFields to visual properties (see below).
documentSettings	object	Global toggles and styling preferences.
termMapping	object	Configures how fields are handled during Excel export/import.
relationMapping	object	Configures how relations are handled during Excel export/import.
relationTypeMapping	array	Custom mappings between Relation Names and semantic types.

Extra Fields (xFields)

These define custom attributes that can be applied to Terms or Relations.

{
  "id": "field-unique-guid",
  "name": "Branch",
  "type": "hierarchy-branch", // text, dropdown, multi-value, link, hierarchy-level, hierarchy-branch, etc.
  "scope": "both", // 'terms', 'relations', or 'both'
  "values": ["Governance", "Location"],
  "colors": { "Governance": "#FDD835" },
  "hierarchyConfig": {
    "relationType": "Generalization",
    "direction": "ST",
    "splitLevel": 1
  }
}

XField Visual Settings (xFieldsSettings)

This object tells Termboard which XField should control which visual property.

Key	Description
labelField	Which XField to show alongside the Term name.
backgroundColorField	XField ID controlling the Term background color.
borderColorField	XField ID controlling the Term border color.
shapeField	XField ID controlling the Term shape.
sizeField	XField ID controlling the Term width/height.
lineColorField	XField ID controlling the Relation line color.

---

Data

The data object contains the actual elements of the diagram.

Terms (Nodes)

Terms represent entities or concepts.

Property	Alias	Type	Description
id	-	string	A unique ID (GUID recommended).
name	-	string	The text displayed on the node.
type	-	string	term, concept, property, or group.
description	-	string	Detailed description.
additionalInformation	additional_info	string	Extra technical notes (supports Quill.js HTML).
parent	-	string	The id of the parent group node.
x, y	xpos, ypos	number	Absolute coordinate in diagram space.
synonyms	-	array	List of string aliases for the term.
style_*	-	any	Flattened style (e.g., style_backgroundColor).
xFields_*	-	any	Flattened XField value (e.g., xFields_Branch).

IMPORTANT

Standard style properties include: style_backgroundColor, style_borderColor, style_fontColor, style_fontSize, style_fontType, style_shape, style_lineStyle, style_width, style_height.

Relations (Edges)

Relations represent the connections between Terms.

Property	Alias	Type	Description
id	-	string	Unique ID for the relation.
source	sourceId, sourceTerm	string	The id of the source Term.
target	targetId, targetTerm	string	The id of the target Term.
name	relation, relationName	string	Label of the relation.
relationType	-	string	Semantic category (e.g., Generalization, Composition).
cardinality	-	string	Target cardinality (e.g., 1, *).
cardinalitySource	-	string	Source cardinality.
additionalInformation	additional_info	string	Extra notes (supports Quill.js HTML).
style_*	-	any	Flattened style (e.g., style_lineColor).

---

Technical Considerations

1. Unique Identifiers

While Termboard can resolve human-readable names to IDs during import, a full project JSON should use unique, immutable IDs (GUIDs) for all references.

2. Flattening Convention

Termboard uses a flattened naming convention within the data arrays to simplify specific processing steps.

• Styles: Prefixed with style_ (e.g., style_backgroundColor).
• Extra Fields: Prefixed with xFields_ followed by the name (not ID) of the field (e.g., xFields_Branch).

3. Coordinate System

If x and y are omitted, Termboard will apply an automatic layout upon loading. A value of 0.90909 for both x and y indicates the node has no fixed position.

4. Semantic Resolution

Termboard automatically attempts to categorize relations based on their name if no relationType is provided. Explicitly providing relationType (e.g., Generalization) ensures correct hierarchical rendering and semantic checks.

---

Full Example

{
  "metadata": {
    "name": "Knowledge Model",
    "id": "model-001",
    "xFields": [
      {
        "id": "xf-1",
        "name": "Category",
        "type": "dropdown",
        "scope": "terms",
        "values": ["Technical", "Business"],
        "colors": { "Technical": "#1E88E5", "Business": "#43A047" }
      }
    ],
    "xFieldsSettings": {
      "backgroundColorField": "xf-1"
    }
  },
  "data": {
    "terms": [
      {
        "id": "node-1",
        "name": "Neural Network",
        "type": "concept",
        "x": 100,
        "y": 100,
        "style_backgroundColor": "#1E88E5",
        "xFields_Category": "Technical"
      }
    ],
    "relations": [
      {
        "id": "rel-1",
        "source": "node-1",
        "target": "node-2",
        "name": "is a",
        "relationType": "Generalization"
      }
    ]
  }
}