Standard Files and Directory Sets

file: reqstool_config.yml

Contains file and directory configuration used by reqstool.

The layout of files and directories for a project depends on the language and build tool. The table below shows the default paths that reqstool uses when only language and build are specified:

Language Build Tool Static files (requirements, SVCs, MVRs) Dynamic files (annotations, test results)

Java

Maven

./reqstool/

../../target/ (relative to static files)

Java

Gradle

./reqstool/

../../build/ (relative to static files)

Python

Hatch

docs/reqstool/

../../build/ (relative to static files)

Python

Poetry

docs/reqstool/

../../build/ (relative to static files)

These defaults are applied by the build plugins. They are configurable — see each plugin’s documentation for details.

If no reqstool_config.yml file is present, reqstool will expect all files and folders (including dynamic ones) to reside in the path provided to the -p argument. This works well with a Maven zip artifact or PyPI package.

A minimal reqstool_config.yml only needs to specify language and build tool:

# yaml-language-server: $schema=https://raw.githubusercontent.com/reqstool/reqstool-client/main/src/reqstool/resources/schemas/v1/reqstool_config.schema.json

language: java
build: maven

Below is an example with custom paths. Paths are relative to the -p argument provided when reqstool is run:

# yaml-language-server: $schema=https://raw.githubusercontent.com/reqstool/reqstool-client/main/src/reqstool/resources/schemas/v1/reqstool_config.schema.json

language: java
build: maven
resources:
  requirements: ../../target/some_folder/requirements.yml
  software_verification_cases: ../../target/some_folder/software_verification_cases.yml
  manual_verification_results: ../../target/some_folder/manual_verification_results.yml
  annotations: ../../target/reqstool/annotations.yml
  test_results:
    - ../../target/**/*.xml

file: requirements.yml

Contains all the requirements.

Below is an example of a requirements.yml file:

metadata:
  urn: ms-101
  variant: microservice
  title: Some Microservice Requirement Title
  url: https://url.example.com

requirements:
  - id: REQ_101
    title: Title REQ_101
    significance: may
    description: Requirement with automated test and should have no implementation
    rationale: Rationale REQ_001
    categories: ["maintainability", "functional-suitability"]
    implementation: N/A
    lifecycle:
      state: obsolete
      reason: Superseded by REQ_102
    revision: 0.0.1

The metadata section is required to describe the application.

In the requirements section, an array of requirements can be specified.

Required fields

  • id — Must be unique within the project.

  • title — A title of the requirement.

  • significance — Could be shall, should, or may.

  • description — Short text to describe the requirement.

  • categories — Which categories the requirement relates to.

  • revision — In which version the requirement was introduced.

Optional fields

  • rationale — Why this requirement is important.

  • implementation — If this requirement requires a source code implementation or not. Acceptable values: in-code or N/A. Defaults to in-code if omitted.

  • lifecycle — Provides four options: draft, effective, obsolete, deprecated. Defaults to effective if omitted. If set to obsolete or deprecated, reqstool will issue a warning during parsing when referenced in code or by other requirements, SVCs, or MVRs.

file: software_verification_cases.yml

Contains information about how specific requirements should be verified.

One of the fields to be set on a software verification case is the verification type which can be selected from five pre-defined values: automated-test, manual-test, review, platform, other.

All but automated-test expect at least one manual verification entry for that particular software verification case. The automated-test value expects at least one automated test to exist and preferably pass.

file: manual_verification_results.yml

Contains information and the result of a manual verification case.

file: requirement_annotations.yml

Typically generated by an annotations parser and lists all requirement annotations.

file: svcs_annotations.yml

Typically generated by an annotations parser and lists all software verification cases annotations.

file: annotations.yml

Lists all annotations, containing both requirements and software verification cases annotations.

Generated by default by the Python decorators parser. For Java projects, the Maven and Gradle plugins combine requirements_annotations.yml and svcs_annotations.yml into this file.