How to map from the CALM standard to Ardoq Solutions

Software architecture descriptions have historically been produced as documents and diagrams. They are authored once, reviewed, and then drift away from the systems they describe. The Architecture as Code movement addresses this by expressing software architecture in a machine-readable form that can be versioned, generated, and validated in the same pipelines that build and deploy the software.

CALM, the Common Architecture Language Model, is an open standard for doing this, developed under the FINOS Architecture as Code project. CALM defines a JSON Schema for describing an architecture as a set of nodes, the relationships between them, the interfaces they expose, the flows that traverse them, and the controls they must satisfy. Because the description is a schema-validated document, an architecture can be generated from a pattern, checked against that pattern automatically, and rejected at build time if it diverges.

CALM has been adopted primarily within engineering and solution delivery, particularly in financial services. Whilst Ardoq can also be used in this way, it typically operates with a higher-level focus. It holds the enterprise-wide model that connects applications, technology, data, capabilities, processes, people, and change initiatives, and it is used to answer a range of portfolio, governance, and strategy level questions. The two models are complementary: CALM describes a solution precisely, Ardoq describes the landscape those solutions sit within.

Increasingly, organizations running both want to understand how they can connect these 2 models to help provide deployment-level detail to their enterprise context and help provide additional context and assurance to deployment teams.

This article describes Ardoq's recommended approach to mapping the CALM core concepts onto Ardoq concepts. It covers:

Note: CALM is an evolving standard and this article reflects current best practice against the current CALM release and current Ardoq platform capability. Both will change. Where you need a mapping that is not covered here it is recommended you consult with Ardoq Professional Services or an Ardoq Partner.

Before mapping individual concepts it is worth being explicit about where the two models differ, because this shapes the guidance that follows.

CALM is deployment-precise. A CALM node carries a host, a port, a container image, and the identity it runs as. It describes a single architecture, usually a single solution, in enough detail that a machine can verify it.

Ardoq is enterprise-broad. The Ardoq model deliberately abstracts away runtime detail so that thousands of applications can be compared, rationalized, and traced to business outcomes. The same abstraction that makes Ardoq useful across an enterprise makes it potentially less suitable for deployment-level detail, for example, a port number for every deployed service instance.

The consequence is that the mapping is not always symmetrical. Moving from CALM to Ardoq often involves losing detail deliberately. Moving from the Ardoq model to CALM involves adding detail that Ardoq may not hold. Neither is a defect. They are different tools answering different questions.

The recommended high-level mapping is summarized below and each mapping is described in turn in the sections that follow.

Table 1. Summary mapping between CALM concepts and Ardoq concepts

*depending on your needs you may also choose to model a CALM relationship as a component in its own right, but conceptually the CALM relationship is most directly aligned to an Ardoq Reference.

A CALM node is the primary building block of an architecture, described in the standard as the boxes that represent people, systems, services, databases, or networks. Every node carries a mandatory unique-id, a node-type, a name, and a description. See Nodes in CALM.

Ardoq's equivalent building block is the Component. Where CALM holds the kind of thing as a node-type property on an otherwise generic node, Ardoq holds it in the component type itself, defined in the metamodel. Mapping a CALM node into Ardoq is therefore primarily a decision about which component type to create it as.

The recommended mapping for the CALM node types is shown below.

Table 2. Recommended mapping between CALM node types and Ardoq Component Types

Key points:

CALM relationships are the arrows. They connect two or more nodes and carry a relationship-type of interacts, connects, deployed-in, or composed-of, optionally with a protocol and a set of controls. See Relationships in CALM.

Ardoq's equivalent is the Reference. Ardoq reference types are named semantically rather than structurally, so the mapping is a matter of choosing the reference type that carries the same meaning.

Table 3. Recommended mapping between CALM relationship types and Ardoq reference types

*The composed-of relationship is worth calling out. In CALM it is a relationship like any other. In Ardoq, parent and child structure is a first-class part of the component hierarchy rather than an ordinary reference. Modelling CALM's composed-of as Ardoq hierarchy, for example an Application that is parent of its Application Modules, gives you the grouping, filtering, and roll-up behavior that Ardoq views may depend on. Representing it as a flat reference will work, but that behavior is lost.

The CALM protocol property maps naturally onto a field on the Ardoq reference. Where you are using the Application Integration Management (AIM) Solution this aligns with how integrations are already described.

CALM interfaces define the points at which a node exposes its functionality: host and port, hostname, path, URL, OAuth2 audience, rate limit, container image, or port alone. See Interfaces in CALM.

Ardoq provides an Interface component type, contained within the Application Integration Management Solution. An Interface is a child of an Application, Application Module, or Data Store. Applications, Application Modules, and Data Store are integrated via a 'Connects To' reference to the relevant Interface. An Interface may supply one or more Data Entities.

This is the most direct of the mappings and one of the more useful. A CALM interface becomes an Ardoq Interface component parented under the component representing its node. The CALM interface type maps to a field on the Interface component, and the type-specific properties such as host, port, path, and URL can be captured via additional fields.

The value here is not the technical detail itself but what it enables. Interfaces sourced from validated CALM documents give an accurate and current picture of how applications actually connect. That is the foundation for integration analysis, for understanding the blast radius of a change, and for data lineage.

Note: Ardoq recommends that Applications and related components integrate through connection to defined Interfaces. However, CALM does not always require an interface to be defined in order to define a relationship, and the calling side of a connection is often left implicit. A modeling decision can be taken here as to whether to align with the Ardoq model or to allow the connection as a reference between the two components instead. More information in Ardoq’s recommendation can be found in the Application Integration Management Solution.

A CALM flow describes a business process as it moves through the technical architecture. It is an ordered sequence of transitions, each referencing an existing relationship by unique-id and carrying a sequence-number, a description, and a direction. Flows exist to connect business intent to the components that implement it. See Flows in CALM.

Ardoq expresses the same intent through the Process component type and its children, Process Activities. A Process may be parent of Process Activities, is supported by Applications, accesses Data Entities, and realizes Business Capabilities and Value Stream Stages.

The recommended mapping is:

*Process Activity level linkage to applications can also be preserved if required.

The step from CALM flows to Ardoq processes is where more enterprise value is unlocked, because it is the point at which technical detail meets the business model. Once a flow is represented as a Process in Ardoq it can be attached to the Business Capabilities it realizes and the Value Streams it serves. These are connections CALM has no way to express, and they are the basis for questions such as which capabilities are exposed if a given service becomes unavailable.

Where broader processes are being modelled in detail, the ShiftX process mapping add-on may be a better home for the sequence itself, with the Ardoq Process retained as the point of connection to the wider model. Flows can be simply imported into ShiftX via the AI Process Builder. An example of an AI imported flow can be seen in Example 7.

CALM patterns are reusable architecture templates expressed as JSON Schema. They serve two purposes: generating a scaffold for a new architecture, and validating that an existing architecture conforms to a required structure. Constraints such as const, prefixItems, minItems and maxItems, and oneOf express which nodes must exist, how they must connect, and where implementers are free to choose. See Patterns in CALM.

Ardoq provides a Pattern component type as part of the Architecture Records (REC) Solution. A Pattern sits within a Category, is realized by Applications and Technology Products, and may refer to other Patterns. Patterns are typically linked to their full documentation using the Document URL field. This Document URL field can be used to store the link to the CALM pattern schema document. See Using Reference Architectures in Ardoq.

Conceptually these are the same idea: a reusable blueprint that constrains design. A CALM pattern maps cleanly onto an Ardoq Pattern component, with the pattern's $id or repository URL held in the Document URL field so that architects can reach the machine-readable definition from the portfolio view.

The difference lies in how conformance is established. CALM validates conformance mechanically: the validate command either passes or fails. At present, Ardoq records conformance as a modelled relationship. The 'Is Realized By' reference from Pattern to Application states that an application implements the pattern, and comparing the Technology Products included in the pattern against those actually deployed reveals divergence. Automated conformance within Ardoq is currently under active development and can be approximated using the AI Assistant with direction to the relevant Pattern component (and accompanying CALM pattern schema) and Application architecture.

Used together these are stronger than either alone. CALM tells you whether a design conforms today. Ardoq tells you how many applications are subject to a pattern, who owns it, what technology it commits you to, and what the portfolio-wide cost of divergence is. Where a CALM pattern is enforced in a delivery pipeline, recording the corresponding Ardoq Pattern gives architecture governance visibility of that enforcement.

There is a natural extension here. Where a CALM node carries a details.required-pattern, that is a direct statement that a given component must conform to a given pattern, and it can be represented as a reference from the Ardoq component to the relevant Pattern.

A CALM control expresses a domain requirement, such as a security control permitting only approved connection protocols or a resiliency control requiring a defined recovery time, and attaches it to a node, a relationship, a flow, or the architecture as a whole. Each control pairs an abstract requirement, referenced by requirement-url as a JSON Schema, with a config that supplies the concrete values fulfilling it. Because that configuration is machine-readable, CALM can validate mechanically whether an architecture conforms.

Ardoq represents controls as a first-class Control component type, introduced by the Application Risk Management Solution. A Control sits within a Control Category, mitigates one or more Risks, deploys to one or more Applications with a deployment date, and is realized by the applications, technologies, or policies that implement it. Requirements drawn from adopted frameworks and corporate policies are modelled as Requirement components beneath an Information Artifact representing the framework or policy document, and are realized by the Controls that satisfy them.

The two models share a useful piece of structure. CALM already separates the abstract requirement from the concrete configuration that fulfils it, and Ardoq makes the same separation between a Requirement, owned by a framework or policy, and a Control, owned by a control owner. That symmetry means that identical requirement-url values appearing across many CALM architectures collapse to a single Requirement component in Ardoq.

Table 4. Recommended mapping between CALM controls and Ardoq controls

CALM has no concept of risk. There is no equivalent of Ardoq’s Mitigates reference, no Likelihood Effect or Impact Effect on a control, and no exposure calculation. Everything quantitative in the Ardoq model, including the red and green thresholds held on the Application, has no CALM source and must be supplied by risk and control owners. A CALM import can populate the control library and record which controls are deployed where. It cannot populate the risk assessment. See Application Risk Management: Purpose, Scope, and Rationale for how those values are established.

Ardoq records that a control was deployed to an application on a given date. CALM can prove that the deployed configuration meets the requirement. This is the most valuable thing CALM has to contribute to the enterprise model, because it turns an asserted deployment into an evidenced one. Where a CALM validation run fails, that is a signal the corresponding Deploys To reference in Ardoq is overstating the position.

The differences described here create a level of ambiguity between the precise convergence of Controls between CALM and Ardoq so a review of the intended model should be undertaken prior to implementation.

Where the Application Risk Solution is not in use, the alternative is to represent the requirement as a Policy or Standard within the Architecture Records Solution and to record fulfilment through a Compliance Assessment. This is a reasonable option where there is no risk register for controls to connect to. See How to represent Policies, Principles, Standards, and Frameworks in Ardoq.

Several CALM concepts have no single Ardoq counterpart. The recommended treatment is described below.

Metadata and Decorators attach supplementary information to architecture elements. These map to Ardoq fields on the relevant component or reference, or to tags where the information is used for filtering rather than analysis.

Standards extend CALM elements with organizational requirements and are handled in the same way as Controls.

Timelines track how an architecture evolves through significant moments. Ardoq addresses this need through Future States and Transition Architectures. See Modeling Future States and Transition Architectures in Ardoq.

Widgets generate Markdown documentation from a CALM model. The equivalent need in Ardoq is met by Viewpoints, reports, and presentations, and no data mapping is required.

Decide the direction of travel. Importing CALM documents into Ardoq to enrich the enterprise model is a different exercise from generating CALM scaffolds from Ardoq. The first requires rules for abstraction. The second requires that Ardoq holds enough deployment detail to be useful, which for most customers it deliberately does not.

Do not import everything. A CALM repository across a large delivery organization will contain far more nodes than the enterprise model should hold. Agree in advance which node types are of enterprise interest, typically systems, services, databases, and their interfaces, and leave the remainder in the architecture documents, reachable through detailed-architecture links.

Master the data where it belongs. Where CALM documents are the authoritative source for interfaces and connections, consider holding the resulting components in Managed Workspaces so that the data stays synchronized and is not edited in two places. See Managed Workspaces and Data Sync Strategy on Import.

Preserve identifiers. Bring the CALM unique-id across for every node, relationship, interface, and flow that you import, and hold it in a dedicated field.

Expect the mapping to be opinionated. There is a high degree of variability in how organizations use both CALM and Ardoq. The mappings above cover the clearest and most common cases. Where you need to go further it is recommended you consult with Ardoq Professional Services or an Ardoq Partner.

The following examples are drawn from the Trading System example provided in the CALM GitHub repository.

CALM is provided as JSON which can be imported into Ardoq using the JSON Importer or scheduled for import using the Ardoq Import Builder. Depending on the detail required for import some JSON transformation may be required in order to access the deeply nested JSON structures. This should be undertaken prior to import. A simple way of achieving this is to point Claude (or equivalent) at this article and the relevant CALM JSON file.