Skip to content

Getting Started

This guide walks you through installing etcion, creating your first model, validating it, and exporting to XML.

Installation

Install the core library:

pip install etcion

For XML serialization (requires lxml):

pip install etcion[xml]

etcion requires Python 3.12 or later.

Your First Model

Create a simple model with a business actor, a business service, and a serving relationship:

from etcion import BusinessActor, BusinessService, Serving, Model

# Create elements
customer = BusinessActor(name="Customer")
ordering = BusinessService(name="Online Ordering")

# Connect them with a relationship
serves = Serving(name="serves", source=ordering, target=customer)

# Add everything to a model
model = Model(concepts=[customer, ordering, serves])

print(f"Elements: {len(model.elements)}")
print(f"Relationships: {len(model.relationships)}")

Every element gets a unique UUID on creation. You can also supply your own:

actor = BusinessActor(id="my-custom-id", name="Customer")

Validating a Model

Model.validate() checks every relationship against the ArchiMate 3.2 permission table:

errors = model.validate()
if errors:
    for err in errors:
        print(err)
else:
    print("Model is valid.")

Use strict=True to raise on the first error instead of collecting all errors:

model.validate(strict=True)  # raises ValidationError on first violation

You can also check individual relationships without a model:

from etcion import is_permitted, Serving, ApplicationService, BusinessService

is_permitted(Serving, ApplicationService, BusinessService)  # True

Exporting to XML

Export to the Open Group ArchiMate Exchange Format:

from etcion.serialization.xml import write_model

write_model(model, "my_model.xml", model_name="My Architecture")

The output is compatible with Archi and other Exchange Format tools.

Exporting to JSON

For lightweight integrations, use JSON:

import json
from etcion.serialization.json import model_to_dict

data = model_to_dict(model)
print(json.dumps(data, indent=2))

Next Steps