This document serves as a guide for creating interface design and definition documents (IDDs), outlining key sections such as the design structure matrix, transaction processing, message structure, and security considerations. It emphasizes the importance of including specific details like assumptions, limitations, message types, and field definitions within the IDD to ensure clarity and effectiveness. Additionally, it highlights the benefits of a design structure matrix (DSM) in system design and integration projects.

1. © 2024. All rights reserved. IQVIA®
is a registered trademark of IQVIA Inc. in the United States, the European Union, and various other countries.
Interface Design and
Definition Document
Template – A Short Guide
for the Best Results
Interface Design and Definition Document Template — A Short
Guide for the Best Results (softwaredominos.com)

2. 2
• Table of Contents
• 1. Overview
• 2. Design Structure Matrix (DSM)
• 3. Interface Definition Document (IDD) Template
• 4. Further Reading

3. 3
• This presentation will discuss the Interface Design/Definition Document (or IDD) and provide a basic structure that can
be used as a template.
• The sections below represent the main topics an Interface Definition Document (IDD) must address.
• However, this list is incomplete; an overview section, a reference guide, and a terms and definitions section must also
be included. We have covered each of these items in the Solution Design Document article.
• In summary, an IDD must cover:
• Interface and system overview
• Constraints and limitations
• Transaction processing and design patterns
• The transaction flow
• The message structure and protocols
• The message fields
• Security
• Communications and data transfer
- Before we explore the template, we will discuss the Design Structure Matrix (DSM), an essential part of any
solution design document.
1.1 Overview
1. Overview

4. 4
• A Design Structure Matrix (DSM), also referred to as
a dependency structure matrix, incidence matrix, N2
matrix, interaction matrix, or dependency map, is a simple,
square representation of a system design highlighting the
interfaces, dependencies, or links between the system
subcomponents.
• In the example above, we see four components of the system
(including the environment it operates in and the end user)
and different types of interfaces between them.
• A sensor reads information (such as temperature or pressure)
between the environment and Module B and stores it
internally in a database via a database abstraction layer like
JDBC or Hibernate.
• The operator interacts with the system via a Graphical
User Interface (GUI) or a command-line interface (CLI). An
operator can also upload data files via a File Interface.
• Modules A and B share data through an internal API.
2.1 Overview
2. Design Structure Matrix (DSM)
An example of a Design Structure Matrix (DSM) includes an operator, a system of two components and an environment in which it operates.

5. 5
• A DSM allows you to do the following:
• Identify quickly opportunities to improve the system design,
such as combining similar modules or reducing the overall
number of interfaces.
• Understand the impact of any change on the system, like adding
a new feature or component.
• Ensure that all players’ interfaces have been accounted for.
• A DSM can also be created on different system decomposition
levels. A high-level DSM would show the connections between
major systems, while a low-level DSM would represent a more
granular view. However, its size must remain within the cognitive
capacity of its users to remain usable.
• A high-level Design Structure Matrix naturally belongs in the
High-Level Design Document, whereas a low-level DSM would
best be included in a Low-Level Solution Design.
• While a DSM is crucial in systems integration projects, it is highly
recommended in large software development and
implementation projects.
2.1 Benefits of Having a DSM
2. Design Structure Matrix (DSM)
An example of a Design Structure Matrix (DSM) includes an operator, a system of two components and an environment in which it operates.

6. 6
• 3.1 Interface Overview
• The interface overview section presents generic
details like terms and definitions, change history,
current version number, support contact information,
intended audience, and external references.
• 3.2 Assumptions and Limitations
• Any assumptions, limitations, or constraints on the
systems connected through the interface or the
interface itself must be explicitly mentioned. Example
are:
• Hardware or software environment — if specific
hardware or software is required to process the
message or its contents.
• End-user environment — for example, which browser
to use for web pages.
The Interface Design/Definition Document (IDD) template should cover the following aspects.
3. Interface Definition Document (IDD) Template

7. 7
3.1 Interface Overview
• The interface overview section presents generic
details like terms and definitions, change history,
current version number, support contact information,
intended audience, and external references.
3.2 Assumptions and Limitations
• Any assumptions, limitations, or constraints on the
systems connected through the interface or the
interface itself must be explicitly mentioned. Example
are:
• Hardware or software environment — if specific
hardware or software is required to process the
message or its contents.
• End-user environment — for example, which browser
to use for web pages.
The Interface Design/Definition Document (IDD) template should cover the following aspects.
3.1 Interface Overview and 3.2 Assumptions and Limitations

8. 8
• The following design patterns are typically applied when conceptualizing interface operations.
• Producer/Consumer—This design pattern establishes a preferential direction for information exchange. A
producer creates and shares information with a consumer. The data flow can go in either direction, depending
on whether this sharing occurs via a push or pull mechanism.
• Switching — A switching system treats all interface connections on a somewhat equal footing. A message arrives
from a source and is routed to its destination according to specific rules. The routing is usually determined based
on the origin and the message’s content.
• Command and control — Under this paradigm, a command is issued from the control system, and a response is
typically expected from the executing system. The message direction can be both ways; commands and
responses flow from the control system to the executor, while status messages can be pushed from the executor.
• Message flow could be either synchronous or asynchronous. In synchronous operation modes, the sender is
blocked until a response is received. In asynchronous modes, the sender continues to perform its task while
waiting for a response.
• Connection initiation, handshakes, keep-alive, and security key exchanges must be described.
The IDD should specify the adopted design pattern and operation mode, which we now
describe.
3.3 Transaction Processing, Flow, and Design Patterns

9. 9
• A typical message shared across a system interface is made up of the following components:
• Header
• The message header contains information about the message itself, such as its type, origin, creation time, expiry
timeframe, authentication token, credential information, and routing information. It might also include
metadata about the message content, such as its length, structure, or format. The information in the message
header is crucial for the correct routing, interpretation, and processing of the message.
• Body
• The message body contains the payload, typically containing user and application data of some business value.
This data is relevant only to the destined application or user and carries essential information required to
complete a service or support system functionality. The message body size can be tiny or even zero (for example,
for ping or keep-alive messages). Its most common format is JSON or XML, but it could also be fixed-length, field-
delimited, Tag-Length-Value strings, or bitmap structured.
• Footer
• The message footer is an optional field. It might contain special characters to delimit a message or data
summary (such as the number of records or a sum of amounts) or checksums for integrity checks.
The IDD must contain a detailed definition of the message structure used across the
interface.
3.4 Message Structure and Protocols

10. 10
• Message types and functionality
• What different message types are supported by the interface, and (briefly) what functionalities do they provide?
Typically, a message field indicates the message type and allows the application to distinguish between different
services at both interface ends.
• Dependencies
• Any dependencies between the messages (sequential, temporal, functional)
• How to recover from errors, exceptions, or mistakes
• An interface implementation must provide methods for recovering from errors caused by incorrect usage, invalid
data, or server-side problems.
• Field conditions:
• A message’s fields can be mandatory, optional, or conditional depending on the message type or the presence
and value of other fields. This information is generally provided in a table of allowed fields per message type,
with the conditions specified on the field level.
Include the below topics in your IDD on message definition
3.5 Message Definitions

11. 11
• Field definition — A field can be uniquely defined by the
following attributes:
• Unique identifier
• Name
• Short description
• Purpose
• Field formats — Familiar field formats include
• Alpha-numeric
• Numeric
• Strings
• Dates and timestamps
• A specific pattern (usually specified with regular
expressions)
• Large character or binary objects (CLOB, BLOB)
Include the following topics when describing your interface’s data fields (sometimes called
data elements).
3.6 Data Field Definitions
• Field Validators — For example:
• Number ranges
• Allowed characters
• List of values (LOV)
• Date ranges or conditions
• Whether the field can be null or must have a
default value
• Field presence — This attribute is commonly defined on
the message level. Fields can be:
• Mandatory, i.e. must be present for the specific
message
• Optional, i.e. at the sender’s discretion
• Conditional on the presence of other fields or
their values

12. 12
• Encryption:
• Encryption can be applied on the message or field level where individual fields contain sensitive information.
Encryption can be symmetric (sender and receiver use the same key) or asymmetric (using RSA, where only the
public key is used for encryption).
• Signatures:
• Signatures can be appended to messages to verify the sender’s authenticity and data integrity. Signatures are
created by hashing the message (or a part of it) and encrypting it with a secret key when using asymmetric
encryption. Owners of the public key can authenticate the sender by decrypting the signature and comparing
the hash obtained with the one recalculated on the received message contents.
• Passwords and One-Time Passwords (OTP):
• Passwords and One-Time Passwords (OTPs) authenticate the user. OTPs provide an additional layer of security by
constraining password usage to a limited period or usage count. OTPs are randomly generated for every new
session or transaction.
• Tokens:
• Tokens can be used to authenticate a session or a user instead of usernames and passwords. Tokens typically
have an expiry date, after which they must be regenerated.
Messages and message contents must be secure, and this can be achieved through the
following security mechanisms:
3.7 Security

13. 13
In most applications, communication and data transfer are supported by TCP/IP interfaces and do not require
special attention. However, there might be instances where specialized hardware or legacy software is involved,
and specific constraints on the message lengths, encoding, format, and processing might apply.
3.8 Communications and Data Transfer

14. 14
• Systems Engineering Handbook from NASA
4. Further Reading