Links between requirement artifacts

Technical papers on complex systems – and the Subset-026 makes a particularly striking ex-

ample here – tend to show a high degree of cohesion, while their degree of contiguity is much

lower. So concepts are often intertwined (cohesion) but their individual parts are spread across

a wide range of pages (little contiguity). Although this is certainly not a favorable text property,

it can hardly be avoided in all cases, especially if the respective document stays on an abstract

level, where intentionally only few interfaces, packages or other means of functional grouping

are present. They would indeed predetermine a certain way of implementation which is not de-

sired in these early stages of the systems development life cycle (SDLC).

For the Subset-026 this situation led to a specification sprinkled with all sorts of references to

tie its otherwise unrelated blocks of information together. Structurally speaking, those refer-

ences can be grouped as follows:

1. Cross-references: Any kind of in-text mention of another named part of the document.

(a) Explicitly set through Microsoft Word: This is a cross-reference explicitly created by

the author of the input DOC31_{. Microsoft Word stores both source and target in a}

standardized way so they can be automatically extracted by the tool. ProR renders

this kind of reference as shown in Table 3 on page 49.

EXAMPLES:

refer to chapter4.7“DMI depending on modes”).

Source: 4.4.9.1.6

described inTable 1

Source: 3.5.7.5

8

Source: 7.4.2.0[2].[t]*.[r][4].Length

(b) Fully-qualified implicit reference: A simple in-text mention of a some other entity. The

tool employs heuristic approaches to identify and normalize such mentions.

EXAMPLES:

according to3.6.2.2.2c

Source: 3.4.2.3.3.8.1

according to3.5.3.4 f).

Source: 3.5.4.3.1

see itemsb),c),d),e) in3.5.3.4

Source: 3.5.7.3.a

(see3.18.3.2itemsb)c) andd))

Source: 3.13.2.2.1.2

Concerninga) andb) of clause3.16.2.5.1

Source: 3.16.2.5.1.1

(c) Unambiguous implicit reference: This is conceptually similar to the case above, ex-

cept the mention does not use the numberText of a list but some other unambigu-

ously resolvable numbering scheme.

EXAMPLES:

(seeFigure 25a)

Source: 3.9.3.12.2

referring tofigure 22c

Source: 3.8.3.4.1

(d) relative reference: A possibly ambiguous reference to some preceding or following

entity. Currently, the tool only features rudimentary support for the handling of the

former case.

EXAMPLES:

Exception toa):

Source: 3.6.2.2.2.1

Regardingc):

Source: 3.6.2.2.2.3

2. Recurring phrases: Any kind of in-text mention of a phrase which has been previously

used elsewhere.

At the moment, the tool does not feature any generic algorithm to detect such phrases,

but focuses only on those whose first mention is enclosed in quotation marks – or typo-

graphically questionable variations thereof (see Section 4 for a more generic approach). If

such a phrase, which must consist of at least two words to reduce false-positives, is found

again somewhere later in the document, a reference to the first mention will be gener-

ated. Thus, for better illustration the following examples feature possible targets (i.e. first

mentions) of references instead of their sources as in all the cases above.

EXAMPLES:

"Linking information is used" shall be interpreted

Source: 3.4.4.2.1.1

requirements for “Start of Mission” procedure

Source: 5.4.3

the information "default balise/loop/RIU information".

Source: 3.16.2.4.8

For the very last case the tool saves all possible interpretations as potential reference tar-

gets. That is:

• default balise/loop/RIU

information

• default loop information

• default balise information

• default RIU information

In ReqIF all these references are turned into so-called SpecRelations (Section 2.1.3) with all

cases below item 1 of the above list having the type CrossRefLink attributed and cases belong-

ing to item 2 being typed as KnownTermLink.

Such a SpecRelation always has exactly one source and one target, both of which must be ex-

isting artifacts within the current file. For the examples above this means the respective arti-

facts need to be resolved or created. Resolving depends heavily on the granularity used while

creating the artifacts. If, for instance, a certain cell within a table has been configured as super-

fluous by a table matcher (Section 2.3.1), but is nonetheless targeted by a reference, a fallback

to the parent (in this case: row-) artifact must take place. Artifact creation is necessary if an en-

tity outside the scope of the current document is referenced, as it is sometimes the case for

item 1b. This is achieved by writing an artificial proxy SpecObject of a special type called Proxy

Type, with only an identifier but no further content, into the ReqIF and then referencing this in

the same way as any other ordinary SpecObject. Since the detection algorithm behind item 1b

still has flaws, it does sometimes create false-positive references (see the jUnit test cases in

docreader.range.paragraph.characterRun.FakeFieldHandlerTest for examples). These are

particularly disturbing for statistical postprocessing as outlined in Section 2.2.1. Appendix A.1.1

shows how to manually correct such mistakes.

Entirely ruling out these false-positives is quite challenging because there is no way to verify if

a target represented by a proxy actually does exist somewhere in an external file. Matters are

further complicated by inaccurate mentions of external, unnumbered tables, consisting only of

a reference to the immediately preceding numberText, whose associated paragraph may poten-

tially encompass more than one table. The latter frequently happens in the headings of chapter

6 of Subset-026.

Some references such as those involving images or OLE-objects currently cannot be processed

at all (see for instance the references in 5.11.2.2[2].[t]* targeting the image in 5.11.3.1[2].[f]8).

By design, a SpecRelation always applies to an entire SpecObject (read: artifact). Combined

with the philosophy of the tool to only turn each paragraph into such an artifact (Section 2.3),

those relations therefore often become less granular than they were in the input DOC. In other

words: A few characters of an artifact A which constitute the source of a relation to an artifact

B cannot be directly linked to B. Instead, only artifact A in its entirety can take the role of the

source.

This weakness could be mitigated by either creating a single artifact for all those “few charac-

ters” which make up a link, thereby effectively equalling out the granularities of an in-text men-

tion and a SpecObject. Or by creating a proprietary ReqIF-extension that attributes metadata

to each SpecRelation. However, this data can at most convey the position of the “few charac-

ters” within the respective artifact and would thus need a compatible renderer to make use of

it. In practise, neither of those two approaches was followed as the current situation seldom

leads to ambiguities, especially because the phrases of item 2 are also annotated within the

implementerEnhanced-field (green [Linked_Phrase]-box of Table 4 on page 50). For a truly for-

malized specification this may be too weak, though.

If the same artifact B is referenced multiple times from within A, as it is the case for the first

example in item 1a, only one SpecRelation will be created.

A second property of SpecRelations which can be viewed both as a bug and a feature is the

fact that they are not necessarily “clickable”. See the right column entitled Link in Figure 11 on

page 47 for how ProR renders such relations in its grid. One might expect that a click on any

of the artifacts (targets) mentioned in this column will cause the grid to scroll to the respective

position of that artifact. However, since SpecObjects which act as those targets may be instan-

tiated multiple times even within the same specification (Section 3.2.1), it is not always clear

where to scroll to. This becomes particularly apparent if views as suggested in Section 3.2 are

employed.

The multiple specifications that come with views, however, offer one more treat of the ReqIF

file format: SpecRelationGroups can be used to clump SpecRelations by the different specifi-

cations they connect [Obj13, Fig. 10.7]. For instance, after creating one view for all trackside

requirements and another one for all those which belong to the train, such a group could be

utilised to tag relations that define interfaces between the two.

Figure 5 on page 26, which has been previously discussed in Section 2.2.1, shows a graphical

representation of the roughly 400 relations of type CrossRefLink (as well as the ordinary hier-

archical connections) within chapter 3 of Subset-026. The 90 KnownTermLink-relations of this

chapter have been omitted.

In document On the domain-specific formalization of requirement specifications - a case study of ETCS (Page 54-57)