[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message]

Traceability of constraint from implementation to requirement

• From: "Costello, Roger L." <costello@m...>
• To: <xml-dev@l...>
• Date: Thu, 5 Jul 2007 17:17:05 -0400

Hi Folks,

Rick Jelliffe brought up an excellent point about the importance of
connecting an implementation to its requirement.  I have tried to
summarize Rick's message.  At the bottom I have a question.

IMPORTANCE OF TRACEABLE CONSTRAINTS

Traceability of constraints from implementation to requirement is very
important.

Traceability ensures that:
   - spurious constraints are not introduced, 
   - the successful implementation of requirements can be ascertained,
and 
   - requirements that have unworkable ramifications can be identified.


For a large system, a non-traceable constraint is a loose cannon.

EXAMPLE

Consider this XML instance document:
 
<?xml version="1.0"?>
<Document classification="secret">
    <Para classification="unclassified">
          One if by land, two if by sea;
    </Para>
</Document>

Suppose your requirements specify that this constraint must be
implemented:

Requirement: For an instance document to be valid the value of each
classification attribute must be one of these values:
  - top-secret
  - secret
  - confidential
  - unclassified

IMPLEMENTING TRACEABILITY IN XML SCHEMAS

Here is how to connect the implementation to its requirement:

    <attribute name="classification">
        <annotation >
          <appinfo source="http://www.eg.com/military/security.html">
             <my:requirement idref="A.1.3.4.5" />
          </appinfo>
          <documentation>
              The value of a classification must be one of top-secret,
              secret, confidential, or unclassified, because of MILSPEC
              XXXX (1999) section A.2.
          </documentation>
        </annotation>
        <simpleType>
            <enumeration value="top-secret" />
            <enumeration value="secret" />
            <enumeration value="confidential" />
            <enumeration value="unclassified" />
        </simpleType>
    </attribute>

Observe that the source attribute on <appinfo> identifies the
requirement document (security.html).  A foreign element
<my:requirement> has been introduced to identify the specific
requirement in the requirements document.
 
IMPLEMENTING TRACEABILITY IN SCHEMATRON

Here is how to connect the implementation to its requirement:

    <sch:pattern name="Classifications">
       <sch:rule context="*[@classification]">
          <sch:assert test="@classification='top-secret' or
                            @classification='secret' or
                            @classification='confidential' or
                            @classification='unclassified'"
                  my:requirement="A.1.2.3.4.5"
                  see="http://www.eg.com/military/security.html">
              The value of a classification must be one of top-secret,
              secret, confidential, or unclassified, because of MILSPEC
              XXXX (1999) section A.2.
          </sch:assert>
       </sch:rule>
    </sch:pattern>

The <assert> element has a 'see' attribute, which is used to give the
URL to the requirement document (security.html).  A foreign attribute
my:requirement has been introduced to identify the specific requirement
in the requirements document.

SUMMARY

1. It is important to show the connection between an implementation and
its requirement.

2. When using XML Schemas as your implementation language, use the
source attribute  on the <appinfo> element to provide the URL to the
requirements document, and create a foreign element to identify the
specific section being implemented.

3. When using Schematron as your implementation language, use the 'see'
attribute to provide the URL to the requirements document, and create a
foreign attribute to identify the specific section being implemented.

QUESTION

Why is a foreign element or attribute needed?  For example:

          <appinfo source="http://www.eg.com/military/security.html">
             <my:requirement idref="A.1.3.4.5" />
          </appinfo>

Why is the <my:requirement> element needed? Couldn't the specific
requirement be identified simply using a fragment identifier:

          <appinfo
source="http://www.eg.com/military/security.html#A.1.3.4.5" />

Likewise for Schematron:

                  my:requirement="A.1.2.3.4.5"
                  see="http://www.eg.com/military/security.html">

Why is the my:requirement attribute needed? Couldn't the specific
requirement be implemented simply using a fragment identifier:
                  
 
see="http://www.eg.com/military/security.html#A.1.3.4.5">

/Roger