System Requirement Specification OpenFastTrace

August 1, 2026 · View on GitHub

System Requirement Specification OpenFastTrace

System Requirement Specification OpenFastTrace

Introduction

OpenFastTrace (OFT) is a requirement tracing suite written in Java.

Goals

The OFT's goals are

  • Fast
  • Automation friendly
  • Useful
  • Platform independent

A requirement tracing suite must be fast in order to be used. Development time is precious and requirement tracing does not have a high priority compared to building and testing the software regularly. This means that tracing will only be accepted by the users if it does not eat away their development time.

Requirement tracing is a recurring and frankly quite boring task best performed by a machine instead of a person. Again the chances of getting accepted depend on getting this job "out of the way" and this means automating it. OFT therefore aims to offer easy integration into existing build processes, independently of the tool chains used.

It looks strange first that "useful" needs to be spelled out as a goal. The reason is that the authors felt that existing tracing tools are mostly optimized for producing proof that you worked according to process - i.e. reports that you can shelve until an quality auditor wants to see them. While OFT can do this too, it is not a main goal. Instead OFT wants to help developers and technical writers to find gaps and mismatches in their requirement coverage fast and with as little effort as possible.

OFT aims to help developers independently of their platform. I should not matter if you are developing on Linux, a Mac, BSD, Windows. Also it should not matter which programming language or development environment you are using. OFT aims to be portable and provide interfaces that allow integration into your existing toolchain.

Terms and Abbreviations

The following list gives you an overview of terms and abbreviations commonly used in OFT documents.

  • Artifact: a container for specification items
  • Artifact type: the role of an artifact in a specification hierarchy
  • Coverage: Specification items covering other specification items
  • Coverage provider: a specification item that provides coverage
  • Coverage requester: a specification item that needs coverage
  • OFT: OpenFastTrace (this project)
  • ReqM2: A requirement tracing suite
  • Specification item: holds either a requirement or coverage
  • Specification artifact: a data source containing specification items (e.g. file, ticket system, database)

In the following subsections central terms are explained in more detail.

Specification Items

In OFT requirements and artifacts covering them are represented by specification items. Each item is a container for attributes of requirements and covering artifacts like the name, artifact type and the location where OFT found them.

A specification item can also contain information about its relationships to other specification items. For more details about those relationships check section "tracing".

Coverage

Coverage is a measure of how well the tracing result matches the required relations between specification items.

Full coverage is what a project aims to achieve: all required relations between specification items exist.

An item is undercovered if at least one of the required relations is missing. It is overcovered if at least one relation exists that is not required.

Features

Requirement Tracing

feat~requirement-tracing~1

OFT traces requirements from specification to any kind of coverage (document, implementation, test, etc.).

Needs: req

Markdown Import

feat~markdown-import~1

OFT imports specification items from Markdown files.

Rationale:

Markdown is a clean and simple format that:

  • is viewable with any text editor
  • focuses on content instead of layout
  • is portable across platforms
  • easy to process with text manipulation tools

For those reasons Markdown is a suitable candidate for writing specification that can be read and maintained over a long time.

Needs: req

ReStructured Text (RST) Import

feat~rst-import~1

OFT imports specification items from ReStructured Text (RST) files.

Rationale:

RST is a text-based documentation format with non-invasive structure elements. It originated in the Python world and has become the standard for documentation there.

The same benefits as for Markdown apply:

  • is viewable with any text editor
  • focuses on content instead of layout
  • is portable across platforms
  • easy to process with text manipulation tools

Needs: req

ReqM2 Import

feat~reqm2-import~1

OFT imports specification items from ReqM2 files.

Rationale:

One of the OpenFastTrace design goals is to provide a Java-based drop-in replacement for ReqM2, so file format compatibility is essential.

Needs: req

Coverage Tag Import

feat~coverage-tag-import~2

OFT imports coverage tags from source code files and supported documentation files.

Rationale:

Coverage tags indicate parts of source code or documentation that cover a certain requirement.

Needs: req

Gherkin Import

feat~gherkin-import~1

OFT imports specification items from annotated Gherkin scenarios and scenario outlines in .feature files.

Needs: req

Import Gherkin Scenarios

req~gherkin-scenario-import~1

OFT imports a Gherkin Scenario or Scenario Outline as a specification item when its immediately preceding contiguous tag region contains exactly one @id:<specification-item-id> tag. The ID supplies the item location, the scenario header supplies the title, and scenario steps form the description. An invalid ID skips only the affected scenario. Duplicate item IDs are passed to the OFT core for validation.

Covers:

Needs: dsn

Validate Gherkin Covers Metadata

req~gherkin-covers-validation~1

OFT accepts optional, scoped # Covers: comments between an ID tag region and its scenario header. Covers may occur multiple times. Each directive must contain a non-empty, valid, duplicate-free list of specification item IDs. An invalid Covers directive skips only the affected scenario.

Covers:

Needs: dsn

Validate Gherkin Needs Metadata

req~gherkin-needs-validation~1

OFT accepts an optional, scoped # Needs: comment between an ID tag region and its scenario header. The directive may occur once and must contain a non-empty, valid, duplicate-free list of artifact types. An invalid or repeated Needs directive skips only the affected scenario.

Covers:

Needs: dsn

Preserve Gherkin Comment Coverage Tags

req~gherkin-comment-coverage-tags~1

OFT imports basic coverage tags from comments in .feature files, but does not evaluate coverage tags in executable Gherkin lines.

Covers:

Needs: dsn

ReqM2 Export

feat~reqm2-export~1

OFT exports specification items to ReqM2 files.

Rationale:

One of the OpenFastTrace design goals is to provide a Java-based drop-in replacement for ReqM2, so file format compatibility is essential.

Needs: req

Tracing Reports

A tracing report is a representation of the results of the requirement tracing OFT performs. Depending on their use, reports can be designed to be human readable, machine readable or both.

Console Reports

Plain Text Report

feat~plain-text-report~1

OFT produces a tracing report in plain text.

Rationale:

This can be read directly as console output or with any text editor.

Needs: req

HTML Report

feat~html-report~1

OFT produces a tracing report in Hypertext markup language (HTML).

Rationale:

This report type is more optically appealing than the plain text report and still widely supported on all platforms.

Needs: req

User Interface

Command Line Interface

feat~command-line-interface~1

OFT offers a command line interface.

Rationale:

Running traces automatically in a scripted environment is the most important use case.

Needs: req

Third Party Plugins

feat~plugins~1

Users can extend OFT's features with plugins from third parties.

Rationale:

  • Some use cases or proprietary file formats might only be relevant for a very small user group. It does not make sense to integrate this into the core OFT product.

  • Some importers/exporters require additional dependencies that we don't want to include in the core OFT product.

  • We want to be able to release OFT and the plugins independently. Especially if the plugins have many dependencies, it is expected that they need frequent security updates. By keeping them separate, we make sure that users don't have to update OFT whenever a plugin needs a security update.

Needs: req

Functional Requirements

Anatomy of Specification Items

Specification Item

req~specification-item~2

A specification item consists of the following parts:

  • ID
  • Title (optional)
  • Status (optional)
  • Description (optional)
  • Rationale (optional)
  • Comment (optional)
  • Covers (optional)
  • Depends (optional)
  • Needs (optional)
  • Tags (optional)

The ID is a unique key through which the specification item can be referenced. It also contains the specification item type and revision number.

The title is a short summary of the specification item, mostly intended to appear in overview lists.

The status of the item is one of "approved", "proposed", "draft" and "rejected".

The description contains the normative part of the specification.

The rationale explains the reasoning behind a requirement or decision.

The "Covers" section contains a list of all specification item IDs that are covered by this item.

The "Depends" section contains a list of all specification item IDs that must be implemented in order for this item to be complete.

The "Needs" section list all artifact item types in which coverage for this item must be provided.

Tags are a way to label an artifact intended for grouping.

Covers:

Needs: dsn

Forwarding Needed Coverage

req~forwarding_needed_coverage~1

OFT allows users to forward needed coverage from one artifact type to one or more different types.

Rationale:

Often a system requirement does not affect the high-level architecture. In this case it is convenient for the architect to hand it down to lower levels directly.

Covers:

Needs: dsn

Supported Formats

Common Requirements for Lightweight Markup Import

Typical OFT specifications are written in a lightweight markup language like Markdown or ReStructured Text. Before we go into the specifics, this section discusses the common requirements.

Disabling OFT Parsing for Parts of a Markup File

req~disabling-oft-parsing-for-parts-of-a-markup-file~1

OFT-enhanced markup allows excluding text blocks from OFT parsing with the syntax oft:on|off.

Example for Markdown:

<!-- oft:off -->
This part of the document will not be parsed for OFT specification items.

Until the end marker or the end of the current document is reached
<!-- oft:on -->

Example for RST:

.. oft:off
Not imported.
.. oft:on

Rationale:

This allows creating OFT examples that do not contribute to the code and avoid accidental recognition of specification items in text that is not supposed to contain them.

Covers:

Needs: dsn

Markdown

Markdown is a simple ASCII-based markup format that is designed to be human-readable in the source. While it can be rendered into HTML, it is perfectly eye-friendly even before rendering.

Markdown focuses on content over formatting by giving the document structure like headlines, paragraphs and lists. The combination of being lightweight, human-readable and structure-oriented makes it a good fit for writing specifications as code.

OFT defines a Markdown format that we call "Requirement-Enhanced Markdown" which is a superset of the regular Markdown. Any Markdown renderer can render this format without understanding it. The additional structural definitions tell OFT which part of the text is a specification item.

For backward compatibility OFT supports a variant of this format that was introduced at Elektrobit. This format is a little bit closer to ReqM2, the predecessor that sparked the OFT idea. We recommend using the standard OFT Markdown format in new documents, though, since this format is cleaner.

Markdown Standard Syntax

req~markdown-standard-syntax~1

The OFT Markdown specification artifact format uses the standard Markdown syntax without proprietary extensions.

Rationale:

The specification documents that the OFT Markdown importer reads must be viewable with any regular Markdown reader and as plain text.

Covers:

Needs: dsn

Markdown Outline Readable

req~markdown-outline-readable~1

The Markdown outline -- a table of contents created from the heading structure by various Markdown editors -- must be human-readable.

Rationale:

In long specification documents the outline is the primary means of navigating the document. Only if the outline can be read easily, it is useful for authoring specification documents.

Covers:

Needs: dsn

Artifact Type Forwarding in Markdown

req~artifact-type-forwarding-in-markdown~1

The Markdown format features a compact way to forward a requirement from the artifact type that was originally required to one or more different artifact types.

Rationale:

Often a system requirement does not affect the high-level architecture. In this case it is convenient for the architect to hand it down to lower levels directly.

Covers:

Needs: dsn

Coverage Tags

Developers add coverage tags as comments to source code or supported documentation to indicate where certain specification items are covered.

Import Full Coverage Tag Format

req~import.full-coverage-tag-format~2

OFT imports coverage tags from source files and supported documentation files in a full format that contains all necessary information for tracing.

Covers:

Needs: scn, dsn

Import Short Coverage Tag Format

req~import.short-coverage-tag-format~2

OFT imports coverage tags from source files in a short format that requires additional configuration during import.

Covers:

Needs: scn, dsn

Import Coverage Tags from Markdown Comments

scn~markdown.comment-coverage-tags~1

Given a Markdown documentation artifact with coverage tags in standalone, single-line HTML comments, when OFT imports the artifact, then it creates coverage items at the tag-line location while continuing to import ordinary Markdown specification items unchanged. Text that resembles a coverage tag outside such a comment does not create a coverage item.

Covers:

  • req~import.full-coverage-tag-format~2
  • req~import.short-coverage-tag-format~2

Needs: dsn

Import Coverage Tags from RST Comments

scn~rst.comment-coverage-tags~1

Given an RST documentation artifact with coverage tags in standalone, single-line RST comments, when OFT imports the artifact, then it creates coverage items at the tag-line location while continuing to import ordinary RST specification items unchanged. Text that resembles a coverage tag outside such a comment does not create a coverage item.

Covers:

  • req~import.full-coverage-tag-format~2
  • req~import.short-coverage-tag-format~2

Needs: dsn

ReqM2 Format

ReqM2 is a markup format developed at Elektrobit. ReqM2 files traditionally use the .xml file extension, a better way is to use .oreqm instead since that identifies the files uniquely.

ReqM2 File Detection

req~import.reqm2-file-detection~1

OFT considers a file to be a ReqM2 file if it either

  1. has a the .oreqm extension or
  2. has a the .xml extension and the header indicates that it is a ReqM2 file.

Covers:

Needs: dsn

Tracing

req~tracing.outgoing-coverage-link-status~1

Outgoing coverage link means links that originate from a specification item and end at another specification item. OFT determines the status of an outgoing coverage link of a specification item.

The possible results are:

  1. Covers: link points to a specification item which wants this coverage
  2. Outdated: link points to a specification item which has a higher revision number
  3. Predated: link points to a specification item which has a lower revision number
  4. Ambiguous: link points to a specification item that has duplicates
  5. Unwanted: coverage provider has an artifact type the requester does not want
  6. Orphaned: link is broken - there is no matching coverage requester

Covers:

Needs: dsn

req~tracing.incoming-coverage-link-status~1

Incoming coverage link means links that end at a specification item and originate at another specification item OFT determines the incoming coverage link status of a requirement.

The possible results are:

  1. Covered shallow: coverage provider for a required coverage exists
  2. Covered unwanted: coverage provider covers an artifact type the requester does not want
  3. Covered predated: coverage provider covers a higher revision number than the requester has
  4. Covered outdated: coverage provider covers a lower revision number than the requester has

Covers:

Needs: dsn

Deep Coverage

req~tracing.deep-coverage~1

OFT marks a specification item as covered deeply if this item - and all items it needs coverage from - are covered recursively.

Covers:

Needs: dsn

Duplicate Items

req~tracing.duplicate-items~1

OFT marks a specification item as duplicate if other items with the same ID exist.

Covers:

Needs: dsn

Defect Items

req~tracing.defect-items~2

OFT marks a specification item as defect if the following criteria apply

  • The specification item has duplicates (i.e. another specification item with the same ID exists) or
  • The item has any other status than "rejected" and any of
    • At least one outgoing coverage link has a different status than "Covers"
    • The item is not covered deeply

Covers:

Needs: dsn

Transitive Defect

req~tracing.transitive-defect~1

OFT identifies a specification item as having a transitive defect if it is a defect item but has no direct defects.

An item has direct defects if:

  • It has duplicates.
  • It has bad links (any outgoing coverage link has a different status than "Covers").
  • It has uncovered artifact types (not all artifact types in its "Needs" section are covered by outgoing links).

Covers:

Needs: dsn

req~tracing.link-cycle~1

OFT detects if specification items are linked in a cycle.

Rationale: Link cycles are never intended and hard to find by hand in large collections of requirements.

Covers:

Needs: dsn

Partial Tracing

Usually the responsibility of document authors or coders when it comes to tracing is to make sure that they cover the input documents above. Only integrators or quality engineers are concerned with full chain coverage.

If the users try to run a regular trace without feeding in the artifacts all the way to the bottom level of the tracing chain, the coverage check will always report errors because of missing lower level coverage.

To mitigate the situation, OFT allows users to ignore required coverage for selected artifact types.

Example:

Kim is a software architect, and it is her job to cover the system requirements coming from Steve in her software architecture. Kim wants to make sure she did not forget to cover a system requirement and uses OFT to trace the two documents. The system requirement specification uses the artifact types feat and req where req covers the feat artifacts in the same document. Kim's architecture uses the artifact type sysarch which covers req and requires a detailed design dsn.

Obviously, the detailed design is missing at the point when Kim runs the trace. To mitigate this situation, Kim configures OFT to ignore all artifacts of type dsn, including the needed coverage. This allows Kim to validate coverage towards the system requirement without needing the detailed design document.

Include Only Artifact Types

req~include-only-artifact-types~1

OFT gives users the option to include only a configurable set of artifact types during processing.

Covers:

Needs: dsn

Include Only Item Statuses

req~include-only-item-statuses~1

OFT gives users the option to include only specification items with a configurable set of statuses during processing.

Covers:

Needs: dsn

Include Items Where at Least One Tag Matches

req~include-items-where-at-least-on-tag-matches~1

OFT gives users the option to include only specification items that have at least one tag from a configurable set of tags during processing.

Covers:

Needs: dsn

Include Items That Don't Have Tags Or Where at Least One Tag Matches

req~include-items-that-do-not-have-tags-or-where-at-least-one-tag-matches~1

OFT gives users the option to include only specification items that either do not have tags or have at least one tag from a configurable set of tags during processing.

Covers:

Needs: dsn

Reports

Reports are the main way to find out if a project's requirements are covered properly.

Common Report Functions

Requirement Origin in Report

req~reporting.requirement-origin~1

Users can choose to display the requirement origin (e.g. file and line number) in reports:

  • In the body of a specification item
  • For each link to a specification item

Rationale:

This is especially useful for debugging since it makes finding broken sources faster.

Covers:

Needs: dsn

Report Verbosity

OFT allows users to control the verbosity of the tracing report.

Report Verbosity Direct Failures

req~reporting.verbosity.direct-failures~1

The verbosity level direct_failures lists only the IDs of specification items with direct defects.

Covers:

Needs: dsn

Report Verbosity Direct Failure Summaries

req~reporting.verbosity.direct-failure-summaries~1

The verbosity level direct_failure_summaries lists only the summaries of specification items with direct defects.

Covers:

Needs: dsn

Report Verbosity Direct Failure Details

req~reporting.verbosity.direct-failure-details~1

The verbosity level direct_failure_details lists only the summaries and details of specification items with direct defects.

Covers:

Needs: dsn

Plain Text Report

The plain text report is the most basic report variant. It serves two main purposes:

  1. Input in build chains
  2. Minimal requirement coverage view with the least dependency. Any text terminal can display the plain text report.
Plain Text Report Summary

req~reporting.plain-text.summary~3

The summary in the plain-text report includes:

  • Result status
  • Total number of specification items
  • Total number of direct and transitive defect specification items (if any)

Covers:

Needs: dsn

Plain Text Report Specification Item Overview

req~reporting.plain-text.specification-item-overview~2

An item summary in the plain-text report includes

  1. Status
  2. Number of broken incoming links
  3. Total number of incoming links
  4. Number of broken outgoing links
  5. Total number of outgoing links
  6. Number of duplicates (not including this item)
  7. ID
  8. Status (unless "approved")
  9. Artifact types indicating coverage

Covers:

Needs: dsn

Plain Text Report Link Details

req~reporting.plain-text.link-details~1

The link detail section shows for all links of a specification item:

  1. Incoming / Outgoing
  2. Link status
  3. ID of the specification item on the other end of the link

Covers:

Needs: dsn

Monochrome Plain Text Report With Font Style

req~monochrome-plain-text-report-with-font-style~1

The plain text report supports different font styles to visually separate report elements.

Rationale:

This makes the report easier to read and works for people who are colorblind.

Covers:

Needs: dsn

Colored Plain Text Report

req~colored-plain-text-report~1

The plain text report supports color to visually separate report elements.

Rationale:

This makes the report easier to read.

Covers:

Needs: dsn

Plain Text Report Transitive Defect

req~reporting.plain-text.transitive-defect~1

The plain text report renders transitive defects less visually alarming than direct ones. Transitive defects are rendered with the suffix (transitive) and the status not ok is rendered in grey.

Covers:

Needs: dsn

HTML Report

HTML Report is a Single File

req~reporting.html.single_file~1

OFT creates the HTML Report as a single file.

Rationale:

It makes exchanging reports with other people easier if everything is contained in a single file.

Covers:

Needs: dsn

HTML Report Renders Details Expanded or Collapsed Initially as Configured

req~reporting.html.details-display~1

OFT allows configuring the display status of specification item details to expanded or collapsed by default.

Rationale:

Allowing the details section to be expanded and visible allows rendering the HTML report to a PDF document that contains all details.

Covers:

Needs: dsn

HTML Report Renders Valid HTML

req~reporting.html.valid-html~1

OFT generates valid HTML format for the HTML report.

Rationale:

This ensures correct and consistent rendering of the HTML report.

Covers:

Needs: dsn

HTML Report Transitive Defect Mark

req~reporting.html.transitive-defect-mark~1

The HTML report uses a special mark (❎) to indicate specification items with a transitive defect.

Covers:

Needs: dsn

HTML Report Summary

req~reporting.html.summary~2

The summary in the HTML report includes:

  • Result status
  • Total number of specification items
  • Completion status as a progress bar
  • Total number of direct and transitive defect specification items (if any)

Rationale:

This allows users to quickly identify if a failure is caused by the item itself or inherited from its dependencies.

Covers:

Needs: dsn

Requirement Format Conversion

OFT supports conversion from one requirement format into another for example from Markdown to ReqM2.

Requirement conversion allows using the input formats OFT support in combination with external tracing tool chains by converting the inputs into the format the toolchain expects.

ReqM2 Export

req~conversion.reqm2-export~1

OFT exports to ReqM2's "SpecObject" format.

Covers:

Needs: dsn

User Interface

Requirement Tracing

Requirement Tracing Command

req~cli.tracing.command~1

OFT allows requirement tracing via the command line.

Covers:

Needs: dsn

Tracing Output Format

req~cli.tracing.output-format~1

Users can select one of the following requirement tracing output formats (aka. "report formats"):

  • Plain text

Covers:

Needs: dsn

Default Tracing Output Format

req~cli.tracing.default-output-format~1

OFT uses plain text as requirement tracing output format if the user does not select one.

Covers:

Needs: dsn

Tracing Exit Status

req~cli.tracing.exit-status~1

The return value of the OFT executable reflects the overall tracing result.

Covers:

  • [featrequirement-tracing1](#requirement-tracing~1

Needs: dsn

Requirement Format Conversion

Requirement Conversion Command

req~cli.conversion.command~1

OFT allows requirement tracing via the command line.

Covers:

Needs: dsn

Conversion Output Format

req~cli.conversion.output-format~1

Users can select one of the following conversion output formats (aka. "export formats"):

  • ReqM2

Covers:

Needs: dsn

Default Conversion Output Format

req~cli.conversion.default-output-format~1

OFT uses ReqM2 as default conversion format if the user does not select one.

Covers:

Needs: dsn

Common

CLI Help

req~cli.help~1

help, -h and --help show a short help text with command line usage.

Covers:

Needs: dsn

CLI Version

req~cli.version~1

help, -h and --help show the version of OFT.

Covers:

Needs: dsn

Input Selection

req~cli.input-selection~1

Users can select requirement sources as combinations of files and directories.

Covers:

Needs: dsn

Input Directory Selection

req~cli.input-directory-selection~1

Users can select zero or more directories below which files and sub-directories are imported recursively.

Covers:

Needs: dsn

Default Input

req~cli.default-input~1

If users select neither files nor directories for input, OFT imports from the current working directory recursively.

Covers:

Needs: dsn

Newline Format

req~cli.newline-format~1

Users can choose between Unix-style and Windows-style newline encoding for outputs.

Rationale:

When users work together in teams where the team members use different platforms, configuring the newline helps the team to set a common standard.

Covers:

Needs: dsn

Default Newline Format

req~cli.default-newline-format~1

Unless selected by the user, OFT uses the native newline format of the platform it runs on for outputs.

Covers:

Needs: dsn

Third Party Plugins

Loading Plugins

req~plugins.loading~1

OFT automatically loads plugins from JAR files located in a predefined location at startup.

Rationale:

  • Plugins must be only installed once in the correct location.
  • This requires no additional configuration by the user.
  • OFT adheres to the standard locations for plugin installation depending on the OS.

Covers:

Needs: dsn

Supported Plugin Types

req~plugins.types~1

OFT supports the following plugin types:

  • Importers add support for importing requirements from additional file formats.
  • Exporters add support for exporting requirements in additional file formats.
  • Reports add support for generating reports in additional formats.

Covers:

Needs: dsn

Logging Available Plugins

req~plugins.log~1

OFT logs all currently available plugins at startup including the following information:

  • Plugin type (importer, exporter, reporter)
  • Location (included with OFT, external JAR)
  • Version number

Rationale:

This is helpful for debugging in case OFT does not use a plugin as expected.

Covers:

Needs: dsn