Decide on unambiguous requirement identifiers

[morido]

The subset 026 (and possibly other subsets as well) comes with identifiers for each requirement (i.e. 3.8.5.1.2 is requirement of chapter 3 dealing with infill MAs). This works reasonably well as long as we are only dealing with pure textual requirements and no deeper nesting. However, this simple "addressing scheme" does not work anymore as soon as we lay out the term requirement in a little broader fashion and try to unambiguously address each artifact of the subset in a computer-compatible way.

Artifact may refer to: (the following list raises no claims to completeness)

1. a requirement as described above
2. a sub-requirement which comes with a non-numeric identifier (i.e. 3.8.5.1.a) or consists only of a bullet-point (i.e. the list in 3.8.5.3.2)
3. a row / cell in a table (i.e. Table 8)
4. a figure / parts of a figure (i.e. Figure 17)
5. an equation / parts of an equation (i.e. the second equation in 3.13.9.3.5.6)
6. possibly even individual words in any of the other artifacts named above.

Depending on the complexity of the resulting new identifier which takes care of all these cases, it may not necessarily be easy to handle for a human anymore. If so, a separate (simpler) identifier which perhaps only covers a few of the cases named above could be introduced.

Such a machine-readable unambiguous requirement identifier is absolutely crucial for proper traceability and integration with other (downstream) tools. I strongly encourage you to thoroughly discuss this topic asap and come up with a naming scheme upon which we can all develop our necessary interfaces. The people from ERTMS Solutions have already developed their own scheme for use within their ERTMS Formal Specs Workbench which covers parts of the list above. If necessary, they'll gladly provide this as an input.

[jastram]

I agree that unique identification is necessary. I'd like to add two more thoughts:

• We need to distinguish between human-readable and internal IDs (which may or may not be the same). In the case of the subset, it makes sense to align them.
• If an internal IDs being used, a UUID can be generated. In such a scenario, it is important to never change the ID, once created. This makes machine processing easy, predictable and safe.
• Another technique employed in practice is to give each artefact not just an ID, but a URI. Especially with human-readable IDs that is a good way to prevent name collisions (e.g. there may be two sections 3.5 in two different documents; you could distinguish them with the URIs word://file1.doc/3.5 and word://file2.doc/3.5
• For existing artefacts (specifically the subset), I think that it makes a lot of sense to reuse the work done by ERTMS Solutions.

[BerndHekele]

Regarding the SRS and for supporting traceability I do not see an alternative to using the identifiers coming with the subset. They are easily readable by any person involved in the process and reflect a good accuracy.

In addition, we need to be able to link other documents like openETCS requirement documentation.

I cannot see from the experience I have with EFS how this tool can do the job in the necessary quality. But, I'm open for a presentation and evaluation on the topic.

br Bernd

[UweSteinkeFromSiemens]

An appropriate format for self-defined requirements could be:

REQ#RequirementName#DEF# for the definition of requirements,

REQ#RequirementName#REF# for a reference to a requirement,

REQ#RequirementName#REAL# for a realization / implementation reference to a requirement

REQ#RequirementName#VER# for a verification reference to a requirement

and so on.

[jastram]

@UweSteinkeFromSiemens, what is the advantage of your notation, compared to the URI-notation, as described in https://github.com/openETCS/toolchain/issues/191#issuecomment-28279003 ?

[UweSteinkeFromSiemens]

The advantage is that a requirement can be identified unambiguously as a requirement and is not in danger to be confused with other artefacts coded as URI identifiers. And it allows the identifiers to be distributed in almost all kinds of file formats (source code, documents, test cases, test protocols, log files, ....) and detected as an - probably so far unknown requirement - with an automatized scan/grep.

But perhaps I misunderstood URI identifiers: Could you give an example, how to search for URI requirement identifiers by using a regular expression?

[jastram]

@UweSteinkeFromSiemens, I think you can achieve with URIs what you are trying to achieve, but in a slightly different way.

First, you propose specific formats not just for the requirement ID, but also for relationships: REF, REAL and VER are traces. Thereby, you're embedding semantic information in the identifier itself. Further, you also make it difficult to attach information to the traces.

An alternative approach is to introduce dedicated traceability elements, consisting of source, target and arbitrary metadata. The relationship type could then simply be part of the trace's metadata. How this could work in practice is described in this blog article for Crema, where also URIs are used for identifying source and target.

A URI identifies an element, not a relationship. For ProR requirements, a URI format could be:

reqif://RELATIVE_PATH_IN_PROJECT/TYPE/ID

... for identifying the element of TYPE type with the given ID, for instance:

reqif://subset26-3/SpecObject/3.3.1.5.7

You could even make the URI longer to access specific information. For instance,

reqif://subset26-3/SpecObject/3.3.1.5.7/status

would give you the value of the attribute "status", if there is such an attribute.

Could you give an example, how to search for URI requirement identifiers by using a regular expression?

In a simplified scenario, assume that we have a traceability table with three attributes, SOURCE, TARGET and TYPE. To find the traces for a given source, you would search for entries with the given source and type, while we could apply regular expressions to the target attribute. If we are looking for a ReqIF SpecObject, the regex could be:

reqif://.*/SpecObject/.*

This would exclude traces to Papyrus, for instance.

[UweSteinkeFromSiemens]

Sounds good. URI identifiers seem to be suitable.

[BerndHekele]

Is the URL notification compatible with Reqtify, Uwe?

[UweSteinkeFromSiemens]

@BerndHekele : If requirement identifiers are chosen as in the example above, yes. The identifiers must be able to filtered in a document by using regular expressions.

[BerndHekele]

This means we can conclude on the issue in documenting the rule in some guidance? I see D2.4 as a nice place to document this rule and will take care it is documented during the upcoming review?

[UweSteinkeFromSiemens]

2 * Yes.

[jastram]

@BerndHekele and @UweSteinkeFromSiemens - as IDs are relevant for traceability, I would like to encourage you to attend the ReqCylce presentation on Thursday, if you have time. I haven't seen you on the doodle: http://doodle.com/id5ns2d6vsi6hmns

If you can make it, please add you name.

[jastram]

At Development Sprint it was decided to close this, as the URI-based approach has been chosen.

[morido]

Very nice to have a decision here. Will there be a (formal) definition of the URI-structure any time soon?

[jastram]

@morido: Intuitively, I'd use URI fragments, which can be provided by EMF. Of course, this requires an Ecore model (which would allow us to conveniently document everything in one place). Maybe @JonasHelming has some additional insights, as he knows more about EMF than I do.