The .farki File Format: Design Decisions

The .farki file format is Farkitect’s native format for importing and exporting models. It’s not a binary blob or a proprietary archive — it’s human-readable JSON that you can open in any text editor and understand.

This is a deliberate design choice with specific goals.

Design Goals

1. Portability

A .farki file is self-contained. It includes everything needed to recreate the package tree: elements, relationships, property values, diagrams (with node positions and edge waypoints), catalogs (with column configuration), and notation definitions. You can email it, put it in a shared drive, or attach it to a ticket — the recipient doesn’t need anything except Farkitect to open it.

2. Human Readability

The JSON structure mirrors the model’s logical structure. When you open a .farki file, you see packages containing elements containing property values — the same hierarchy you see in the Explorer. Field names are descriptive: name, type, classifier, propertyValues, notation.

This matters for debugging, auditing, and understanding. If an import fails or a model looks wrong, you can open the file and see exactly what’s in it.

3. Version Control Friendliness

Because .farki files are text-based JSON, they work well with Git and other version control systems:

• Diffs are meaningful — when a model changes, git diff shows exactly which elements, properties, or diagram positions changed
• Merges are possible — text-based formats can be merged (with care)
• History is browsable — git log on a .farki file shows the evolution of the model over time

This makes .farki files suitable for infrastructure-as-code workflows where models are tracked alongside the systems they describe.

4. LLM Interaction

The human-readable, self-describing nature of .farki files makes them ideal for use with large language models. An LLM can:

• Read a .farki file to understand a model’s structure — what elements exist, how they’re related, what properties they carry
• Generate M1 model content against an existing M2 metamodel — for example, “create a Business Model Canvas for this company” by producing a valid .farki file
• Create new M2 metamodels — define element types, relationship types, notation, and constraints as a .farki file that Farkitect can import
• Update and extend existing models — add elements, fill in property values, or create relationships by modifying the JSON structure

This is a deliberate design advantage. The format is not just machine-parseable but machine-understandable. An LLM can look at an M2 metamodel .farki file, understand the element types and their properties, and then generate valid M1 instances without any special tooling or API access.

The Farquind Yachts case study models were generated this way — an LLM read the case study document and the M2 metamodel definitions, then produced .farki files with realistic M1 model content.

Structure

A .farki file has this top-level structure:

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

Scope

• package — the file contains a single package tree. Use File > Import… to bring it into an existing project.
• project — the file contains a complete project with multiple packages. Use File > New Project… > From File to create a new project from it.

The $id Convention

Every element in a .farki file has a $id — a unique, human-readable slug (kebab-case) that identifies it within the file. For example:

{
  "name": "FQ Vessels",
  "type": "Class",
  "$id": "fq-vessels",
  "classifier": "M2 ArchiMate 3.2:Application Component"
}

$id values are:

• Unique within the file — no two elements share a $id
• Kebab-case — lowercase with hyphens (e.g., fq-vessels, customer-segment)
• Used for cross-references — relationships reference their source and target by $id, not by name
• Stable — renaming an element in the UI doesn’t change its $id

Classifiers

M1 elements reference their M2 type using a classifier field with the format Package Name:Type Name:

"classifier": "M2 ArchiMate 3.2:Application Component"

This lets the import process resolve the M2 type by name, even across different projects or Farkitect installations.

Property Values

Property values are stored as a flat object mapping property names to values:

"propertyValues": {
  "Lifecycle Status": "active",
  "Service Date": "2025-06-15"
}

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

Why Not XML? Why Not a Database Dump?

• XML would be more verbose, harder to read, and more painful to generate with LLMs. JSON is the lingua franca of web development and AI.
• A database dump would be tied to Farkitect’s internal storage format. .farki is an interchange format — it’s designed to be understood by humans and tools, not to mirror database internals.
• A binary format would be smaller but opaque. The readability and diff-ability of JSON outweigh the size cost for the file sizes involved in modelling.