Model-Based Interface Control Documents: Generating ICDs from SysML v2 Instead of Maintaining Them

Ask any integration lead where the schedule went and the answer is usually an interface. Not a big one. A CAN message whose scaling factor changed in one team's spreadsheet and not the other's. A connector pinout that was correct in revision C of the ICD and wrong in the harness drawing that was cut from revision B. The interface control document was supposed to prevent exactly this, and it did, right up until it became a 200-page Word file that three organizations edit on different cadences.

Model-based interface control documents are the attempt to fix that by demoting the ICD from a source to a report. The interface itself lives in the system model. The document is generated whenever somebody needs to read one. SysML v1 tools have offered this for years, and SysML v2 makes the underlying structure considerably cleaner. It is worth understanding what the pattern actually buys you, because the payoff is real but narrower than the pitch.

What an ICD is really for

Strip away the template and an ICD does three jobs. It defines the boundary between two things owned by different people. It states, precisely, what crosses that boundary: signals, fluids, loads, data, power, with units, ranges, rates, and protocols. And it records agreement, meaning both sides signed off and any change goes through a control process.

The document format is good at the third job and bad at the first two. Boundaries and flows are structural facts that already exist, or should exist, in the architecture model. Copying them into prose creates a second authoritative source, and two sources drift. The No Magic and Dassault approach to model-based ICDs, which generates black-box and white-box ICD tables straight from block definition and internal block diagrams, is a direct response to that drift: if the table is a query over the model, it can't disagree with the model.

Note what the pattern doesn't change. Somebody still has to review and approve the interface. Model-based ICDs move the artifact, not the governance.

How SysML v2 structures an interface

SysML v2 gives interfaces a layered structure that maps unusually well onto what an ICD needs to say. Sensmetry's Advent of SysML v2 series lays out the pieces, and the refinement pattern it describes is the one to adopt.

• Port definitions declare an interaction point and the directed features exposed through it. A port def lists in, out, and inout items. Ports themselves are never directed; the items are.
• Conjugation (the ~ operator) flips a port definition inside out, so the other side of the interface uses the same definition with directions reversed. One definition, two compatible ends, no hand-mirroring.
• Item definitions describe what actually crosses: a command, a telemetry frame, a coolant flow. Items carry attributes, which is where units, ranges, and encodings go.
• Interface definitions are connections whose ends are ports. Inside an interface def you declare flow usages from an output item on one end to an input item on the other.
• Connection definitions between parts can contain an interface usage, so whenever two parts are connected with that connection type, their ports are automatically joined and the flows are set up with them.

The practical consequence is that a single interface definition, written once, is instantiated everywhere that connection appears. Change the item's attribute range in one place and every ICD view that references it updates. That is the whole argument for the model-based approach in one sentence.

Generating the document

With that structure in place, the ICD becomes a view. SysML v2 has first-class view and viewpoint elements, so the query that says "all interfaces crossing the boundary of subsystem X, with every item, direction, and attribute" is itself a model element with a name and a version. Rendering it as a table, a PDF, or a web page is a tooling job, not a modeling job.

Tools handle the rendering differently. Dassault's CATIA Magic (formerly Cameo) generates black-box and white-box ICD tables from SysML v1 diagrams and can export them to documents. Eclipse Capella, which is not SysML but shares the same philosophy, derives interface descriptions from its physical and logical architecture exchanges. SysML v2-native tools such as Sensmetry's Syside and Dalus work directly from the textual notation, where port, interface, and flow definitions are plain declarations that a view can query. Which is right depends on where the rest of your model lives, but the pipeline is the same in all cases: model the interface, define the view, render on demand.

A few things make the generated document useful rather than merely automated:

• Put units on attributes. SysML v2 ships quantity and unit libraries. An item attribute typed as a MassValue in kilograms is unambiguous. An attribute called mass with a comment saying "kg" is a spreadsheet in disguise.
• Model both ends. A one-sided interface is just an export. The value comes from the conjugated port on the other side, so a mismatch between what one team emits and what the other expects shows up as a model error, not an integration surprise.
• Version the view, not the document. The rendered PDF is disposable. What you baseline is the model commit plus the view definition, which is what you'd diff when someone asks what changed between ICD revisions.

Where it pays off first

The pattern is worth the setup cost in a few recognizable situations.

Systems of systems with many organizational boundaries, where each boundary would otherwise carry its own document and its own change board. Programs with high interface churn early in the lifecycle, where a weekly regenerated ICD beats a quarterly negotiated one. Product lines, where the same interface definition is reused across variants and the last thing you want is a hand-edited ICD per variant. And any program pursuing a modular open systems approach, where key interfaces are contractual and conformance has to be demonstrable; the DoD's MOSA guidance explicitly ties open interfaces to MBSE and wants architecture models to flow into downstream engineering rather than sit beside it.

What it won't solve

Be honest about the trade-offs before selling this internally.

• Suppliers still want a document. Most of them don't run your modeling tool and won't. You will generate a PDF for them, and their redlines come back as prose. Round-tripping supplier feedback into the model is manual work and will stay that way for a while.
• Protocol detail doesn't fit neatly. SysML v2 is comfortable describing that a frame flows from A to B with these fields. It is less comfortable with bit-level packing, timing diagrams, or state-dependent message sets. Teams end up linking to an external protocol spec or embedding it as an attribute blob, which is fine, but the ICD is then only partly model-based.
• Interface governance is a process problem. If your change board meets monthly and your model changes daily, generating a fresh ICD each morning doesn't help anyone; it just makes the drift visible. You need a baseline discipline for the model that matches the ICD approval cadence.
• Migration is not free. Converting an existing document ICD into port, item, and interface definitions is a modeling project. If the legacy ICD is inconsistent (and the ones that hurt usually are), you'll discover every inconsistency during migration and have to adjudicate each one.
• Tool maturity varies. View rendering, document export, and diff-across-baselines are uneven across SysML v2 tools right now. Check that your chosen tool can produce the table your stakeholders actually read, not just that it parses the interface syntax.

Bottom line

The interface control document has always been a report about structure that should have lived somewhere more reliable than a Word file. SysML v2 gives that structure a clean home: ports with directed items, conjugated ends, interface definitions that carry flows, and connection definitions that stamp all of it out wherever parts meet. Once that is modeled, the ICD is a view you generate, not a file you maintain.

Start with one high-churn, high-stakes boundary. Model both sides, put real units on the items, define the view, and ship the generated table to the people who currently read the document. If they stop asking which revision is current, you've proved the case. Then worry about the supplier round-trip and the protocol detail, because those problems are still yours, model or no model.