1. Requirements

5.2.4.1 The Interface Design Description shall include: (SWE-112)
           a.    Priority assigned to the interface by the interfacing entity(ies).
           b.    Type of interface (e.g., real-time data transfer, storage-and-retrieval of data) to be implemented.
           c.    Specification of individual data elements (e.g., format and data content, including bit-level descriptions of data interface) that the interfacing entity(ies) will
                  provide, store, send, access, and receive.
           d.    Specification of individual data element assemblies (e.g., records, arrays, files, reports) that the interfacing entity(ies) will
                  provide, store, send, access, and receive.
           e.    Specification of communication methods that the interfacing entity(ies) will use for the interface.
           f.     Specification of protocols the interfacing entity(ies) will use for the interface.
           g.    Other specifications, such as physical compatibility of the interfacing entity(ies).
           h.    Traceability from each interfacing entity to the system or CSCI (Computer Software Configuration Item) requirements addressed by the entity's interface design, and traceability from each system or
                  CSCI requirement to the interfacing entities that address it.
           i.      Interface compatibility.
           j.      Safety-related interface specifications and design features.

1.1 Notes

NPR 7150.2, NASA Software Engineering Requirements, does not include any notes for this requirement.

1.2 Applicability Across Classes

This requirement applies to all classes and safety criticalities except:

• Class D and Not Safety Critical.
• Class E and Not Safety Critical.
• Class H.

Classes C through E and Safety Critical are labeled with "P (Center)" and  "SO."  "P (Center)" means that an approved Center-defined process that meets a non-empty subset of the full requirement can be used to achieve this requirement.  "SO" means that the requirement applies only for safety-critical portions of the software.

Class C and Not Safety Critical is labeled with "P (Center)." This means that an approved Center-defined process that meets a non-empty subset of the full requirement can be used to achieve this requirement. 

Class F and Class G are labeled with "X (not OTS)."  This means that this requirement does not apply to off-the-shelf software for these classes.

2. Rationale

The Interface Design Description (IDD) describes the interface characteristics of one or more systems, subsystems, Hardware Configuration Items (HWCIs), Computer Software Configuration Items (CSCIs), manual operations, or other system components. Typical NASA development projects are complex, multi-disciplined activities that consist of systems and systems of systems. These projects usually require integrated product teams working together to achieve the goals and objectives in a timely and cost-efficient manner. The execution of the software development life cycle and its activities by the team requires multiple tasks and work products to be developed and accomplished in parallel. To assure that the assembled systems and integrated systems function as intended, the interfaces for the software work products (components) and systems must be accurately defined, designed, controlled, and communicated.  A high-quality IDD document fulfills these needs for the software development team. 

3. Guidance

The software IDD document may be a stand-alone entity or part of the Software Design Description document (see SWE-111) or part of an electronic data system. Center policies and procedures are expected to be followed when determining which documentation approach is suitable for a particular project. It is important that the interface design information be identified and tracked as the software system is being developed, tested, and operated. Software interface designs and requirements tend to drive software designs and can lead to a potential source of anomalies during the development and operational life cycle. The key to implementing this requirement is to have a good description of all software, hardware, operations, and system interfaces and interactions during the design and operational phases of a development cycle. The content of the IDD is defined by PDR (Preliminary Design Review)).  The preliminary IDDs are expected to be approximately 30 percent completed at PDR.  All interface components are to be defined by PDR.  The IDDs are completed by CDR (Critical Design Review) and updated as needed after CDR. The final as-built IDD is documented as a part of the as-built design documentation for operational use, software modification, and potential software reuse applications.

The descriptions contain the interface characteristics for systems or configuration items that participate in the interface (including human-system and human-human interfaces), standards and protocols, responsible parties, interface operational schedules, and any error handling routines. The software team also defines those interface characteristics that are existing or permanent, as well as those that are being developed or modified. The applicability of this requirement is highly dependent on the classification level for the software work product(s). Appendix D, Requirements Mapping Matrix, of NPR 7150.2 shows the requirements for each classification level (see SWE-020).

An excellent way to begin the descriptions of the interfaces is with a context or state diagram. A suitably detailed diagram (showing the relationship of the interface with the overall activity) with legends and callouts will easily show the dependencies that must be controlled and satisfied in the software detailed design. Either a single diagram or an interrelated set of diagrams, depending on the complexity of the software work product(s), may be the most appropriate choice.

As shown in the SWE-112 requirements text above, the software IDD document is required to contain specific information. Below are suggestions for the type of information to consider for the named required content.

Document content

The following paragraphs are based on Department of Defense (DoD) DI-IPSC-81436A, Data Item Description Interface Design Description (IDD) ⁰²⁵, along with supporting material from  GRC (Glenn Research Center) GRC-SW-TPLT-IDD, Interface Design Description (IDD) Template. ²²⁷

• Assigned priority.
  This is the priority assigned to the interface by the interfacing entity(ies).The level of the priority allows the software to service higher priority queues ahead of lower priority queues. Complex priority values may allow timeouts and software interrupts to avoid the starving of lower priority interfaces.
• Type of interface.
  The IDD document includes characteristics about interface types, such as real-time data transfer, storage-and-retrieval of data, remote programming interface, etc., that will be implemented.

Factors like functionality, performance speed, the time needed to use the program, user satisfaction, and the rate of user errors are some criteria for the software development team to consider when designing an interface. The software interface tests are specified in the Software Test Plan (see SWE-104 and SWE-114).

The two most common ways of expressing interface information are (1) alphabetically by parameter and (2) for data-oriented interfaces, by layers with reference to a level-of-abstraction model such as the Open Systems Interconnection (OSI)-7 Layer model. ³⁰³  In the latter case, individual information items, e.g., requirements or characteristics, are framed consistent with the layer definitions and then specified by layer, "physical" up to  "application" in that order of the OSI-7 Layer model. Within a layer, control flow sequence is used where applicable to express information; otherwise it is expressed alphabetically by parameter.

• Specifications of individual data elements
  The IDD document includes characteristics about the individual data elements that the interfacing entity(ies) will provide, store, send, access, receive, etc., such as:
  • Names/identifiers.
    1. Project-unique identifier.
    2. Nontechnical (natural language) name.
    3. Standard data element name.
    4. Technical name, e.g., variable or field name in code or database.
    5. Abbreviation or synonymous names.
  • Data type (alphanumeric, integer, etc.), indicating data types that are not defined until implementation, such as C++ type overloading (templates) and dynamic typecasting.
  • Size and format, i.e., length and punctuation of a character string or bit-level descriptions.
  • Units of measurement, i.e., meters, dollars, or nanoseconds.
  • Range or enumeration of possible values, i.e., 0 to 99.
  • Accuracy (how correct) and precision (number of significant digits).
  • Priority, timing, frequency, volume, sequencing, and other constraints, such as whether the data element may be updated and whether business rules apply.
  • Security and privacy constraints.
  • Sources (setting or sending entities) and recipients (using or receiving entities).
  • Safety criticality.
• Specifications of data element assemblies
  The IDD document includes characteristics about data element assemblies, such as records, messages, files, arrays, displays, reports, etc., that the interfacing entity(ies) will provide, store, send, access, receive, etc., such as:
  • Names/identifiers.
    1. Project-unique identifier.
    2. Nontechnical (natural language) name.
    3. Technical name, e.g., record or data structure name in code or database.
    4. Abbreviations or synonymous names.
  • Data elements in the assembly and their structure (number, order, grouping, and bit-level descriptions).
  • Medium, i.e., disk, and structure of data elements or assemblies on the medium.
  • Visual and auditory characteristics of displays and other outputs, i.e., colors, layouts, fonts, icons, and other display elements, beeps, and lights.
  • Relationships among assemblies, such as sorting or access characteristics.
  • Priority, timing, frequency, volume, sequencing, and other constraints, such as whether the assembly may be updated and whether business rules apply.
  • Security and privacy constraints.
  • Sources (setting or sending entities) and recipients (using or receiving entities).
  • Safety criticality.
• Specifications of communication methods
  The IDD document includes characteristics about communication methods that the interfacing entity(ies) will use for the interface, such as:
  • Project-unique identifier(s).
  • Communication links, bands, frequencies, media, and their characteristics.
  • Message formatting.
  • Flow control, i.e., sequence numbering and buffer allocation.
  • Data transfer rate, whether periodic or aperiodic, and interval between transfers.
  • Routing, addressing, and naming conventions.
  • Transmission services, including priority and grade.
  • Security and privacy considerations, such as encryption, user authentication, compartmentalization, and auditing.
  • Safety criticality.
• Specifications for communications protocol
  The IDD document includes characteristics about digital message formats and the rules for exchanging those messages. A protocol defines the syntax, semantics, and synchronization of communication, and the specified behavior is typically independent of how it is to be implemented. A protocol can therefore be implemented as hardware or software or both. Characteristics of protocols the interfacing entity(ies) will use for the interface include: 
  • Project-unique identifier(s).
  • Priority or layer of the protocol.
  • Packeting, including fragmentation and reassembly, routing, and addressing.
  • Legality checks, error control, and recovery procedures.
  • Synchronization, including connection establishment, maintenance, and termination.
  • Status, identification, and any other reporting features.
• Other characteristics, such as
  Physical compatibility of the interfacing entity(ies) (dimensions, tolerances, loads, voltages, plug compatibility, etc.).
• Traceability
  Show the path from each interfacing entity to the system or CSCI requirement addressed by the design. To complete the bidirectional tracing of the requirements, show from each system or CSCI requirement to the interfacing entity that addresses it. (See SWE-059 on bidirectional traceability.)
• Interface Compatibility
  The IDD document contains information about the intended compatibility between or among the interfaces being developed. Specifically, will there be uniform or optional approaches to developing weak versus strong compatibility? Will the compatibility of the software components' interaction with their environment be characterized as optimistic or pessimistic in nature?
• Safety-related interface specifications and design features
  Safety-critical off-the-shelf (OTS) and reused software must undergo safety analysis that considers:
  • Its ability to meet required safety functions.
  • Extra functionality that may be present, even if not planned for use.
  • The impact on safety.
  • Interfaces to developed code.

Additional analysis, testing, or a combination thereof can be performed to verify safety-critical OTS or reused software to the same level required of in-house developed software to the extent possible via black box testing.

The Contract Data Requirements List specifies whether deliverable data are to be delivered on paper or electronic media; may be delivered in developer format rather than in the format specified herein; and may reside in a computer-aided software engineering or other automated tool rather than in the form of a traditional document.

Best practices

The software development team solicits relevant stakeholder involvement to evaluate applicable system interface(s).

Whenever possible, the software development team considers using an industry recognized standard for system interfaces.

4. Small Projects

The proper execution of interfaces among entities in software design activities is no less important for small projects than for large projects. Improper interface development, evaluation, and testing will cause any software work product to fail to function, regardless of the size of the project.

Smaller projects may benefit by using standard interface designs or

IDD (Interface Design Documents) templates ²²⁷ previously developed and cataloged in software reuse repositories or by using personnel with previous experience on identical or similar interfaces. Where applicable, the information required for SWE-112 may be duplicated from IDDs written for previously developed software interfaces. Extreme care is used whenever deciding to reuse software. (See SWE-027 for information that may be applicable.) (See the Center's repository of best practices for additional guidance in this area (see SWE-099).)

5. Resources

5.1 Tools

Tools to aid in compliance with this SWE, if any, may be found in the Tools Library in the NASA Engineering Network (NEN).

NASA users find this in the Tools Library in the Software Processes Across NASA (SPAN) site of the Software Engineering Community in NEN.

The list is informational only and does not represent an “approved tool list”, nor does it represent an endorsement of any particular tool. The purpose is to provide examples of tools being used across the Agency and to help projects and centers decide what tools to consider.

6. Lessons Learned

 The NASA Lessons Learned database contains the following lessons learned related to interface design:

• Mars Climate Orbiter Mishap Investigation Board - Phase I Report. Lesson Number 0641: "The MCO Mishap Investigation Board (MIB)...determined that the root cause for the loss of the MCO spacecraft was the failure to use metric units in the coding of a ground software file." The data in the ... file was required to be in metric units per existing software interface documentation, and the trajectory modelers assumed the data was provided in metric units per the requirements. In fact, the angular momentum (impulse) data was in English units rather than metric units. The failure to properly communicate what was in the interface documentation is a warning that the effective implementation of the IDD requirement includes adequate communication of its contents, not just the writing and recording. ⁵¹³
   
   
• Interface Control and Verification. Lesson Number 0569: Problems occurred during the Mars Pathfinder spacecraft integration and test due to out-of-date or incomplete interface documentation. (While this lesson involves a hardware-related problem, it illustrates the need for accuracy in interface documentation.) Investigation showed that the main wiring harness was built in accordance with documentation that had not been updated after design changes were made. In part, this was due to independently prepared Mechanical Interface Control Drawings (MICD) by the Government and the contractor.  The MICDs should have had periodic verification for accuracy and compatibility. ⁵⁰⁸