How to upgrade a metamodel

When a new version of a metamodel arrives — ArchiMate 4 to 4.1, or a corrected copy of your own metamodel — you want your models to move with it, not break.

Upgrading changes the metamodel in place. Every model element keeps its identity: same id, same diagrams, same relationships, same history. Only the definitions change. Anything the new version would break — a type your models still use that the new version removed, a rule your relationships still need — is kept safely until you decide what to do with it.

You need contributor access or above.

When to use it

You want to…	Use
Move to a new version of the same metamodel, or a corrected copy	Upgrade (this page)
Move a model to a different metamodel that sits beside it (another notation)	Migrate a model
Deal with definitions an earlier upgrade kept as retired	Resolve Retired Types (below)

Two things you should not do with a metamodel your models use:

Replace it on import. Farkitect won’t let you: Replace would re-create the metamodel and leave every model element without a type. The import dialog offers Upgrade… instead.
Delete it and import the new one. Deleting a metamodel deletes every model element that uses it.

Before you start

The new version as a .farki file. It is applied to the metamodel you choose, so its name can stay the same.
Somewhere to save a backup. A backup of the whole project is required before anything changes. It is your way back.
A few minutes without other edits to the metamodel. If someone changes the project between planning and applying, Farkitect notices and asks you to plan again — nothing is applied from an out-of-date plan.

1. Start the upgrade

Either:

In the Explorer, right-click the metamodel (its root package, e.g. M2 ArchiMate 4) and choose Upgrade from File…, then pick the new version’s file; or
Use File › Import Package… with the new version’s file. When the dialog says the metamodel already exists and models use it, click Upgrade….

The Upgrade dialog opens and plans the upgrade. Planning reads the metamodel and what your models use; it changes nothing.

The dialog stays open beside your work, so you can look at the Explorer and diagrams while you read the plan.

2. Read the plan

The first line summarises the plan, e.g. 2 held back · 1 retired · 3 added · 14 changed · 1 removed. Below it, the plan is grouped, with what needs your attention first:

Group	What it means
Held back	A change in the new version that would make existing elements or relationships invalid — for example a relationship rule removed while relationships still use it. Not applied; the old rule stays.
Retired	Removed in the new version but still used by your models. Kept, hidden from the palette, and marked retired.
Deleted	Elements or values you chose to delete (see step 3).
Mapped	Elements or values you chose to give another type (see step 3).
Values converted	Stored values rewritten to fit a new definition — e.g. a property that became a whole number.
Ambiguous names	Several definitions share a name, so they are treated as removed and added rather than guessed.
Added	New in this version. Available at once.
Changed	Same definition, updated — notation, notes, rules, a rename the new version declares. Elements that use it are unaffected.
Moved	Same definition, in another package of the metamodel.
Removed	Not in the new version and not used by any model.

If the plan says Nothing to change: this metamodel already matches the file, there is nothing to do. If it says Nothing changes as the plan stands, the file differs only in things your models use: decide what to do with them (step 3), or leave them as they are.

Upgrading with no decisions is always safe. Nothing your models use is lost: it is kept as retired or held back. You can stop here and go to step 4, and decide later with Resolve Retired Types.

3. Decide (optional)

Above the groups, the dialog lists everything you can decide. Each item starts on the safe choice.

Item	Choices (default first)
Removed types still in use	Keep, retired · Map to… another type of the same kind · Delete its elements
Removed properties with values	Keep, retired · Map to… another property the element type has · Move values to notes · Discard values
Removed values still in use (enumeration values)	Keep, retired · Map to… another value · Clear values
Values that don’t fit a new property type	Keep, retired (the old values stay on a retired copy of the property) · Move values to notes · Clear values
Relationships the new rules don’t allow	Keep (the rule they need stays) · Map to… a relationship type that allows them · Delete
Types made abstract that have elements	Keep (the type stays concrete) · Map to… a concrete subtype · Delete
Superclasses removed that values depend on	Keep · Move values to notes · Discard values

What “Map to…” does

The element stays the same element: same id, name, notes, package, place on every diagram, nesting and relationships. Only its type changes, so diagrams redraw it with the new type’s appearance.

Values move to the new type’s properties with the same name, converted where needed. Values that have nowhere to go, or don’t fit, are added to the element’s notes as lines like Contract type (Contract, retired in 4.1): Fixed price — or discarded, if you choose Other values → discard.
Relationships are checked again against the new type. If a relationship would no longer be allowed, it appears as a new item under Relationships the new rules don’t allow, set to Keep, with its own choices. Nothing is left invalid.

Deciding element by element

For types, relationship rules and abstract changes, click Decide each (N) to give individual elements their own choice — for example, map most of a type’s elements but delete one. As above follows the item’s choice. Click an element’s name to select it in the Explorer.

Update the plan

As soon as you change a choice, the dialog says Your choices have changed and shows Update plan instead of the backup step. Click it: the plan is worked out again with your choices, so you can see exactly what they do before anything happens. The plan stays on screen while it updates.

Changing how a type is handled starts the relationship choices over, because which relationships need a decision depends on it. Decide the type first, Update plan, then decide the relationships.

4. Back up and apply

Click Back up and apply…. The save dialog opens immediately. Choose where to save the backup — take your time. The suggested name says what it is, e.g. Farquind (before upgrade M2 ArchiMate 4 to 4.1 2026-09-29 1847).farki.
Farkitect exports the whole project into that file, with progress. When it’s saved you’ll see Backup saved: and the file name.
- If you cancel the save dialog, or the save fails, nothing has changed; click Back up and apply… to try again.
- Some browsers can’t confirm that a download finished. The dialog then says so and names the file: check it’s in your downloads, tick the box, and click Continue.
Click Apply upgrade. Keep the dialog open until it finishes.

When it’s done, the dialog says what happened to your models — how many elements were given another type or deleted as you chose, how many definitions were retired and changes held back — and the result of an integrity check.

The backup must be less than an hour old when you apply. If you leave the dialog longer, you’ll be asked to back up again.

5. Check the result

Diagrams that are open update by themselves. Elements you mapped are in the same place, drawn with their new type.
Retired definitions show a muted retired label in the Explorer, and elements of a retired type are dimmed on diagrams with a small retired chip. The Show only retired button (archive icon) on the Explorer toolbar lists them all.
The status bar integrity indicator should be clean.
Select the metamodel in the Explorer: its Properties show the Version and the latest upgrade — when, who, what was retired, held back, mapped or deleted, and the backup file.
The Log panel records the upgrade.

Resolve retired types later

Retired definitions can stay as long as you like: your models remain valid, and nothing new can use them. When you’re ready to deal with them:

Right-click the metamodel and choose Resolve Retired Types…
The same dialog opens, without a file. Every retired type, property and value still in use is listed with the choices from step 3; retired definitions nothing uses any more are removed.
Decide, Update plan, then Back up and apply… as in step 4.

If nothing is retired, the dialog says so.

Changes that were held back aren’t stored separately: to revisit them, run Upgrade from File… again with the same file. Its plan shows them again, with their choices.

Undo an upgrade

The backup is a complete copy of the project from just before the upgrade. To go back to it, create a project from it on the dashboard: New Project › From File, then choose the backup. This makes a new project; the upgraded one is left as it is, so you can compare the two.

If something goes wrong

What you see	What it means, and what to do
The project changed — The project changed since this upgrade was planned	Something was edited after planning. Click Plan again; you’ll need a new backup. Nothing was applied.
The backup couldn’t be saved	Nothing has changed. Click Back up and apply… again, and choose a folder you can write to.
The upgrade didn’t complete	Whatever was already applied left your models valid. Run Upgrade from File… again with the same file: the new plan contains only what’s left. The backup holds the project as it was.
A metamodel’s Properties say the last upgrade didn’t complete	As above: upgrade again from the same file to finish it.
Replace isn’t offered when importing a new version	Models use that metamodel. Use Upgrade… in the same dialog.

For metamodel authors

A new version upgrades more smoothly when its .farki file says what changed:

version on the root package, e.g. "version": "4.1". It’s shown in the metamodel’s Properties and names the upgrade.
formerNames on a type, property, enumeration or value you renamed, e.g. "formerNames": ["Contract"]. Without it, a rename looks like a removal plus an addition; with it, the definition is simply renamed and every model keeps using it.
retired is written by Farkitect during an upgrade. Don’t add it to a new version.

See the .farki format reference for the details, and Metamodel upgrades for why upgrades work this way.