What the BREX checks,
and what it cannot.

What are S1000D business rules?

S1000D is deliberately open. It offers more elements, attributes and options than any single project needs, and it leaves the choice to the people who use it. Business rules record those choices: which issue of the specification applies, which parts of the schema are used, which values an attribute may take, how the product is broken down into systems, how a warning is worded.

The specification lists the questions a project has to answer, its business rules decision points. Issue 4.1 alone has over 550 of them. A project works through them once, at the start, and writes down the answers.

What is a BREX data module?

The rules that a machine can check go into a data module of their own: the business rules exchange module, the BREX. It is written in the same XML as every other module, carries information code 022 and has existed since Issue 2.2.

Every data module names the BREX it has to follow. In the words of PTC’s documentation, “The association of a BREX to a data module is mandatory in S1000D.” Even without a project BREX, a module refers to the default BREX of its issue. A validation tool reads that BREX and checks the module against it.

What does a BREX rule look like?

A rule points at a place in the XML of a data module with an XPath expression, says whether that place may exist, and can list the values allowed there. This one, written the way the default BREX writes its rules, allows two security classifications and no others:

<structureObjectRule>
  <objectPath allowedObjectFlag="2">//@securityClassification</objectPath>
  <objectUse>Only classifications 01 and 02 are used.</objectUse>
  <objectValue valueForm="single" valueAllowed="01"/>
  <objectValue valueForm="single" valueAllowed="02"/>
</structureObjectRule>

The flag sets the verdict, as PTC’s documentation lists it: 0, the object is not allowed. 1, it must be included. 2, it is optional. Where values are listed, the object must take one of them. Besides these structure rules, a BREX can hold rules for the standard numbering system and for notations, and rules in plain words that no machine checks.

How do BREX modules build on each other?

Business rules come in layers. The business rules of the Defense Interest Group, published in 2017 for Issue 4.1, put it in one line: “A layered BREX data module structure shall be applied.” Their layers run from S1000D itself through the group’s rules to national, military and project rules. Each BREX refers to the one above it, so a module checked against the project BREX can be checked against the whole chain.

Customers write this into their contracts. Sweden’s FMV requires every delivery to “refer to the agreed (chain of) BREX”, one of which must be its own general BREX. The US Department of Defense has a data item description for the project BREX file, DI-TMSS-81952, so the BREX can be ordered as a deliverable in its own right. Australia’s Defence publishes its BREX for Issue 5.0.

What a BREX check catches

• Elements and attributes the project does not use.
• Attribute values outside the allowed list, such as a security classification the project does not know.
• System codes that do not exist in the project’s breakdown of the product.
• Warnings and cautions that do not follow the agreed structure.
• Information the project requires but the schema leaves optional, such as an applicability statement.

Free and commercial tools run the check, and some CSDBs have one built in:

What a BREX check cannot catch

A BREX checks form. It cannot tell whether a torque value is right, whether a step is missing or whether the steps are in the right order. A module can pass every rule and still send a technician the wrong way.

It also sees one module at a time. Earl Hood, lead developer of the IrisCheck validator, puts it plainly: “The scope of BREX context rules is limited to a single data module.” Whether a reference to another module, to a common information repository or to an illustration resolves, and whether applicability holds across modules, is beyond its reach. That is why the open-source s1kd-tools ship separate checkers for applicability and for references to common information repositories.

And some rules cannot be written as paths at all: how clearly a step is worded, whether the right figure is used. These stay in the business rules document and on the reviewer’s checklist.

A rule that matches nothing never fails

A BREX rule reports an error only when its path finds something that should not be there, or misses something that should. A path with a mistake in it finds nothing, so the rule passes every module, silently.

The specification’s own default BREX shows how easily this happens. Rule BREX-S1-00032 says that a published module with change marks must be flagged as changed. In the default BREX of Issues 4.1, 4.2, 5.0 and 6, its path looked for an attribute called inwork. The attribute is inWork, and XPath is case-sensitive. We ran both versions of the rule against a published module with change marks and the wrong flag. The Issue 6 rule found nothing. The Issue 7 rule, with the spelling corrected, found the error.

Tools can fail silently too. s1kd-brexcheck, for example, skips a rule whose XPath is invalid and prints a warning. A BREX that passes has not necessarily run all its rules.

Schema, BREX and review: three checks

A module needs all three. The first two are cheap and can run on every save. The third is expensive, so everything that can be checked by machine should be, before a person spends time on it.

How to write business rules that hold

1. Decide before the first module is written. Every rule changed later means reworking modules already done.
2. Start from the customer’s BREX if there is one, and from the default BREX of your issue.
3. Keep the rules few and specific. A rule nobody can check is a wish.
4. Test every rule with a module that breaks it. A rule that never fails may not be working.
5. Run the BREX on real modules of every type before the project depends on it.
6. Version the BREX like code, and record why each rule exists.

Where Tracium fits

Tracium checks every draft against S1000D and your business rules, so a module reaches its reviewer already valid in form. And because every step links to the page of the supplier manual it came from, the third check, the one no BREX can do, becomes a comparison with the source instead of a search for it.