Three layers that deserve their own rules
The repository owns business facts: applications, APIs, events, services, integrations, owners, lifecycle and source links. An ArchiMate projection expresses selected facts as model elements and relationships. An exchange document serialises that projection for another tool. These layers are related but should not be treated as identical.
An API can play different modelling roles
An API catalogue record might represent an exposed application interface, while the behaviour offered through that interface is an application service. The provider is an application or component. Conflating interface, service and provider makes it difficult to express assignment, realisation and serving relationships accurately.
Avoid the generic-association shortcut
Using an association whenever an explicit relationship is inconvenient may produce diagrams that render successfully yet lose meaning. Each mapping should specify source and target types, direction, permitted semantics and any intermediate element required for a valid ArchiMate expression.
Round-trip requires more than export success
An XML document being accepted by a modelling tool is necessary, not sufficient. The exported structure must preserve canonical identities and stable relationships. If importing a model back into the repository is contemplated, reconciliation rules must guard against spurious additions or unintended changes.
Practical lesson
Treat metamodel projection as a deliberate product feature, not a cosmetic diagram generator. This gives architects both a usable repository and standards-aligned visualisations without making every catalogue field fit an artificial modelling convention.
This article explains design principles and lessons from developing architecture tooling. Examples are illustrative. A described design approach does not, by itself, indicate that a feature is enabled or generally available in a deployed product.