WorkProductDescriptor
Work Product (Artifact): Component Specification
Specifies the details for individual components identified in the Component Model.
Purpose

The Component Specification details the responsibilities and key characteristics for individual components. These details allow developers to create an executable architecture to validate the architectural approach.

Relationships
Container Artifact
RolesResponsible: Modified By:
Input ToMandatory:
  • None
Optional: External:
  • None
Output From
Description
Main Description

This artifact specifies the details of a component identified in the Component Model. The specification shows the interfaces offered and used by the component, identifies where business rules are placed, and details the operations and their signatures for each interface.

Component Interfaces - An interface specifies one or more operation signatures and is both offered and used by a component. Offering an interface means the component makes the interface available for other components to use.  Each interface provides a unique and well-defined set of operations. Hiding the structure of a component and its data behind an interface allows that data to be changed without affecting how the interface is used.  The actual composition of that data may change, but the interface that provides access to that data is fixed. Interfaces also describe the state of a component.

Business Rules - Business Rules dictate the behavior of a system, and the component specification defines how the system implements the business rules.  For example, a business rule may state that Internet transactions for an on-line order can not exceed $1000 for a given account. A component that manages account transactions may define an on-line transactions interface that implements this business rule.

Operations - Fully specified Component Specifications assign operations and operation signatures to the interfaces and may define pre- and post-conditions on the operations.  Pre- and post-conditions specify the effect of an operation without prescribing an algorithm or implementation. A post-condition specifies the effect of the operation on the components data or state. A pre-condition is the condition under which the operation guarantees that the post-condition is true.

Brief Outline

The Component Specification defines the following information for each component:

  • Name - uniquely identifies the component and its primary function
  • Description -outlines the primary function of the component and how it is positioned within the overall architecture
  • Responsibilities -lists responsibilities allocated to the component, stated in natural language
  • Required service levels - for non-functional requirements, lists all the service levels that the component must support (such as must be available during office hours)
  • Reasonableness & risk - identifies the risks associated with this component, together with a mitigation strategy if the risk is high
  • Design rationale - details any design decisions that influence how the component should be implemented
  • Implementation approach - details how the component should be implemented and the technology used to implement it
  • Component Interfaces - lists and visually models the interfaces offered and used by a component
Properties
Optional
Planned
Illustrations
Key Considerations

Points to consider when deciding whether to use a Component Specification:

  • The Component Specification provides value when the architecture is complex, such that new team members need a simplified, abstracted model to understand it.
  • The extra work required to ensure that the Component Specification and Executable Architecture remain consistent must be balanced against the benefit of having a view of the system that represents only the most important details of how the system works. It can be very costly to maintain a high degree of fidelity between the Component Specification and Executable Architecture. As the complexity of the Component Specification increases, so does the cost to maintain it.
  • Once you no longer maintain the Component Specification, its value decays rapidly. At some point, it will no longer accurately reflect the Executable Architecture. Deciding to no longer maintain the Component Specification may be appropriate (it may have served its purpose), but the decision should be a conscious one.

Component Specifications tend to be useful in companies where systems live for decades, or where there are many variants of the system.

Tailoring
Impact of not having

The absence of this work product may result in:

  • Brittle architecture with components that may not be reused, maintained, or replaced without impacting the overall system 
  • Ambiguous and incomplete component definitions requiring developers to clarify the scope and interoperability of components
  • Inability to select appropriate implementation technologies or 3rd party packages to implement component responsibilities 
  • Difficulty creating an executable architecture to validate the architectural approach
Reasons for not needing

A Component Specification may not be necessary when:

  • The overall system is quite small and the division of functional responsibility between components is clearly understood 
  •  The structure of the overall system can be adequately described in some other form 
  • The environment for the system is trivial and does not require detailed considerations of how applications and data are organized
Representation Options

Notation

The Component Specification consists of both a textual definition and visual model of a component's responsibilities, characteristics, and interfaces.

The textual definition includes the following information:

Property

Description

UML Representation

Name

The name of the Component

The attribute "Name" on model element.

Description

Brief description of the component

Tagged value, of type "short text".

Responsibilities

List of component responsibilities

A (predefined) tagged value on the superclass "Type".

Required Service Levels (Non-Functional Requirements)

List of Service Levels supported by the Component

Tagged value, of type "short text".

Reasonableness & Risk

Statement(s) about the risks associated with the design of the component

Tagged value, of type "short text".

Design Rationale

Component design decisions

Tagged value, of type "short text".

Implementation Approach

Implementation guidance and instructions

Tagged value, of type "short text".

Diagrams

Diagrams (detailed below) local to the component that complete its specification.

Owned by an enclosing package, via the aggregation "owns".

The visual model consists of three UML diagrams:

  • Component Specification Diagram - shows the interfaces offered and used by a component
  • Interface Responsibility Diagram - depicts the data managed by each interface; shows dependencies between data and interfaces
  • Interface Specification Diagram - shows the information types managed by interfaces; shows how interfaces manage a component's state

Component Specification Diagram

Component Specification Diagram

A component specification diagram shows a single component with the interfaces it uses as well as the ones it offers.

Interface Responsibility Diagram

Interface Responsibility Diagram

An Interface Responsibility Diagram the information managed each interface and brings dependencies to the surface. It shows an association between interfaces and entities from the logical data model (LDM). It does not show information or state that the components manage through the interfaces.

Interface Specification Diagram

Interface Specification Diagram

An Interface Specification Diagram depicts the information model of an interface. It shows all of the information types that are needed by the interface. These types correspond to dynamic or "in-flight" data. They are not the same as persistent data, but they usually map to the underlying entities of the logical data model from which they are derived.

More Information