bannera

Book A.
Introduction

Book B.
7150 Requirements Guidance

Book C.
Topics

Tools,
References, & Terms

SPAN
(NASA Only)

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

...

Alias
aliasSWE-110

...

Tabsetup
1. The Requirement
12. Rationale
23. Guidance
34. Small Projects
45. Resources
56. Lessons Learned
1. The Requirement
{div3:id=} h1.
Wiki Markup
Div
idtabs-1

1.

Requirements

5.2.2.1

The

Software

Data

Dictionary

shall

include:

\

[SWE-110

\

]

a.

Channelization

data

(e.g.,

bus

mapping,

vehicle

wiring

mapping,

hardware

channelization).


b.

Input/Output

(I/O)

variables.


c.

Rate

group

data.


d.

Raw

and

calibrated

sensor

data.


e.

Telemetry

format/layout

and

data.


f.

Data

recorder

format/layout

and

data.


g.

Command

definition

(e.g.,

onboard,

ground,

test

specific).


h.

Effecter

command

information.


i.

Operational

limits

(e.g.,

maximum/minimum

values,

launch

commit

criteria

information).

h2. {color:#003366}{*}

1.1

Notes{*}{color} NPR

Notes

NPR 7150.2,

NASA

Software

Engineering

Requirements,

does

not

include

any

notes

for

this

requirement.

h2.

1.2

Applicability

Across

Classes

Class

B

and

Class

B

and

Safety

Critical

and

Classes

C

through

E

and

Safety

Critical

are

labeled

with

"P

(Center)

+

SO."

 

  This

means

that

the

requirement

must

be

met

to

the

extent

necessary

to

satisfy

safety-critical

aspects

of

the

software

and

an

approved

Center-defined

process

that

meets

a

non-empty

subset

of

the

full

requirement

can

be

used

to

other

aspects

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.

Classes

F

and

G

are

labeled

with

"X

(not

OTS)."

 

  This

means

that

this

requirement

does

not

apply

to

off-the-shelf

software

for

these

classes.

{applicable:asc=1|ansc=1|bsc=*|bnsc=*|csc=*|cnsc=p|dsc=*|dnsc=0|esc=*|ensc=0|f=*|g=*|h=0} {div3}

Wiki Markup
{div3:id=tabs-2}

h1. 2. Rationale

The preparation, documentation, and use of a Software Data Dictionary (SDD) enable uniform communication among the team members on a software development project. The SDD provides key information needed for the implementation, testing, and maintenance of the software product. The data dictionary allows developers, maintainers, and analysts to access information about the tables, fields, procedures, processes, and other information in the system.  Customers and users have a ready reference of information about the software work product.
{div3}
Wiki Markup
{div3:id=tabs-3}

h1. 3. Guidance

The Software Data Dictionary (SDD) may be a stand-alone project document; it may be included as part of an electronic database; or it may be written as an appendix in one of the project's primary documents, e.g., the systems requirement specification (see [SWE-109|SWE-109]) or the software design description document (see [SWE-111|SWE-111] and [SWE-112|SWE-112]). Either format (hardcopy or electronic) is compliant with the requirement.

A data dictionary includes a set of meta-data that contains the definition and representation of data elements. A data dictionary lists all data elements but does not say anything about the relationships between elements. It gives a single point of reference for a data repository of an organization.

Some of the typical components of a data dictionary entry are:
* Name of the table.
* Name of the fields in each table.
* Data type of the field (integer, date, text, etc.).
* Brief description of the expected data for each field.
* Length of the field.
* Default value for that field.
* Whether the field is Nullable or Not Nullable.
* Constraints that apply to each field, if any.

{panel}Not all of these fields will apply for every single entry in the data dictionary. {panel}

Designers, programmers, users, maintainers, and administrators of a computer system as an administrative resource are the main users of the SDD. Data dictionaries are used to maintain information on systems hardware and software configurations, documentation, application, and users, as well as other relevant information.

The SDD can be produced:
* Automatically, using a software tool to interrogate the database and to map its content.
* Manually, by examining the code to determine and record its content.
* By a combination of the two.

{panel}An electronic data dictionary is said to be active or passive. The term "passive" applies to the data dictionary that must be updated manually, whereas the term "active" applies to the data dictionary that is updated automatically by a database manager tool as data in the database is updated.  {panel}

The data in the SDD may be in the form of tables. Typically, the table definitions define the tables in the database, including a brief description of their use, the key fields, the primary key, and a list of the fields.

Guidance and examples for the required content of the SDD are included in the bullets below:
* Channelization data, e.g., bus mapping, vehicle wiring mapping, hardware channelization, provides a description of each data channel and where it maps to.
* Input/Output (I/O) variables provide a description of each I/O variable. Specify format, unit of measure, and definition.
* Rate group data, e.g., science data is collected at 1000 Hz, and health and status data is collected at 1 Hz.
* Raw and calibrated sensor data provide a description of the format, units of measure, and definition of each sensor. Specify data reduction for transforming raw data into calibrated data.
* Telemetry format/layout and data provide a description of the telemetry mode, format, packetization and definition:
** Specify what types of packets are allowed to be sent for each of the telemetry modes.
** Specify maximum data rate for each mode.
** The telemetry format usually includes data type, data representation, data size, acceptable range values, unit of measure, and the meaning of the data for each field.

* Data recorder format/layout and data
* Command definition, e.g., onboard, ground, test specific, provides a description for each of the commands processed by the software work package. Include the purpose, function, the format of the command and its parameters, and any restrictions attendant to the command.
* Effecter command information provides information about the setting of names or flags that cause command executions in the software work products.
* Operational limits, e.g., maximum/minimum values, launch commit criteria information.
\\

Other candidate information for the software data dictionary includes:

* Data channelization.
* Data description.
* Data location.
* Data relationships.
* Data sources and destinations.
* Data structure.
* Data type.
* Data units.
* Data use.
* Data values, e.g., range and calibration data.
* Database schema and database management systems.
* Object-oriented class and method descriptions.
* Entity-relationship diagrams.
\\

Finally, the SDD includes descriptions of each process carried by the database system, including:
* Where and how the data enters the system.
* What is done to the data, at what stage, and why.
* What the outputs of the system are (if any).
* How to control, update, and distribute the SDD.
\\

{panel}When performing class F and G software development, the appropriate Center Chief Information Officer is expected to provide appropriate guidance for the fulfillment of this requirement. In all cases, engineering judgment is expected to be used when finalizing the approach to satisfying SWE-110.  {panel}


Additional guidance related to the production of the SDD may be found in the work products generated by the following related requirements in this Handbook:
| [SWE-103|SWE-103] | Software Configuration Management Plan |
| [SWE-104|SWE-104] | Software Test Plan |
| [SWE-105|SWE-105] | Software Maintenance Plan |
| [SWE-111|SWE-111] | Software Design Description |
| [SWE-112|SWE-112] | Interface Design Description |
| [SWE-115|SWE-115] | Software User Manual |
| [SWE-116|SWE-116] | Software Version Description |
\\
{div3}
Wiki Markup
{div3:id=tabs-4}

h1. 4. Small Projects

This requirement is applicable to all projects regardless of size.  Small projects may be able to leverage SDDs, or portions of dictionaries, from previous projects, as long as those projects had similar data structures.
{div3}
Wiki Markup
{div3:id=tabs-5}

h1. 5. Resources

{refstable}

{toolstable}
{div3}
Wiki Markup
{div3:id=tabs-6} h1. 6. Lessons Learned A documented lesson from the NASA Lessons Learned database notes the following: *Develop and Test the Launch Procedure Early (1997).* *Lesson Number* *0609:* The Abstract states: "During the terminal countdown for the first attempted launch of Cassini, spacecraft telemetry channels indicated a false alarm condition that delayed verification of spacecraft readiness for launch, and contributed to a delay on the first launch day. The anomaly was traced to erroneous telemetry documentation. Develop and release the launch procedure early enough for comprehensive testing before launch. Rigorously test and verify all telemetry channels and their alarms and ensure documentation such as telemetry definitions is kept up to-date."{sweref:565} {div3}

applicable
f*
g*
h0
asc1
ansc1
bnsc*
csc*
bsc*
esc*
cnscp
dsc*
dnsc0
ensc0
Div
idtabs-2

2. Rationale

The preparation, documentation, and use of a Software Data Dictionary (SDD) enable uniform communication among the team members on a software development project. The SDD provides key information needed for the implementation, testing, and maintenance of the software product. The data dictionary allows developers, maintainers, and analysts to access information about the tables, fields, procedures, processes, and other information in the system.  Customers and users have a ready reference of information about the software work product.

Div
idtabs-3

3. Guidance

The Software Data Dictionary (SDD) may be a stand-alone project document; it may be included as part of an electronic database; or it may be written as an appendix in one of the project's primary documents, e.g., the systems requirement specification (see SWE-109) or the software design description document (see SWE-111 and SWE-112). Either format (hardcopy or electronic) is compliant with the requirement.

A data dictionary includes a set of meta-data that contains the definition and representation of data elements. A data dictionary lists all data elements but does not say anything about the relationships between elements. It gives a single point of reference for a data repository of an organization.

Some of the typical components of a data dictionary entry are:

  • Name of the table.
  • Name of the fields in each table.
  • Data type of the field (integer, date, text, etc.).
  • Brief description of the expected data for each field.
  • Length of the field.
  • Default value for that field.
  • Whether the field is Nullable or Not Nullable.
  • Constraints that apply to each field, if any.
Panel

Not all of these fields will apply for every single entry in the data dictionary.

Designers, programmers, users, maintainers, and administrators of a computer system as an administrative resource are the main users of the SDD. Data dictionaries are used to maintain information on systems hardware and software configurations, documentation, application, and users, as well as other relevant information.

The SDD can be produced:

  • Automatically, using a software tool to interrogate the database and to map its content.
  • Manually, by examining the code to determine and record its content.
  • By a combination of the two.
Panel

An electronic data dictionary is said to be active or passive. The term "passive" applies to the data dictionary that must be updated manually, whereas the term "active" applies to the data dictionary that is updated automatically by a database manager tool as data in the database is updated.  

The data in the SDD may be in the form of tables. Typically, the table definitions define the tables in the database, including a brief description of their use, the key fields, the primary key, and a list of the fields.

Guidance and examples for the required content of the SDD are included in the bullets below:

  • Channelization data, e.g., bus mapping, vehicle wiring mapping, hardware channelization, provides a description of each data channel and where it maps to.
  • Input/Output (I/O) variables provide a description of each I/O variable. Specify format, unit of measure, and definition.
  • Rate group data, e.g., science data is collected at 1000 Hz, and health and status data is collected at 1 Hz.
  • Raw and calibrated sensor data provide a description of the format, units of measure, and definition of each sensor. Specify data reduction for transforming raw data into calibrated data.
  • Telemetry format/layout and data provide a description of the telemetry mode, format, packetization and definition:
    • Specify what types of packets are allowed to be sent for each of the telemetry modes.
    • Specify maximum data rate for each mode.
    • The telemetry format usually includes data type, data representation, data size, acceptable range values, unit of measure, and the meaning of the data for each field.
  • Data recorder format/layout and data
  • Command definition, e.g., onboard, ground, test specific, provides a description for each of the commands processed by the software work package. Include the purpose, function, the format of the command and its parameters, and any restrictions attendant to the command.
  • Effecter command information provides information about the setting of names or flags that cause command executions in the software work products.
  • Operational limits, e.g., maximum/minimum values, launch commit criteria information.

Other candidate information for the software data dictionary includes:

  • Data channelization.
  • Data description.
  • Data location.
  • Data relationships.
  • Data sources and destinations.
  • Data structure.
  • Data type.
  • Data units.
  • Data use.
  • Data values, e.g., range and calibration data.
  • Database schema and database management systems.
  • Object-oriented class and method descriptions.
  • Entity-relationship diagrams.

Finally, the SDD includes descriptions of each process carried by the database system, including:

  • Where and how the data enters the system.
  • What is done to the data, at what stage, and why.
  • What the outputs of the system are (if any).
  • How to control, update, and distribute the SDD.
Panel

When performing class F and G software development, the appropriate Center Chief Information Officer is expected to provide appropriate guidance for the fulfillment of this requirement. In all cases, engineering judgment is expected to be used when finalizing the approach to satisfying SWE-110.  

Additional guidance related to the production of the SDD may be found in the work products generated by the following related requirements in this Handbook:

SWE-103

Software Configuration Management Plan

SWE-104

Software Test Plan

SWE-105

Software Maintenance Plan

SWE-111

Software Design Description

SWE-112

Interface Design Description

SWE-115

Software User Manual

SWE-116

Software Version Description


Div
idtabs-4

4. Small Projects

This requirement is applicable to all projects regardless of size.  Small projects may be able to leverage SDDs, or portions of dictionaries, from previous projects, as long as those projects had similar data structures.

Div
idtabs-5

5. Resources

refstable
toolstable
Div
idtabs-6

6. Lessons Learned

A documented lesson from the NASA Lessons Learned database notes the following:

Develop and Test the Launch Procedure Early (1997). Lesson Number 0609: The Abstract states: "During the terminal countdown for the first attempted launch of Cassini, spacecraft telemetry channels indicated a false alarm condition that delayed verification of spacecraft readiness for launch, and contributed to a delay on the first launch day. The anomaly was traced to erroneous telemetry documentation. Develop and release the launch procedure early enough for comprehensive testing before launch. Rigorously test and verify all telemetry channels and their alarms and ensure documentation such as telemetry definitions is kept up to-date."

sweref
565
565