Data

Data Source Types

reqstool reads data from four different sources:

Local file system
Git repository
Maven repository (zip artifact)
PyPI package (tar.gz)

Data Inputs

reqstool reads both static (created by human) and dynamic data (generated by tools, e.g. test reports):

Static Data Inputs

reqstool looks for the following files in the location provided as an argument:

requirements/
  manual_verification_results.yml  (1)
  requirements.yml                 (2)
  reqstool_config.yml              (3)
  software_verification_cases.yml  (4)

1	See manual_verification_results.yml example \| JSON Schema
2	See requirements.yml example \| JSON Schema
3	See reqstool_config.yml example \| JSON Schema
4	See software_verification_cases.yml example \| JSON Schema

For example:

reqstool report-asciidoc local -p /home/ms001/requirements

reqstool will look for the files above in the folder specified by the -p argument.

Dynamic Data Inputs

Dynamic files (annotations and test results) are generated during the build process. Their location varies by ecosystem. A custom layout can be specified in reqstool_config.yml.

Artifact Structures by Ecosystem

Each ecosystem produces a different artifact structure that reqstool can consume.

Java

Build Output (Maven)

After building a Maven project, dynamic files reside in the target directory:

target/
  failsafe-reports/              (1)
  surefire-reports/              (2)
  generated-sources/
    annotations/
      resources/
        annotations.yml          (3)
  generated-test-sources/
    test-annotations/
      resources/
        annotations.yml          (4)

1	Integration test reports (Failsafe)
2	Unit test reports (Surefire)
3	Requirements annotations — see JSON Schema
4	SVCs annotations — see JSON Schema

Maven Artifact (ZIP)

The reqstool Java Maven Plugin packages static and dynamic files into a zip artifact (<project-id>-<version>-reqstool.zip) during the build. The plugin combines svcs_annotations.yml and requirements_annotations.yml into a single annotations.yml.

The published artifact has this structure:

requirements/
  manual_verification_results.yml  (1)
  requirements.yml                 (2)
  annotations.yml                  (3)
  reqstool_config.yml              (4)
  software_verification_cases.yml  (5)
  test_results/
    failsafe/                      (6)
    surefire/                      (7)

1	See example
2	See example
3	Combined annotations — see JSON Schema
4	See example
5	See example
6	Integration test reports (Failsafe)
7	Unit test reports (Surefire)

For Gradle projects, the reqstool Java Gradle Plugin produces an equivalent artifact structure.

Python

Build Output (Hatch/Poetry)

After building a Hatch or Poetry project, dynamic files reside in the build directory:

build/
  reqstool/
    annotations.yml  (1)

1	Generated annotations — see JSON Schema

PyPI Package (tar.gz)

The reqstool Python Hatch Plugin or reqstool Python Poetry Plugin adds a custom reqstool_config.yml to the tar.gz with paths based on the package structure.

The published package has this structure:

<project_name>-<version>/
  build/
    reqstool/
      annotations.yml
    test_results.xml
  reqstool/
    manual_verification_results.yml
    requirements.yml
    reqstool_config.yml
    software_verification_cases.yml
  src/
  tests/
  reqstool_config.yml  (1)

1	Generated custom reqstool_config.yml — see JSON Schema

TypeScript

The reqstool TypeScript Tags processor scans TypeScript source files for annotation tags and generates an annotations.yml file. See the project documentation for details on the output structure.

Variant Data Matrix

Variant	Requirements	Annotations (implementation)	Annotations (tests)	Software Verification Cases	Automated Tests	Manual Verification Results
Microservice	yes	yes	yes	yes	yes	yes
System	yes	no	yes	yes	yes	yes
External	yes	no	no	no	no	no

Variant

Requirements

Annotations (implementation)

Annotations (tests)

Software Verification Cases

Automated Tests

Manual Verification Results

Microservice

yes

System

yes

External

yes

Imports

Requirements and software verification cases can be imported from other sources via the imports attribute in requirements.yml. Imports can be combined with Filters.

Local Import

Import from another source on the local file system:

requirements.yml

imports:
  local:
    - path: ../sys-001

Git Import

Import from a Git repository. The optional env_token field specifies an environment variable containing an authentication token. If no authentication is required, env_token can be omitted.

requirements.yml

imports:
  git:
    - url: https://github.com/reqstool/reqstool-demo
      branch: main
      path: docs/reqstool
      env_token: SECRET_TOKEN

Maven Import

Import from a Maven repository:

requirements.yml

imports:
  maven:
    - url: https://maven.pkg.github.com/reqstool/reqstool-client
      group_id: se.lfv.reqstool.testdata
      artifact_id: reqstool-testdata-test-basic-ms101
      path: ""
      version: 0.0.2

PyPI Import

Import from a PyPI package:

requirements.yml

imports:
  pypi:
    - env_token: PYPI_TOKEN
      url: https://pypi.org/project/reqstool/
      package: reqstool
      version: 0.4.7

Mixed Import Sources

It is also possible to import from multiple source types:

requirements.yml

imports:
  local:
    - path: ../sys-001
  git:
    - url: https://github.com/reqstool/reqstool-demo
      branch: main
      path: docs/reqstool

Filters

Filters can be applied in both requirements.yml and software_verification_cases.yml to include or exclude specific items.

requirements.yml

filters:
  sys-001:
    requirement_ids:
      includes:
        - REQ_sys001_103
        - ext-001:REQ_ext001_101

software_verification_cases.yml

filters:
  sys-001:
    svc_ids:
      includes:
        - SVC_sys001_101
        - SVC_sys001_109

Categories

A requirement is assigned to one or multiple categories.

requirements.yml

requirements:
  - id: REQ_ms001_101
    title: Title REQ_ms001_101
    significance: may
    description: Description REQ_ms001_101
    rationale: Rationale REQ_ms001_101
    categories: ["maintainability", "functional-suitability"]
    revision: 0.0.1

Categories follow the ISO 25010 Product Quality Characteristics.

ISO 25010 Product Quality Characteristics

Functional Suitability: Assesses the degree to which the software provides appropriate functions that meet specified needs under specified conditions.
Performance Efficiency: Evaluates the degree to which the software provides appropriate performance relative to the amount of resources used under specified conditions.
Compatibility: Assesses the degree to which the software can exchange information and work together with other systems, products, or environments.
Interaction Capability: Describes to which degree a product or system can be interacted with by specified users to exchange information.
Reliability: The degree to which the software performs specified functions under specified conditions without failure for a specified period of time.
Security: The degree to which the software protects information and data from unauthorized access, disclosure, alteration, or destruction.
Maintainability: Evaluates the degree to which the software can be modified effectively and efficiently without introducing defects or degrading performance.
Flexibility: Assesses the degree to which the software can be transferred from one environment to another, including the necessary adaptation effort.
Safety: The degree to which a product under defined conditions avoids a state in which human life, health, property, or the environment is endangered.

1	See manual_verification_results.yml example \| JSON Schema
2	See requirements.yml example \| JSON Schema
3	See reqstool_config.yml example \| JSON Schema
4	See software_verification_cases.yml example \| JSON Schema