Notation System Reference
Farkitect’s notation model (format farki/1.5) treats appearance as a set of independent compositional primitives. shape controls only the outline; fill, border, body content, icon, and label placement are separate fields that combine freely. This replaced the older model where a handful of fixed shapes (note, boundary, text) each baked in their own fill and border.
Node Shapes
Section titled “Node Shapes”shape is the silhouette (outline) only:
| Shape | Description | Typical Use |
|---|---|---|
rectangle |
Square corners | Most element types |
rounded |
Rounded corners | Active elements, processes |
pill |
Fully rounded ends | Tags, states |
chamfered |
Cut corners | Artifacts, cut-corner boxes |
ellipse |
Ellipse / circle | BPMN events, start/end nodes |
diamond |
Diamond | Gateways, decisions |
chevron |
Point on the right edge | Process steps, stages, value chains |
The legacy note, boundary, and text looks are now compositions of a rectangle plus primitives (a folded corner; a dashed border with no fill; no border and no fill).
Compositional Primitives
Section titled “Compositional Primitives”| Field | Values | Description |
|---|---|---|
fillMode |
solid / none |
Whether the body is filled with fillColor or transparent |
borderStyle |
solid / dashed / dotted / none |
Outline stroke style |
bodyContent |
name / notes / image |
What fills the node body (see below) |
showIcon |
Boolean | Whether the type icon is drawn |
foldCorner |
Boolean | Draw a folded top-right corner (the Note look) |
labelPlacement |
inside / outside |
Where the element name sits (see below) |
iconPlacement |
top-right (default) / top-left / bottom-left / bottom-right |
Which corner the type icon takes. A chevron’s point is on the right, so those types usually set top-left. When the icon takes bottom-right, the drill-down and attachment badges move to bottom-left |
Colours and border (element types)
Section titled “Colours and border (element types)”Every colour is a pair — a value for the light theme and a value for the dark theme, { "light": "#RRGGBB", "dark": "#RRGGBB" }. A missing side is Auto for that theme. See Colour Model.
| Field | Type | Auto means |
|---|---|---|
fillColor |
Colour pair | The theme’s node background |
borderColor |
Colour pair | Charcoal in light mode, off-white in dark |
textColor |
Colour pair | Black or white, whichever reads best on the fill. It colours the name, stereotype, compartments, the icon (at 60% opacity) and an outside label; on Auto, an outside label uses the theme’s label colour |
foldColor |
Colour pair | The fill, about 15% darker in light mode and 15% lighter in dark |
defaultBorderWidth |
Number (px) | 2px |
shadow |
Boolean | On. A soft shadow in light mode, a light halo in dark mode |
bodyContent
Section titled “bodyContent”| Value | Meaning |
|---|---|
name |
The element name (default) |
notes |
The element’s notes text (text-annotation style) |
image |
The element’s attached image fills the body, letterboxed. Requires the type to declare attachment: "image". Shows a dashed “No image” placeholder until an image is uploaded. |
labelPlacement
Section titled “labelPlacement”| Value | Behaviour |
|---|---|
inside |
Default. Name sits inside the body; the type icon is small in the top-right corner (ArchiMate/UML convention). |
outside |
The icon renders centred and scaled in the body, and the name renders as an external, draggable label below the node (BPMN convention for events, gateways, data objects). |
labelPlacement: outside is for icon-centric symbols where the icon is the symbol. It is ignored when the type has compartments (compartmented boxes are always inside-labelled). Set it in the M2 Notation Editor via the Label Placement dropdown; the canonical form omits the field when inside.
Compartments
Section titled “Compartments”An element type can split its body into stacked bands via compartments[]. The first band is normally the name (the title); content bands sit beneath it, separated by dividers. A type with no compartments renders as a plain node.
| Field | Values | Description |
|---|---|---|
id |
String | Unique within the type |
contentType |
name / properties / attachment / subordinates / methods |
What the band shows |
label + showLabel |
String + boolean | Optional caption above the band |
showPropertyLabels |
boolean (default true) |
properties bands only. false locks the band to values only on every diagram — a value line rather than a labelled list (M2 Common’s Hyperlink uses it for its URL line). Whether names show is otherwise a per-diagram choice: the diagram toolbar’s property names and empty properties toggles (see Diagram view settings) |
style.vAlign |
top (default) / middle / bottom |
Vertical placement of the band’s content. A content band stretches to fill the node, so middle centres a single line instead of leaving it at the top |
subordinateTypeId |
String | subordinates bands only — which subordinate type the band lists |
style (other) |
background, fontWeight, fontStyle |
Band styling |
An attachment band shows the attached file’s name and size, or a plain “No file” when there is none. It needs no configuration — it follows the element’s attachment, so it is only offered on a type that declares the attachment capability.
Set all of these in the M2 Notation Editor under Compartments: tick Name band and Property values, then Show property names and Values V-Align for the properties band.
M2 Common’s Hyperlink is exactly this composition — a bold name band above a value-only, centred band holding its url-formatted property — so any metamodel can produce the same result without custom code.
Diagram View Settings
Section titled “Diagram View Settings”How a diagram shows the property rows inside compartments is decided per diagram, not by the metamodel. Three toolbar toggles, all saved with the diagram:
| Toggle | Default | Effect |
|---|---|---|
| Property compartments | on | Whether compartments render at all |
| Property names | on | Off renders each row as its value alone. Disabled while compartments are hidden |
| Empty properties | on | Off omits rows that have no value and no M2 default. Disabled while names are hidden (a value-only row with no value is already nothing) |
A band whose M2 sets showPropertyLabels: false stays value-only whatever the diagram’s property names toggle says. The same two toggles apply to property rows on relationship labels. Node sizes are not changed by the toggles.
Attachment Capability
Section titled “Attachment Capability”Set on an M2 element type to turn on the attachment facility for its instances:
| Field | Values | Description |
|---|---|---|
attachment |
image / file |
Enables a single attachment per instance; picks the Properties-panel label, file filter, and size limit (image → images ≤ 4 MB, file → any type ≤ 20 MB) |
containment |
model / visual / none |
How the node hosts children. none (used by Image) makes it a pure backdrop — dropped elements are never nested, moved, or resized by it |
A property whose format is "url" renders as a live clickable link on diagram nodes — this is how the Hyperlink type works, and it applies to any metamodel.
Notation Object (Relationship Types)
Section titled “Notation Object (Relationship Types)”| Field | Type | Description |
|---|---|---|
type |
"relationship" |
Always “relationship” |
icon |
String (SVG) | Icon for palette and explorer |
linePattern |
solid / dashed / dotted |
Stroke dash pattern (not the routing, which is a per-edge setting) |
sourceMarker / targetMarker |
Marker | End markers (see below) |
lineColor |
Colour pair | Line colour. Auto is charcoal in light mode, off-white in dark. Filled markers are drawn in this colour |
labelColor |
Colour pair | The name, role names and multiplicities. Auto uses the theme’s label colours |
defaultLineWidth |
Number (px) | Default line width |
s2tVerb |
String | Source-to-target verb (e.g., “serves”) |
t2sVerb |
String | Target-to-source verb (e.g., “is served by”) |
showMultiplicities |
Boolean | Display multiplicity labels |
showRoleNames |
Boolean | Display role name labels |
Edge End Markers
Section titled “Edge End Markers”A marker is a shape plus an optional fill:
| Marker shape | Fill applies? |
|---|---|
none |
— |
arrow (open stick arrow) |
No |
triangle (closed head) |
Yes — filled or hollow |
diamond |
Yes |
circle |
Yes |
bar |
No |
Subordinate Types
Section titled “Subordinate Types”Define owned element types that render inside compartments.
| Field | Type | Description |
|---|---|---|
id |
String | Unique identifier referenced by compartments |
label |
String | Display label |
classifier |
String | $id of the owned element type |
displayTemplate |
String | Template for rendering (e.g., {name} : {Data Type}) |
Label Visibility
Section titled “Label Visibility”Label placement is an M2 (author) decision; whether a specific label shows is an M1 (per-diagram) decision:
| Setting | Scope | Where |
|---|---|---|
| Hide Label / Show Label | Per node | Node context menu (and a batch action for multi-select) |
| Hide Label / Show Label | Per edge (main label) | Edge or edge-label context menu |
| Show/Hide relationship labels | Whole diagram (edges) | Diagram toolbar |
The per-edge toggle is subtractive — it can hide an edge’s label when the diagram shows labels, but cannot force one on when the diagram-level switch is off. Hiding a label is a content decision, so it is not cleared by “Revert Appearance to Default”. External (outside-placement) labels can also be dragged and resized; their per-diagram position and size persist with the diagram.
Stereotypes
Section titled “Stereotypes”Stereotypes display the M2 type name on diagram nodes (e.g., <<Application Component>>). Visibility is toggled per-diagram via the diagram toolbar.
Colour Model
Section titled “Colour Model”Diagrams have a light and a dark theme, and every colour has a value for each. For more on why, see How colours work in light and dark mode.
- A colour is a pair,
{ "light": …, "dark": … }. A missing side is Auto: the theme’s default, or a colour derived from another one (text from the fill, fold from the fill). - M2 notation sets each type’s colours: fill, border, text and fold for element types; line and label for relationship types.
- M1 diagram overrides change one node or edge on one diagram, in the Properties panel’s Appearance section. They are pairs too. See How to change a node’s or edge’s appearance on one diagram.
- Lookup order, for each theme separately: the diagram override, then the M2 notation, then Auto. An override set for only one theme falls back to the M2 colour in the other.
- Revert Appearance to Default removes a node’s or edge’s overrides.
- Non-compliant nodes and edges stay grey whatever their colours, so compliance problems stay visible.
Auto defaults
Section titled “Auto defaults”| Colour | Light theme | Dark theme |
|---|---|---|
| Node border | #3f3f46 (charcoal) |
#e4e4e7 (off-white) |
| Edge line | #3f3f46 (charcoal) |
#e4e4e7 (off-white) |
| Canvas | #fafafa |
#18181b |
Contrast warnings
Section titled “Contrast warnings”The notation editor and the Appearance section show ⚠ when a chosen colour is hard to read in either theme. The warning never blocks saving.
| Pair | Warns below |
|---|---|
| Text against its fill; outside and edge labels against their background | 4.5 : 1 |
| A line, or the border of an unfilled node, against the canvas | 3 : 1 |
Auto colours never warn.