Archi Semantic Core: Using Archi Models from TypeScript

How to read a .archimate file and work with its elements, relationships, and views from your own application.

Archi stores its models in .archimate files.

Although we normally interact with them through the editor, these files contain the complete model: elements, relationships, folders, views, diagram objects, connections, properties, geometry, and other data used by Archi.

archi-semantic-core gives you access to that information from TypeScript without requiring you to understand how Archi structures its native XML internally.

In this article, we will see how to use it.

Installation

The package is available on npm:

npm install @cda/archi-semantic-core

The main operation is parseArchiModel:

import { parseArchiModel } from '@cda/archi-semantic-core';

const model = parseArchiModel(xml);

Here, xml contains the XML text of a native Archi model.

The result is a typed ArchiModel.

From there, you can start working directly with the model:

console.log(model.elements);
console.log(model.relationships);
console.log(model.views);

Instead of manually navigating XML nodes and namespaces, your application can work with concepts from the Archi model.

Reading a .archimate file

If you are working with Node.js, you can read the model directly from disk.

There is one important detail: a .archimate file can be plain XML, but Archi can also use a ZIP-based variant when the model contains embedded images.

To support both forms, use extractArchiModelXml:

import { readFileSync } from 'node:fs';

import {
  extractArchiModelXml,
  parseArchiModel
} from '@cda/archi-semantic-core';

const bytes = readFileSync('MyModel.archimate');

const xml = extractArchiModelXml(bytes);
const model = parseArchiModel(xml);

console.log(`Elements: ${model.elements.length}`);
console.log(`Relationships: ${model.relationships.length}`);
console.log(`Views: ${model.views.length}`);

With this small program, you can already open a model created in Archi and begin inspecting it.

The library deliberately keeps these responsibilities separate:

extractArchiModelXml retrieves the XML from the file, while parseArchiModel interprets the model stored inside it.

Working with elements

Elements are available through:

model.elements

You can iterate over them using normal TypeScript:

for (const element of model.elements) {
  console.log(element.name, element.type);
}

For example:

Customer Application ApplicationComponent
Customer Database Node
Process Payment BusinessProcess

The library preserves both the original type written by Archi and a cleaner semantic representation.

For example:

console.log(element.xsiType);
// archimate:ApplicationComponent

console.log(element.type);
// ApplicationComponent

This means your application can work directly with ApplicationComponent instead of repeatedly interpreting the namespace used in the XML.

You can also use ordinary JavaScript operations to query the model:

const applications = model.elements.filter(
  element => element.type === 'ApplicationComponent'
);

console.log(applications);

There is no special query language involved. You receive typed TypeScript structures and can process them using the language itself.

Working with relationships

Relationships are available through:

model.relationships

You can inspect them in the same way:

for (const relationship of model.relationships) {
  console.log(
    relationship.type,
    relationship.sourceId,
    relationship.targetId
  );
}

Archi connects model concepts through identifiers.

A relationship may therefore contain information such as:

{
  type: 'ServingRelationship',
  sourceId: 'id-application-a',
  targetId: 'id-application-b'
}

From there, you can build your own queries.

For example, to find all relationships originating from a particular element:

const outgoing = model.relationships.filter(
  relationship => relationship.sourceId === element.id
);

Some relationship types also contain Archi-specific information.

An AccessRelationship, for example, can expose its access type as:

• Read
• Write
• ReadWrite
• Unspecified

The library interprets Archi's native representation and exposes values that are easier for another application to consume.

Views: the model and its visual representation

This is where an important distinction appears.

An element in the model is not the same thing as the object that represents it in a diagram.

You can define an ApplicationComponent once and display it in several different views.

Each occurrence has its own position, dimensions, and visual context, but they all refer to the same underlying model element.

archi-semantic-core preserves both layers.

Views are available through:

model.views

For example:

for (const view of model.views) {
  console.log(view.name);
  console.log(view.diagramObjectIds);
}

Diagram objects preserve information such as their referenced Archi element, position, dimensions, nested objects, connections, and visual styling.

This makes the same parsed model useful for very different applications.

An analysis tool may only care about elements and relationships.

A renderer may also need geometry.

A converter may need properties and references.

The semantic core does not decide which information matters to each consumer. Its job is to expose Archi's model consistently.

Validating the model

The library also provides structural validation:

import {
  parseArchiModel,
  validateArchiModel
} from '@cda/archi-semantic-core';

const model = parseArchiModel(xml);

const result = validateArchiModel(model);

console.log(result.valid);
console.log(result.errors);

Validation can detect structural problems such as duplicate identifiers, unresolved references, and other inconsistencies in the parsed model.

There is an important distinction here.

validateArchiModel validates the structural integrity of the Archi model. It does not determine whether the architecture itself is good or whether a modeling decision complies with a particular governance rule.

Those kinds of rules can be built on top of the ArchiModel.

Some Archi-specific details

The value of a semantic core becomes clearer once you move beyond basic elements and relationships.

archi-semantic-core also understands native Archi information such as:

• AND and OR Junctions
• connection bendpoints
• nested diagram objects
• visual styling
• properties
• Specializations and Profiles
• relationship-specific attributes
• Label Expressions

For example, Archi can use an expression such as:

${name}
${property:Owner}

to dynamically generate the label displayed on an object.

The library can resolve these expressions as well:

import { resolveLabelExpression } from '@cda/archi-semantic-core';

const label = resolveLabelExpression(model, node);

This is particularly useful for consumers that need to reproduce information as Archi would display it.

A complete example

Putting the pieces together, we can create a small Archi model inspector:

import { readFileSync } from 'node:fs';

import {
  extractArchiModelXml,
  parseArchiModel,
  validateArchiModel
} from '@cda/archi-semantic-core';

const bytes = readFileSync('MyModel.archimate');

const xml = extractArchiModelXml(bytes);
const model = parseArchiModel(xml);

console.log(`Model: ${model.name ?? 'Unnamed'}`);
console.log(`Elements: ${model.elements.length}`);
console.log(`Relationships: ${model.relationships.length}`);
console.log(`Views: ${model.views.length}`);

console.log('\nElements');

for (const element of model.elements) {
  console.log(`- ${element.name} [${element.type}]`);
}

const validation = validateArchiModel(model);

console.log(
  validation.valid
    ? '\nModel structure is valid'
    : `\nValidation errors: ${validation.errors.length}`
);

In a few lines of TypeScript, we can open a .archimate file, interpret its model, inspect its contents, and validate its structural integrity.

From there, we can build reports, converters, visualizers, modeling rules, or other tools without implementing Archi's native file semantics again.

One important distinction: .archimate is not Open Exchange

archi-semantic-core works specifically with Archi's native file format.

This should not be confused with the ArchiMate Model Exchange File Format defined by The Open Group.

They solve different problems.

.archimate is the format Archi uses to persist its own representation of models and views.

The Model Exchange File Format is designed for interoperability between ArchiMate tools.

Understanding Archi's native format and converting that information to an exchange format are therefore separate responsibilities.

archi-semantic-core focuses on the first one:

understanding Archi.

---

archi-semantic-core is open source, written in TypeScript, and distributed under the MIT license.

npm install @cda/archi-semantic-core

Repository:

github.com/Continuous-DrivenArchitecture/archi-semantic-core

The README contains the complete API reference and details about the native Archi features currently supported.