Technical Note: Zephyr requirements tool requirements

ZEP-1

1. Multiple files / include mechanism

ZEP-1

Requirements or groups of requirements shall be distributable over several files and still form a full specification (document) via some kind of include mechanism.

SDOC-SSS-52

2.4. Assembling documents from fragments SDOC-SSS-52

The Requirements Tool shall allow composing documents from other documents or fragments.

NOTE: If a Requirements Tool implements stores documents in a file system, the composition can be arranged at a file level when a parent document file includes the child fragment files and produces a composite document.
- SDOC-SRS-109
  
  1.10. Composeable document SDOC-SRS-109
  
  StrictDoc's data model shall allow composing a Document from other Documents.
- SDOC-SRS-122
  
  2.9. Importable grammars SDOC-SRS-122
  
  StrictDoc shall support an inclusion of a grammar stored in a separate file.

ZEP-2

2. Clear separation of requirements (machine-readable)

ZEP-2

Requirements objects shall be clearly separated from each other, also when organized in the same file.

SDOC-SSS-54

12.3. Machine-readable format SDOC-SSS-54

The Requirement Tool's text language shall be machine-readable.
- SDOC-SRS-19
  
  2.6. Fixed grammar SDOC-SRS-19
  
  StrictDoc's markup language shall be based on a well-defined grammar.

ZEP-3

3. Custom fields

ZEP-3

Requiremements objects shall be configurable to create several types with a number of custom fields.

SDOC-SSS-62

3.3. Custom fields SDOC-SSS-62

The requirements tool shall support configuring a requirement item with an arbitrary set of fields.

NOTE: Examples of typical fields include: UID, Title, Statement, Rationale, Comment. Other fields that are used very often are: Status, Tags, Criticality level, Priority, etc.
- SDOC-SRS-100
  
  1.3. Requirement model fields SDOC-SRS-100
  
  StrictDoc's "Requirement" model shall support configurable fields system.
- SDOC-SRS-21
  
  2.8. Custom grammar / fields SDOC-SRS-21
  
  The SDoc markup shall support custom grammars.
- SDOC-SRS-56
  
  6.3.10. Edit Document grammar SDOC-SRS-56
  
  StrictDoc's screen shall allow editing a document's grammar.

ZEP-4

4. Links

ZEP-4

Linking shall in general be supported between any requirement object of any object type in a 1:n manner.

SDOC-SSS-7

3.8. Link requirements together SDOC-SSS-7

The Requirements Tool shall allow bi-directional linking of requirements nodes together using Parent or Child relations.
- SDOC-SRS-31
  
  1.11. Requirement relations SDOC-SRS-31
  
  The StrictDoc data model shall support connecting requirements using Parent and Child relations.
- SDOC-SRS-28
  
  4.1. Traceability index SDOC-SRS-28
  
  StrictDoc shall maintain a complete Traceability Index of all documentation- and requirements-related information available in a project tree.
- SDOC-SRS-159
  
  6.3.7. Create node relation SDOC-SRS-159
  
  StrictDoc's Document screen shall creating updating node relations.
- SDOC-SRS-158
  
  6.3.8. Update node relation SDOC-SRS-158
  
  StrictDoc's Document screen shall allow updating node relations.

ZEP-5

5. Multiple link roles

ZEP-5

Links shall be configurable to create multiple link roles.

SDOC-SSS-8

3.9. Multiple link roles SDOC-SSS-8

The Requirements Tool shall support the link roles.

Example of roles for a child-to-parent link: "verifies", "implements", "satisfies", etc.
- SDOC-SRS-101
  
  1.12. Requirement relation roles SDOC-SRS-101
  
  Each SDoc relation shall be optionally configurable with a relation role.
  
  NOTE: A relation role is a string value. Typical examples: "refines", "verifies", "implements".

ZEP-6

6. ReqIF export

ZEP-6

Requirements specification shall be exportable to ReqIF.

SDOC-SSS-58

6.2. ReqIF export/import SDOC-SSS-58

The Requirements Tool shall support exporting/importing requirements content from/to ReqIF format.
- SDOC-SRS-18
  
  1.1. Data model SDOC-SRS-18
  
  StrictDoc shall be based on a data model.
- SDOC-SRS-72
  
  8.2.1. Export/import from/to ReqIF SDOC-SRS-72
  
  StrictDoc shall support exporting/importing requirements content from/to ReqIF format.

ZEP-7

7. CSV

ZEP-7

Requirements specification shall be exportable to CSV.

SDOC-SSS-59

6.3. CSV export/import SDOC-SSS-59

The Requirements Tool shall support exporting/importing requirements content from/to CSV.

ZEP-8

8. Unique ID management

ZEP-8

Requirements objects shall allow unique ID management when adding new requirements on different branches.

Options could be:

UUID: no checking required, but not handy
Manually assigned: collision checking required
Centralized: when not affected by branching".

SDOC-SSS-6

3.7. Auto-provision of Requirement UIDs SDOC-SSS-6

The Requirements Tool shall provide controls for automatic generation of requirements UIDs.
- SDOC-SRS-96
  
  6.3.12. Auto-generate requirements UIDs SDOC-SRS-96
  
  StrictDoc's Document screen shall provide controls for automatic generation of requirements UIDs.
- SDOC-SRS-120
  
  6.3.13. Auto-completion for requirements UIDs SDOC-SRS-120
  
  StrictDoc's Document screen shall provide controls for automatic completion of requirements UIDs.
- SDOC-SRS-85
  
  9.2.1.1. Auto-generate requirements UIDs SDOC-SRS-85
  
  StrictDoc shall allow automatic generation of requirements UIDs.

ZEP-9

9. Text formatting capabilities

ZEP-9

The description field shall allow for formatting such as:

lists
tables
headings
UML diagrams
etc.

SDOC-SSS-63
2.7. Text formatting capabilities SDOC-SSS-63
The Requirements Tool shall provide "rich text" formatting capabilities which includes but not limited to:

Headings

Lists

Tables

UML diagrams

etc.
- SDOC-SRS-24
  
  2.11. Format-specific markup-to-HTML fragment writers SDOC-SRS-24
  
  StrictDoc shall render supported markup formats (at least RST and Markdown) to HTML fragments via dedicated format-specific writers selected by markup type.
- SDOC-SRS-27
  
  2.12. MathJAX SDOC-SRS-27
  
  StrictDoc's markup language shall support integration with MathJax.

ZEP-10

10. Minimal requirement field set

ZEP-10

A requirements object shall at least comprise the following fields (or similar):

title
ID
Description
Status
Outbound links
Inbound links (optional?)

SDOC-SSS-61
3.2. Minimal requirement field set SDOC-SSS-61
The Requirements Tool shall support at least the following requirement field set:

UID

STATUS

TITLE

STATEMENT

RATIONALE

COMMENT

RELATIONS (connections with other requirements).
- SDOC-SRS-132
  1.4. Requirement model default fields SDOC-SRS-132
  
  By default, the Requirement shall support the following fields:
  
  MID
  
  UID
  
  STATUS
  
  TITLE
  
  STATEMENT
  
  RATIONALE
  
  COMMENT.
- SDOC-SRS-93
  2.7. Default grammar fields SDOC-SRS-93
  
  The StrictDoc grammar shall have at least the following fields activated by default:
  
  UID
  
  STATUS
  
  TITLE
  
  STATEMENT
  
  RATIONALE
  
  COMMENT
  
  RELATIONS (references to other requirements)

ZEP-11

11. Requirements to source code traceability

ZEP-11

Linking from requirements objects to code or from code to requirements objects via ID shall be supported.

SDOC-SSS-72

5.1. Traceability between requirements and source code SDOC-SSS-72

The Requirements Tool shall support bi-directional tracing between requirements content and implementation source code with only minimal changes needed in the source code.

NOTE: The Requirements Tool does not necessarily have to implement the complete tracing process. It may delegate parts of the traceability task to other tools, e.g., Doxygen, Lobster, etc.
- SDOC-SRS-35
  
  6.10.1. Project source code coverage SDOC-SRS-35
  
  StrictDoc shall generate project source code coverage information.
  
  NOTE: Source code information can be visualized using both web or CLI interfaces.
- SDOC-SRS-36
  
  6.11.1. Single source file coverage SDOC-SRS-36
  
  StrictDoc shall generate single file traceability information.
- SDOC-SRS-33
  
  7.1. Link requirements with source files SDOC-SRS-33
  
  StrictDoc shall support bi-directional linking requirements with source files.
- SDOC-SRS-34
  
  7.6.1. Relation markers syntax SDOC-SRS-34
  
  StrictDoc shall support annotating source code with links that reference the requirements.
  - SDOC-LLR-164
    
    3.1.1. Auto-scoped relation markers in Rust docs SDOC-LLR-164
    
    If a StrictDoc relation marker is inside a Rust doc comment, the marker scope shall be set to exact the item the Rust language defines as target of the containing doc comment. The @relation(scope=...) parameter shall therefore be optional and shall be ignored if provided.
    
    1 /// @relation(REQ-1) 2 impl Foo { 3 4 /// @relation(REQ-2) 5 fn foo() { 6 } 7 }
    
    In the given example, the first marker shall link REQ-1 to the impl Foo implementation, highlighting lines 1 to 7. The second marker shall link REQ-2 to the fn foo() function, highlighting lines 4 to 6.
- SDOC-SRS-124
  
  7.6.2. Line marker SDOC-SRS-124
  
  StrictDoc's shall support line markers that can be attached to single source code lines.
  
  NOTE: A single-line marker points to a single line in a source file.
  - SDOC-LLR-171
    
    3.1.8. File, line and range markers SDOC-LLR-171
    
    StrictDoc shall point to lines and line ranges of Rust code by using file, line and range markers. These marker types shall be parsed from regular line and block comments.
    
    Note: File markers may also result from the inner doc comments of the top-level module.
- SDOC-SRS-137
  
  7.6.3. Language element marker SDOC-SRS-137
  
  StrictDoc shall support relation markers that can be attached to individual source code elements. StrictDoc shall support an optional scope attribute to disambiguate the target element where StrictDoc can't infer it solely from the marker position.
  
  Note: The most basic example of such traceable elements are functions and classes, but generally supported elements and available scope attributes depend on the programming language.
  - SDOC-LLR-164
    
    3.1.1. Auto-scoped relation markers in Rust docs SDOC-LLR-164
    
    If a StrictDoc relation marker is inside a Rust doc comment, the marker scope shall be set to exact the item the Rust language defines as target of the containing doc comment. The @relation(scope=...) parameter shall therefore be optional and shall be ignored if provided.
    
    1 /// @relation(REQ-1) 2 impl Foo { 3 4 /// @relation(REQ-2) 5 fn foo() { 6 } 7 }
    
    In the given example, the first marker shall link REQ-1 to the impl Foo implementation, highlighting lines 1 to 7. The second marker shall link REQ-2 to the fn foo() function, highlighting lines 4 to 6.
- SDOC-SRS-139
  
  7.6.4. File marker SDOC-SRS-139
  
  StrictDoc's shall support file markers that can be attached to entire source files.
  - SDOC-LLR-171
    
    3.1.8. File, line and range markers SDOC-LLR-171
    
    StrictDoc shall point to lines and line ranges of Rust code by using file, line and range markers. These marker types shall be parsed from regular line and block comments.
    
    Note: File markers may also result from the inner doc comments of the top-level module.
- SDOC-SRS-138
  
  7.6.5. Range marker SDOC-SRS-138
  
  StrictDoc shall support relation markers that can be attached to source code ranges.
  
  NOTE: Compared to other marker types, to indicate a range, two markers are needed: one to start a range and one to end a range.
  - SDOC-LLR-171
    
    3.1.8. File, line and range markers SDOC-LLR-171
    
    StrictDoc shall point to lines and line ranges of Rust code by using file, line and range markers. These marker types shall be parsed from regular line and block comments.
    
    Note: File markers may also result from the inner doc comments of the top-level module.

ZEP-12

12. Non-intrusive links in source code

ZEP-12

Linking from code to requirements objects via ID shall be least code intrusive.

SDOC-SSS-72

5.1. Traceability between requirements and source code SDOC-SSS-72

The Requirements Tool shall support bi-directional tracing between requirements content and implementation source code with only minimal changes needed in the source code.

NOTE: The Requirements Tool does not necessarily have to implement the complete tracing process. It may delegate parts of the traceability task to other tools, e.g., Doxygen, Lobster, etc.
- SDOC-SRS-35
  
  6.10.1. Project source code coverage SDOC-SRS-35
  
  StrictDoc shall generate project source code coverage information.
  
  NOTE: Source code information can be visualized using both web or CLI interfaces.
- SDOC-SRS-36
  
  6.11.1. Single source file coverage SDOC-SRS-36
  
  StrictDoc shall generate single file traceability information.
- SDOC-SRS-33
  
  7.1. Link requirements with source files SDOC-SRS-33
  
  StrictDoc shall support bi-directional linking requirements with source files.
- SDOC-SRS-34
  
  7.6.1. Relation markers syntax SDOC-SRS-34
  
  StrictDoc shall support annotating source code with links that reference the requirements.
  - SDOC-LLR-164
    
    3.1.1. Auto-scoped relation markers in Rust docs SDOC-LLR-164
    
    If a StrictDoc relation marker is inside a Rust doc comment, the marker scope shall be set to exact the item the Rust language defines as target of the containing doc comment. The @relation(scope=...) parameter shall therefore be optional and shall be ignored if provided.
    
    1 /// @relation(REQ-1) 2 impl Foo { 3 4 /// @relation(REQ-2) 5 fn foo() { 6 } 7 }
    
    In the given example, the first marker shall link REQ-1 to the impl Foo implementation, highlighting lines 1 to 7. The second marker shall link REQ-2 to the fn foo() function, highlighting lines 4 to 6.
- SDOC-SRS-124
  
  7.6.2. Line marker SDOC-SRS-124
  
  StrictDoc's shall support line markers that can be attached to single source code lines.
  
  NOTE: A single-line marker points to a single line in a source file.
  - SDOC-LLR-171
    
    3.1.8. File, line and range markers SDOC-LLR-171
    
    StrictDoc shall point to lines and line ranges of Rust code by using file, line and range markers. These marker types shall be parsed from regular line and block comments.
    
    Note: File markers may also result from the inner doc comments of the top-level module.
- SDOC-SRS-137
  
  7.6.3. Language element marker SDOC-SRS-137
  
  StrictDoc shall support relation markers that can be attached to individual source code elements. StrictDoc shall support an optional scope attribute to disambiguate the target element where StrictDoc can't infer it solely from the marker position.
  
  Note: The most basic example of such traceable elements are functions and classes, but generally supported elements and available scope attributes depend on the programming language.
  - SDOC-LLR-164
    
    3.1.1. Auto-scoped relation markers in Rust docs SDOC-LLR-164
    
    If a StrictDoc relation marker is inside a Rust doc comment, the marker scope shall be set to exact the item the Rust language defines as target of the containing doc comment. The @relation(scope=...) parameter shall therefore be optional and shall be ignored if provided.
    
    1 /// @relation(REQ-1) 2 impl Foo { 3 4 /// @relation(REQ-2) 5 fn foo() { 6 } 7 }
    
    In the given example, the first marker shall link REQ-1 to the impl Foo implementation, highlighting lines 1 to 7. The second marker shall link REQ-2 to the fn foo() function, highlighting lines 4 to 6.
- SDOC-SRS-139
  
  7.6.4. File marker SDOC-SRS-139
  
  StrictDoc's shall support file markers that can be attached to entire source files.
  - SDOC-LLR-171
    
    3.1.8. File, line and range markers SDOC-LLR-171
    
    StrictDoc shall point to lines and line ranges of Rust code by using file, line and range markers. These marker types shall be parsed from regular line and block comments.
    
    Note: File markers may also result from the inner doc comments of the top-level module.
- SDOC-SRS-138
  
  7.6.5. Range marker SDOC-SRS-138
  
  StrictDoc shall support relation markers that can be attached to source code ranges.
  
  NOTE: Compared to other marker types, to indicate a range, two markers are needed: one to start a range and one to end a range.
  - SDOC-LLR-171
    
    3.1.8. File, line and range markers SDOC-LLR-171
    
    StrictDoc shall point to lines and line ranges of Rust code by using file, line and range markers. These marker types shall be parsed from regular line and block comments.
    
    Note: File markers may also result from the inner doc comments of the top-level module.

ZEP-13

13. Structuring requirements in documents

ZEP-13

Requirements objects shall be structurable in a document like manner (with requirements ordering, and organized in chapters).

SDOC-SSS-64

3.4. Structuring requirements in documents SDOC-SSS-64

The Requirements Tool shall support structuring requirements in documents.
- SDOC-SRS-98
  
  1.5. Document model SDOC-SRS-98
  
  StrictDoc's data model shall support modeling documents.
- SDOC-SRS-105
  
  2.5. One document per one SDoc file SDOC-SRS-105
  
  StrictDoc's SDoc file shall represent content of a single document.

ZEP-14

14. Status field

ZEP-14

Each requirements object type shall have a configurable status workflow.

SDOC-SSS-61
3.2. Minimal requirement field set SDOC-SSS-61
The Requirements Tool shall support at least the following requirement field set:

UID

STATUS

TITLE

STATEMENT

RATIONALE

COMMENT

RELATIONS (connections with other requirements).
- SDOC-SRS-132
  1.4. Requirement model default fields SDOC-SRS-132
  
  By default, the Requirement shall support the following fields:
  
  MID
  
  UID
  
  STATUS
  
  TITLE
  
  STATEMENT
  
  RATIONALE
  
  COMMENT.
- SDOC-SRS-93
  2.7. Default grammar fields SDOC-SRS-93
  
  The StrictDoc grammar shall have at least the following fields activated by default:
  
  UID
  
  STATUS
  
  TITLE
  
  STATEMENT
  
  RATIONALE
  
  COMMENT
  
  RELATIONS (references to other requirements)

ZEP-15

15. Tool Qualifiability

ZEP-15

The Requirement Tool shall be qualifiable for use in safety-related and/or security-related development. At the very least, the Requirement Tool shall come with its own set of requirements, which shall be amenable to validation in compliance with the relevant standards.

SDOC-SSS-50

14.2. Self-hosted requirements SDOC-SSS-50

The Requirements Tool's requirements shall be developed and stored using the Requirements Tool itself.
- SDOC-SRS-91
  
  15.2.2. Self-hosted requirements SDOC-SRS-91
  
  StrictDoc's requirements shall be written using StrictDoc.