Interface control documents (ICD) and data dictionaries are two parts of a mature MBD infrastructure. The question I often hear is “what is the boundary between the two artifacts”? First a high-level refresher:
- The Data Dictionary: an artifact used to share a set of common data definitions external to the model and codebase.
- Objective: provide common and consistent data definition between developers
- The ICD: an artifact used to share interface information between components external to the model and codebase; often derived from or part of the requirements document set.
- Objective: provide a common interface definition to simplify the integration of components when multiple people are working on a project.
An example of an ICD spec is
| function name | myIncredibleFunction |
| function prototype | (double mintGum, single *thought, something *else) |
| Call rate | event-driven |
| Multi-thread interruptible | yes |
| Variable | Type | Dimension | passby |
| mintGum | double | 1 | value |
| thought | single | 4 | reference |
| something | structure | 10 | reference |
And here is where the boundary question comes up. In specifying the data type and dimension in the ICD I am duplicating information that exists in the data dictionary; violating the single source of truth objective.
So what is the flow of information here? I would suggest something like this…
- The ICD document is created as part of the initial requirement specifications
- The data interface request is used to inform the initial creation of data in the data dictionary
- Once created the data is owned by the data dictionary
Infrastructure: making your artifacts work for you
Data dictionaries serve an obvious purpose, they are a repository for your data. On the other hand, interface control documents can seem like a burdensome overhead; which it will be without proper supporting infrastructure. If you remember the objective of the ICD, to simplify integration, then the need for tool support becomes obvious. When a developer checks in a new component it should be
- Checked against its own ICD
- Checked against the ICD for functions it calls and is called by
- Its ICD should be checked against the data dictionary to validate the interface definition
With those three checks in place, early detection of invalid interfaces will be detected and integration issues can easily be avoided.
ICDs and the MATLAB / Simulink environment
Recently MathWorks released the System Composer tool. While I have not had a chance to try it out yet it offers some of the functionality desired above. I would be interested to learn of anyone’s experience with the tool