X as Code Is Not a File Conversion: What Must Survive When Engineering Leaves Its Tool?

“We should move the architecture to Git” sounds like a file-conversion project.

Export the model from Rhapsody. Take the requirements from DOORS or Codebeamer. Collect the Word documents. Convert the result to YAML, put it under version control, and call it Architecture as Code.

The difficulty appears to be format diversity.

It is not.

The real difficulty is deciding what the new representation is supposed to preserve.

An established engineering project does not live in one file, even when one tool is officially called the source of truth. Its component structure may be in a modeling tool. Requirements and their status may be in a requirements database. Interfaces may be exchanged as ARXML. Rationale may be in Word documents. Exceptions may exist only in tool settings, review records or what the team has learned not to change.

Converting those files is possible. Establishing that the same engineering system emerged on the other side is a different problem.

X as Code is not a change of storage format. It is a reconstruction of the boundary around engineering truth.

That boundary determines which information becomes authoritative, which is derived, which stays outside the model and which is knowingly left behind.

An Exchange File Is Not the Whole Engineering Model

ARXML is an obvious candidate for an AUTOSAR project. It is standardized, machine-readable and already accepted by the engineering toolchain. Why not make it the universal input to the new model?

Because “standard exchange format” and “complete representation of the engineering system” are different claims.

AUTOSAR describes .arxml as the formal exchange format for information produced and consumed in the AUTOSAR methodology. An AUTOSAR XML description is a serialization of an AUTOSAR model: it can carry information that is representable in the AUTOSAR metamodel. That is a substantial scope, but it is still a scope. AUTOSAR explicitly does not standardize, for example, the internal functional behavior of an application; its application-interface work standardizes what is exchanged between applications.

More importantly, AUTOSAR itself does not treat every schema-valid ARXML file as sufficient for every exchange. Its concept of a Data Exchange Point defines the relevant or excluded subset of the metamodel, the intended use, constraints, completeness and extension mechanisms for a particular producer and consumer. The rationale for doing so explicitly includes avoiding missing elements, undefined structures, incompatible modeling patterns and loss of information. These requirements are stated in AUTOSAR’s Standardization Template requirements.

The standard therefore points to the deeper rule: a common syntax does not remove the need for an agreed semantic boundary.

The same pattern appears elsewhere. ReqIF is a generic format for exchanging requirements information between organizations and tools. It is not an export of an entire lifecycle-management environment. Codebeamer, for example, documents that teams, reviews, test runs, work logs, commits and several other kinds of project information are outside its ReqIF exchange. Rhapsody supports model exchange through XMI, yet its export UI offers additional data specifically for round-tripping a model back into another Rhapsody project.

These formats are not defective because they have boundaries. A useful exchange format needs a defined purpose. The mistake is assuming that its purpose is identical to preserving everything the source tool knew.

Five Attractive Ways to Avoid the Hard Question

Once a team recognizes that its engineering information is spread across several systems, five strategies look attractive.

1. Use the strongest standard format

For an AUTOSAR architecture, that usually means ARXML. For requirements, it may mean ReqIF. For a UML or SysML model, XMI.

Standards give tools shared vocabulary and are often the correct boundary for a downstream consumer. But choosing one as the new source of truth silently makes everything outside its scope secondary. Presentation, rationale, workflow state, tool-specific extensions and links to other repositories do not become irrelevant merely because the selected format has nowhere to put them.

2. Write a converter for every source

A Rhapsody converter, a DOORS converter, a Codebeamer converter and a Word importer can all feed the new repository.

Some source-specific adaptation is unavoidable. The risk is allowing each adapter to invent its own meaning for component identity, requirements, traces, variants or missing values. The result may be several technically correct parsers producing several subtly different architectures.

The important shared asset is not the set of parsers. It is the semantic contract they all target.

3. Invent a universal engineering format

This promises one representation capable of containing everything.

In practice, it tends toward one of two outcomes. It becomes a lowest common denominator that loses the distinctions that made the source systems useful, or it grows into another large specialized metamodel that now has to reproduce architecture, requirements, process, presentation and every vendor extension.

A universal format does not eliminate modeling decisions. It concentrates them in the design of the new format.

4. Rebuild the model from scratch

This may be the most appealing option:

The old models are inconsistent. We will create a clean Architecture as Code model and get it right from the beginning.

For a genuinely new product, a clean start may be appropriate. Reconstructing an existing product in an empty repository is not a greenfield project, however.

The irregularities of a mature architecture may encode product variants, ownership boundaries, downstream limitations or decisions whose rationale has been forgotten. Similar interface names may be accidental duplication, or they may mark a distinction that matters. A missing value may mean unknown, not applicable, inherited or never modeled. A clean model can collapse all four into one tidy default.

The result may look better than its source: consistent names, a smaller hierarchy, no duplicate elements. That appearance is not evidence of fidelity.

The cleanliness of a reconstructed model may come from removing the inconvenient parts of reality.

Starting from scratch does not remove the conversion rules. It moves them from converter code into the modeler’s judgement, where they are harder to inspect and reproduce.

5. Give everything to an AI agent

The request almost writes itself:

Here is the Rhapsody model, the ARXML export, the requirements database, several Word documents and some spreadsheets. Turn them into a correct Architecture as Code model without losing anything.

An AI agent may be unusually useful here. It can read heterogeneous sources, recognize similar concepts, propose mappings, find contradictions and produce a first version much faster than a person working file by file.

But the agent still has to decide whether two names represent one element, whether a contradiction is an error or a variant, whether an absent property implies a default, and whether unsupported information is metadata or an engineering constraint. Those are not serialization choices. They change the architecture.

The most dangerous result is not an obvious hallucination. It is a coherent model built from reasonable assumptions that were never exposed for review.

An AI can solve the problem it was given perfectly while the problem remains incomplete. The same principle led me to build SWCraft around visible proposals rather than autonomous engineering decisions—a principle I explain in the first article in this series. During a migration it matters even more: the agent is not only proposing the future of the architecture; it is interpreting its past.

A clean-sheet rewrite can make information loss look like simplification. An AI conversion can make hidden assumptions look like completed engineering.

There Is No Semantics-Free Migration

None of the five strategies is inherently wrong. Standards, adapters, new models and AI assistance can all be part of a sound transformation.

What none of them provides is a way to avoid interpretation.

If the mapping rules are not written down, they still exist. They are embedded in a standard’s scope, a converter’s code, a new metamodel, a modeler’s judgement or an agent’s context and inference.

The real design question is therefore not:

Which format can store all our current files?

It is:

Which engineering meaning do we promise to preserve, and what evidence will support that claim?

That question leads to a more honest classification. Every piece of source information needs one of four destinations:

1. Canonical: it becomes part of the new authoritative model.
2. Derived: it is generated reproducibly from canonical information.
3. Referenced: it remains authoritative elsewhere, with an explicit relationship to the new model.
4. Unsupported or discarded: it does not move, and that loss is named rather than hidden.

The fourth category is uncomfortable, which is exactly why it matters. A migration report that says what could not be represented is more trustworthy than a success message that counts the files it managed to write.

Three Claims a Transformation Must Prove

Thinking through this problem in SWCraft separated what initially looked like one import project into three independent questions.

Did the existing architecture survive?

This is the faithful import question.

Elements need stable identities. References must still point to the same concepts. Type and interface compatibility must preserve their meaning rather than merely their spelling. Unsupported constructs must be visible. A syntactically valid destination model is not sufficient if it quietly merges two distinct elements or drops a relationship.

This is the question a clean-sheet reconstruction tends to underestimate.

Can the next participant still use it?

This is the operational compatibility question.

A model may be internally consistent and still fail at the next engineering boundary. An AUTOSAR schema can establish that an ARXML document has an allowed structure. It cannot establish that the specific RTE generator, integration workflow or organizational process has received everything it needs.

The strongest acceptance evidence comes from the real consumer. In SWCraft’s roadmap, an “RTE-ready” claim therefore requires an actual RTE generator run; XSD validation alone cannot make that claim. That run has not yet happened, so SWCraft does not currently claim to be RTE-ready.

Did the new representation create new value?

This is the X as Code question.

If the new repository only reproduces the old tool’s files, the team has paid for a migration without necessarily improving the engineering process. The intended value may be reviewable diffs, deterministic checks, reproducible generation, impact analysis, architectural experiments or AI assistance over an inspectable model.

That value must not be purchased by weakening the first two claims. A beautiful Git diff is not a success if it describes a subtly different system or cannot be consumed downstream.

A trustworthy transformation must therefore do three things:

Preserve the existing meaning. Continue the existing engineering flow. Enable a better way of working.

How I Am Approaching This in SWCraft

SWCraft does not try to make YAML a universal engineering format, and it does not treat ARXML as a complete source of engineering truth.

The YAML model is canonical for the architectural concepts SWCraft explicitly owns. ARXML is an important import and export boundary. Diagrams and reports are derived artifacts. Deterministic checks establish properties the model contract knows how to judge. None of those mechanisms claims that every fact in Rhapsody, DOORS, Codebeamer or a Word document has been absorbed into one repository.

The distinction changes how import is designed. A successful parser is only the first layer. The import also needs explicit mappings into the model contract, stable identity, visible handling of unsupported constructs and checks over the resulting relationships. When information cannot be represented, the honest result is a named omission, not an approximation that looks complete.

The current roadmap is split along the same three proof obligations:

• faithful import asks whether an existing AUTOSAR architecture enters SWCraft without a hidden semantic change within the declared scope;
• RTE-ready authoring asks whether a model authored in SWCraft can cross the real downstream integration boundary;
• the architect’s work on the model asks what becomes possible once the representation is explicit: controlled AI editing, diagrams, impact analysis and eventually architectural experiments.

That split is useful because it prevents one vague statement — “SWCraft supports AUTOSAR” — from standing in for three different claims with three different forms of evidence.

AI belongs in this process, but not as the owner of the migration. It can inventory sources, suggest correspondences, construct candidates and expose contradictions. It should also be required to show where each candidate fact came from, which assumptions it made and what it could not map. The accepted model still needs deterministic checks, reviewable changes and an engineer who owns the interpretation.

The goal is not to prevent AI from making inferences. The goal is to prevent an inference from silently becoming engineering history.

What Must Survive?

“Convert everything” is not a useful acceptance criterion. No team can prove it without first defining what everything means across its tools, documents, processes and tacit knowledge.

A better transformation begins with narrower commitments:

• the identities and relationships we promise to preserve;
• the outputs and downstream operations that must remain possible;
• the information that will stay authoritative elsewhere;
• the losses and assumptions that must be visible;
• the new capabilities the code-based representation is intended to create.

Only then do formats, converters and AI agents become implementation choices rather than substitutes for the missing decisions.

The success of an X-as-Code transformation is not measured by how many files were converted. It is measured by whether the promised engineering meaning survived, whether every known loss became visible, and whether every judgement can be traced to someone who had the authority to make it.

Standards and product documentation referenced in this article: AUTOSAR Classic Platform, AUTOSAR application interfaces, AUTOSAR Requirements on Standardization Template, OMG ReqIF 1.2, Codebeamer ReqIF exchange, and IBM Rhapsody XMI export.