.farki File Format

The .farki format is Farkitect’s native interchange format — human-readable JSON for importing and exporting models.

Top-Level Structure

{
  "$format": "farki/1.5",
  "scope": "package",
  "metadata": { ... },
  "package": { ... }
}

Field	Required	Description
$format	Yes	Format version identifier. Exports emit "farki/1.5"; imports also accept the older "farki/1.4", "farki/1.3", "farki/1.2" and "farki/1.1" (see Format versions)
scope	Yes	"package" (single package tree) or "project" (complete project)
metadata	Yes	File metadata including creation timestamp and content summary
package	Package scope	The root package (when scope = “package”)
packages	Project scope	Array of root packages (when scope = “project”)

Metadata

"metadata": {
  "createdAt": "2026-03-15T00:00:00.000Z",
  "summary": [
    {
      "name": "M2 ArchiMate 3.2",
      "layer": "M2",
      "elementCount": 61
    }
  ]
}

Project-scope files may also include name, description, and sourceProject.

Package

{
  "name": "M1 Farquind Applications",
  "layer": "M1",
  "imports": ["M2 ArchiMate 3.2"],
  "elements": [ ... ],
  "diagrams": [ ... ],
  "catalogs": [ ... ],
  "boards": [ ... ]
}

Field	Required	Description
name	Yes	Package name
notes	No	Markdown description
layer	Yes	"M3", "M2", or "M1"
packageKind	M2 only	"standard" or "common"
version	No	M2 root only: the metamodel’s version, e.g. "4.1". Shown in its Properties and in the record of each upgrade
isReadOnly	No	true to prevent modification
imports	No	Array of M2 package names this package uses
elements	No	Array of child elements
diagrams	No	Array of diagrams
catalogs	No	Array of catalogs
boards	No	Array of board (Kanban) views

Elements

Class (Element Type or Instance)

{
  "name": "FQ Vessels",
  "type": "Class",
  "$id": "fq-vessels",
  "classifier": "M2 ArchiMate 3.2:Application Component",
  "notes": "Fleet telemetry and diagnostics platform.",
  "propertyValues": {
    "Lifecycle Status": "active"
  }
}

Package (Nested)

{
  "name": "Customer Systems",
  "type": "Package",
  "$id": "customer-systems",
  "elements": [ ... ]
}

Relationship

{
  "name": "FQ Orders serves Fleet Dashboard",
  "type": "Relationship",
  "source": "fq-orders",
  "target": "fleet-dashboard",
  "$id": "fq-orders-serves-fleet-dashboard",
  "classifier": "M2 ArchiMate 3.2:Serving"
}

Owned (Nested) Elements

{
  "name": "Entity",
  "type": "Class",
  "$id": "entity",
  "nestedElements": [
    {
      "name": "customerId",
      "type": "Class",
      "$id": "customer-id",
      "classifier": "M2 Logical Data Model:Attribute",
      "propertyValues": {
        "Data Type": "integer",
        "Is Primary Key": "true"
      }
    }
  ]
}

The $id Convention

Every element has a $id — a unique, human-readable identifier within the file.

Rule	Example
Unique within the file	No two elements share a $id
Kebab-case	fq-vessels, customer-segment
Used for cross-references	Relationships reference source/target by $id
Stable	Renaming in the UI doesn’t change $id

A diagram, catalog or board may also have a $id, which a view link uses to refer to it. Those are a separate set: a view’s $id must be unique among the file’s views, and may match an element’s.

Classifier References

M1 elements reference their M2 type using Package Name:Type Name:

"classifier": "M2 Business Model Canvas:Customer Segment"

Property Values

Flat object mapping property names to values:

"propertyValues": {
  "Lifecycle Status": "active",
  "Start Date": "2025-06-15",
  "Is Required": "true"
}

Enumeration values use the machine value, not the display name.

Diagrams

{
  "name": "Application Overview",
  "notation": "M2 ArchiMate 3.2",
  "viewport": { "panX": 0, "panY": 0, "zoom": 1.0 },
  "nodes": [
    { "element": "fq-orders", "x": 100, "y": 200, "width": 160, "height": 80 },
    { "element": "fleet-dashboard", "x": 400, "y": 200, "width": 160, "height": 80 }
  ],
  "edges": [
    { "sourceElement": "fq-orders", "targetElement": "fleet-dashboard", "relationship": "fq-orders-serves-fleet-dashboard" }
  ]
}

An edge names the elements behind its two nodes (sourceElement, targetElement) and the relationship it draws (relationship), all by $id. Its lineStyle is the edge’s routing ("direct", "custom", "tree-vertical"…), not its dash pattern.

Diagram nodes and edges may also carry per-diagram label overrides, emitted only when set:

Field	On	Description
showLabel	node / edge	false hides the label on this diagram (default shown)
labelOffset	node / edge	{ x, y } position of a dragged label, relative to its default anchor
labelSize	node / edge	{ width, height } of a manually resized label

Appearance overrides

A node or edge may override its type’s appearance on this diagram only (the Appearance section). Each field is emitted only when set; an absent field means “use the type’s value”.

Field	On	Description
fillColor	node	Fill colour — a colour pair
borderColor	node	Border colour — a colour pair
textColor	node	Text colour (name, compartments, icon, outside label) — a colour pair
borderWidth	node	Border width in pixels
borderStyle	node	"solid", "dashed", "dotted" or "none"
shadow	node	true or false
textHAlign / textVAlign	node	"left" / "center" / "right", "top" / "middle" / "bottom"
lineColor	edge	Line colour (and filled markers) — a colour pair
labelColor	edge	Every text on the edge: name, roles, multiplicities, property label — a colour pair
lineWidth	edge	Line width in pixels
linePattern	edge	Dash pattern: "solid", "dashed" or "dotted"

{ "element": "fq-vessels", "x": 100, "y": 200, "width": 160, "height": 80,
  "fillColor": { "light": "#FFE0B2", "dark": "#B26A00" }, "shadow": false }

The diagram itself may carry showStereotypes, showEdgeLabels (the master switch for relationship labels), showCompartments, showPropertyNames and showEmptyProperties — all booleans, omitted when at their default (true, except showEdgeProperties).

edgeLabelContent says what a shown relationship label reads: "name" (the default, omitted) for the relationship’s name, or "verb" for the source-to-target verb of its type. It has no effect while showEdgeLabels is false.

View links

A diagram may carry links, each a view link to another diagram, a catalog or a board:

{
  "name": "Start Here",
  "links": [
    { "view": "application-overview", "x": 40, "y": 40, "width": 180, "height": 28 },
    { "view": "revenue-streams", "package": "M1 Finance", "x": 40, "y": 80, "width": 240, "height": 60,
      "label": "2. Revenue", "border": true }
  ]
}

Field	Description
view	The $id of the diagram, catalog or board linked to. That view carries the same $id: { "$id": "application-overview", "name": "Application Overview", ... }
package	The name of the top-level package holding the view, when it is not the one the link is in. Found only in project-scope files
x, y, width, height	Position and size on the canvas
label	Optional. Shown in place of the view’s name
border	Optional. true draws the link as a bordered tile

• An export gives a $id only to the views that a link points to
• A package-scope file cannot carry a link to a view outside its package. Such links are left out on export, and Farkitect says how many
• A project-scope file keeps every link
• On import, a link whose view is not in the file is skipped with a warning

M2-Specific Fields

M2 element types include additional fields:

Field	Description
notation	Visual appearance (shape, colours, icon, compartments) — see Colour values and the notation reference
palette	Palette configuration (usually {})
properties	Array of Property definitions
constraints	Relationship constraints (validPairs)
packageRole	Sub-package role (elementTypes, relationshipTypes, etc.)
formerNames	Names this type had in earlier versions, e.g. ["Contract"]. An upgrade treats a matching old type as renamed, so models keep using it. Also allowed on properties, enumerations and enumeration values
retired	{ "since": "4.1", "reason": "…" } — kept only because existing models use it; hidden from the palette and pickers. Written by Farkitect during an upgrade; don’t add it yourself. Also appears on properties, enumerations and enumeration values

Versions and renames

A new version of a metamodel upgrades most smoothly when it says what changed:

{
  "name": "M2 ArchiMate 4",
  "layer": "M2",
  "packageKind": "standard",
  "version": "4.1",
  "elements": [
    {
      "name": "Physical Equipment",
      "type": "Class",
      "$id": "equipment",
      "formerNames": ["Equipment"],
      "notation": { "type": "element" }
    }
  ]
}

Enumeration values take the same field: { "name": "All", "value": "and", "formerNames": ["And"] }. An enumeration value may only have name, value, formerNames and retired.

Colour values

Every colour in a .farki file — in an element type’s or relationship type’s notation, and in a diagram’s appearance overrides — is a pair: one value for the light theme and one for the dark theme.

"fillColor": { "light": "#AFCFD8", "dark": "#AFCFD8" }

• A missing side means Auto for that theme: the theme’s default, or a colour worked out from another (see How colours work in light and dark mode). An absent field means Auto in both themes.
• Colours are CSS colours, normally #RRGGBB.
• When importing, a plain string is also accepted and means the same colour in both themes: "fillColor": "#AFCFD8". Exports always write the pair.

The colour fields in notation:

Field	On	Description
fillColor	element type	Fill
borderColor	element type	Border
foldColor	element type	The folded corner (when foldCorner is true)
textColor	element type	Text, icon and outside label
lineColor	relationship type	Line and filled markers
labelColor	relationship type	Every text on the edge

A relationship type’s dash pattern is linePattern ("solid", "dashed", "dotted").

"notation": {
  "type": "relationship",
  "linePattern": "dashed",
  "lineColor": { "light": "#16A34A", "dark": "#4ADE80" },
  "targetMarker": { "shape": "arrow" }
}

Leave lineColor, borderColor, foldColor and textColor out unless the notation needs a specific colour: Auto gives charcoal lines and borders in light mode and off-white in dark, a fold shaded from the fill, and text that contrasts with the fill.

Boards

A board is a Kanban view of the instances of one element type, grouped into columns by an enumeration property.

{
  "name": "Application Component Board",
  "classifier": "M2 ArchiMate 3.2:Application Component",
  "groupByProperty": "prop:lifecycle-status",
  "columnConfig": {
    "order": ["__none__", "active", "retiring"],
    "hidden": [],
    "limits": [{ "key": "active", "max": 8 }]
  },
  "cardConfig": { "properties": ["prop:owner"] },
  "sortState": [{ "id": "name", "desc": false }],
  "cardRanks": [{ "element": "fq-vessels", "rank": 1000 }]
}

Field	Description
classifier	The element type whose instances become cards (Package:Type)
groupByProperty	The enumeration property that defines the columns, as a portable prop:{$id} slug
columnConfig	Column order / hidden / collapsed (by literal storage value; "__none__" is the “(No value)” column), limits, and width
cardConfig.properties	Which property values appear on cards (prop:{$id} refs)
sortState / filterState	Card ordering and name filter
cardRanks	Manual card order ({$id} refs) when the board uses Manual sort

Enum literals and properties are stored as portable slugs so a board survives round-tripping through .farki even if display names change. A board whose groupByProperty can’t be resolved on import is dropped with a warning.

.farki.zip Archives

When a package contains attachments (images or files) and you export with attachments, Farkitect writes a .farki.zip archive instead of a plain .farki:

mypackage.farki.zip
├── model.farki                       # the JSON model (as above)
└── files/
    └── <element-$id>/<fileName>       # one folder per attachment-carrying element

Inside model.farki, each attachment-carrying element gains an attachmentFile descriptor (M1 only):

"attachmentFile": {
  "fileName": "architecture.xlsx",
  "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "size": 245760
}

On import, a .farki.zip is auto-detected and its payloads are restored to the matching elements. A plain .farki (the “Model only” export) omits the payloads; the descriptor is stripped and the model still loads, just without the files.

Format versions

Version	What changed
farki/1.5	A diagram’s edgeLabelContent: relationship labels can show the type’s verb in place of the relationship’s name. Nothing else changed, so a 1.4 file is also a valid 1.5 file
farki/1.4	View links: a diagram’s links, and an optional $id on a diagram, catalog or board for a link to refer to. Nothing else changed, so a 1.3 file is also a valid 1.4 file
farki/1.3	Colours became light/dark pairs. Renamed: element-type color → fillColor; relationship-type color → lineColor and lineStyle → linePattern; diagram edge color → lineColor. New: textColor, labelColor, and the node and edge appearance overrides textColor, borderStyle, shadow, labelColor, linePattern
farki/1.2	Notation as composable primitives: a silhouette shape plus fillMode, borderStyle, foldCorner and others; relationship markers as { "shape", "fill" }
farki/1.1	Legacy notation: special shapes such as note, text and boundary, and marker strings such as filledDiamond

Older files import without changes on your part — Farkitect converts them on the way in:

• Every single colour becomes the same colour in both themes, under its new name.
• A line or border colour that is a neutral grey (for example the old default #DDDDDD) becomes Auto, so it follows the theme: charcoal in light mode, off-white in dark.
• In the built-in metamodels, the few line colours that carry meaning (for example M2 Common’s green Trace, Realization, Annotation and Dependency lines) get a curated light and dark pair.
• Every other colour is kept as it is.