How to combine/mixin groups of requirements?

[BenGardiner]

We are working on a large set of requirements for several types of component. The types share some requirements but not all requirements.

An abstract example: there is a set of requirements for components with features A, B, C. The components types mix these features in different ways; component type 1 uses features A+B+C , type 2: features A+B, type 3: features A+C, etc. The requirements development team seeks to capture specifications for each component type; how to best model the requirements to avoid duplication and create complete specs for each component type?

More concrete examples: we are evaluating using strictdoc for vehicle cybersecurity requirements specification by fleets to their OEMs during procurement. Some work product of this evaluation can be found here https://github.com/nmfta-repo/vcr-experiment . Examples of where we think we will need to combine/mixin groups of requirements there is:

• There are vehicle components (modules) that connect to multiple network segments. These modules will need to satisfy 'gateway device' (WIP name) security requirements in addition to other requirements based on their module features
• There are groups of security requirements which apply to the organization developing the module (e.g. SDLC requirements); we would like these captured once, repeated in module requirements and communicated to the OEM as 'organization requirements' (WIP name) when shared by the fleet to reduce duplicated effort at the OEM

[stanislaw]

Hi @BenGardiner,

I was too busy at my day job, so I could not get to answer all the questions, including this one.

Currently, what you are asking is not supported by StrictDoc. I see three options of how this could be done:

1. The reused parts could be standalone documents. Instead of implementing anything in StrictDoc, you could consider extracting your shared parts into dedicated standalone documents and by doing that make your module requirements documents referenced those standalone documents as applicable documents. This approach could be the cleanest in terms of how you would manage the boundaries between the documents. I guess you have considered this option and decided that this approach would not work for you because your shared fragments do not justify themselves as being standalone documents so let's consider options 2 and 3.

2. New feature: An SDoc document imports a SECTION subtree content from another file. This feature is relatively easy implement. In the parent document, we could have something like this:

[DOCUMENT]
TITLE: Parent document

[INCLUDE_SECTION_FROM_FILE]
FILE: file_with_shared_part.sdoc
MAYBE_OTHER_OPTION: ...

When parsing the parent SDoc file, StrictDoc would recognize the link to the included file and simply inject the content of that file to become a section in the parent document.

3. The option 3 is the same but instead of importing a SECTION, the imported file would be a standalone document starting with [DOCUMENT] and not with [SECTION] like in option 2. When importing that document, StrictDoc would transform the child document into a section in the parent tree.

The options 2 and 3 are similar, the difference is in whether the child document would start with [DOCUMENT] and could therefore also work as a standalone document or the child document file would only be a partial SDoc document starting with [SECTION].

Let me know what you think.

Also note, that there is another idea which is similar but different to what you are asking: #601.

[BenGardiner]

hi @stanislaw , thanks for taking the time to put together a thoughtful reply.

The reused parts could be standalone documents. Instead of implementing anything in StrictDoc, you could consider extracting your shared parts into dedicated standalone documents and by doing that make your module requirements documents referenced those standalone documents as applicable documents.

I think I understand this option: we could create non-strictdoc module requirements documents that are lists of strictdoc documents.

I guess you have considered this option and decided that this approach would not work for you because your shared fragments do not justify themselves as being standalone documents

Yes and no. I don't think we've exhausted all options and so I appreciate you offering this approach.

It does seem that this approach leaves strictdoc behind at the point where the re-used requirements are aggregated. Which is maybe ok. Another factor here is we would like to produce questionnaires from the aggregated requirements. The processing to questionnaire could be via reqif or something else after the strictdocs are aggregated; that could work...

We were initially thinking the questionnaires could be another output type of strictdoc and we could add this as a PR, plugin, or whatever suited the project best. That path seems to lend itself better to the include features (options 2 and 3). Between the two I think [SECTION] type is a better fit since we wouldn't want to render the re-usable requirements on their own.

Also note, that there is another idea which is similar but different to what you are asking: #601.

Ah yes I can kinda see what you're getting at. We also want to be able to reuse and export groupings of requirements... interesting.

Definitely a lot to think about here.

[BenGardiner]

I tried approach 2) in PR #629 -- let me know you think

[BenGardiner]

Having implemented the includes and putting together a converter from the large set of telematics requirements into multiple sdoc files https://github.com/nmfta-repo/nmfta-vehicle_cybersecurity_requirements/blob/718f1ab6917f6bef804b5f18b402f20864a16e55/scripts/import-tsrm.py we have run into a UID uniqueness problem during traceability. error: DocumentIndex: two nodes with the same UID exist in two different documents: AC-010 in "NMFTA Telematics (Connectivity or Communications Component) Security Requirements Matrix" and "NMFTA Telematics (Cloud Component) Security Requirements Matrix".

Is de-duplication going to be necessary now that there are file includes? Should there be a UID prefix? Was this the wrong approach and tags would have been better?

[stanislaw]

Again, your case with fragments is quite special. Usually, you do want to make sure that all requirements have a unique UID because otherwise the calculation of a traceability index is broken and you will get undefined behavior when looking at the traceability pages.

We could disable this validation with a command-line argument, but then you still have to think about the inconsistent graph 😢

[BenGardiner]

The working group discussed this in our meeting today. We think we have a solution -- it may not actually involve includes/fragments at all... ¯_(ツ)_/¯

Each component will have its own document with its own unique IDs. These component requirements are 'stubs' that will refer up to more detailed but shared parent requirements.

I'll get this implemented and to confirm and then come back here. You may wish to back-out the includes feature because -- unless special steps are taken to process the requirements -- it will always lead to duplicate UIDs.