Let’s Talk About BREX

In this post, our Business Rules (BR) trainer Victoria Ichizli-Bartels will address the mystery of BREX (Business Rules EXchange), and why this S1000D concept and data module is as helpful and widely used as it is.

BREX has nothing to do with Brexit and neither with a song, which only after one little change would sound like that:

“Let’s talk about BREX, baby
Let’s talk about you and me
Let’s talk about all the good things
And the bad things that may be
Let’s talk about BREX
Let’s talk about BREX (a little bit, a little bit)
Let’s talk about BREX
Let’s talk about BREX.”
(Original from Salt-N-Pepa)

So let’s talk about it and whether there is any good or bad in it.

BREX stands for Business Rules Exchange, and S1000D defines the concept in the following way:

“The S1000D concept for exchange of the business rules adopted by a project or an organization implementing the specification. The BREX data module provides a structure for standardized formal exchange and unambiguous definition of such rules.” (S1000D Issue 4.2, Chap 9.2.1)

Many who research this topic within the Specification (e.g., in Chap 4.10.2 and Chap 4.10.3 in S1000D Issue 4.2) would find out that BREX data module has a fairly simple structure, in the central part of which the business rules decisions are tied up to various elements and attributes, or non-context items.

For example, there are 100 values allowed for each configurable attribute defined by S1000D, and inside a BREX data module you can narrow down the permitted values only to five of those, for example. You can also — as often allowed by the Specification — give project or organization specific interpretation of those values.

The simplest way to understand what BREX does when applied, in my opinion, is the following. It adds the third level of validation after the request an XML document to be well-formed, and also valid to the Schema.

A BREX data module allows verifying technical documentation data modules to be — at least to some extent — checked against the project or organizational business rules.

Besides that, you can also document the Standard Numbering System (SNS) breakdown for your product, both the codes and their meanings.

So the above sounds more like a good thing. There is another good thing. You can layer BREX data modules, just like you can layer business rules.
A business rules layer is:

“A level of stakeholders within the hierarchy to which the business rules apply.” (S1000D Issue 4.2, Chap 9.2.1)

For example, you will always have common business rules (even if sometimes not many) across your organization for all projects, as specific practices with graphics and illustrations, your company’s logo and corresponding identification codes. So those business rules decisions would be on the organization layer of the business rules and BREX. More specific project business rules would be on a lower or, in other words, more narrow layer of the business rules and BREX. That is on the project level.

The top level is the S1000D level of decisions. Since Issue 4.2, those are visibly indicated within the specification. See, for example, the definition of the value “rinstate-status” for the attribute issueType:

”rinstate-status” – data modules that have been reinstated from a previously deleted data module and have only the status information changed must have the attribute issueType set to the value ”rinstate-status”. In the simplest case, this status change must require setting the attribute issueType to the value ‘rinstate-status’. Refer to default BREX rule BREX-S1-00034.” (S1000D Issue 4.2, Chap, Para 2.2)

These S1000D “default” rules are recorded and maintained in the Default BREX Data Module. All customized BREX data modules (project or organization specific) must always (either directly or indirectly) refer to and adhere to the default BREX data module. This adherence could also be interpreted in the following words: the rules specified in a project or organization business rules must never override those defined in the Specification and default BREX data module.

For example the following project business rule decision will never be allowed,

“Every change in this project’s data modules must be change marked.”

And the reason for the incorrectness of that rule would be the default BREX rule saying that,

“Editorial changes must not use change markup. Refer to default BREX rule BREX-S1-00044.” (S1000D Issue 4.2, Chap, Para 2.1.1)

It is beneficial that you don’t have to copy the organizational BREX data module and customize it for your project. You simply need to identify the specificity of the certain decisions for your project and record them in a separate BREX data module. That one will be your project BREX data module and will have to refer to the organizational BREX data module. That is the BREX data module for next upper layer of the business rules.

At the same time, such layering is also a “bad” thing (if we use the wording of the quoted song above). Not exactly bad, but surely one adding complexity to BREX implementation.

When the BREX layering is applied, your technical publication data modules undergo not only three levels of validation, but at least four and often at least five:

  1. Well-formed-ness
  2. Adherence to the XML Schema
  3. Validation against default BREX data module
  4. Conformance with the organizational business rules and BREX data module capturing the bulk of them.
  5. Agreement with the more specific business rules and BREX data module of a project.

And that chain could go further if you have more than two layers in your business rules structure. There could be sub-project BREX, or there could be some international or national business rules layer placed between the S1000D and organizational (company) layer.

The challenge also comes when you try to implement such a layered structure into the quality assurance processes inside an S1000D software application. The originators of the BREX concept and the Steering Committee made sure to provide suggestions, and guidance how to do that in the Chap 7.9 of the Specification.

But I suspect that each system still approaches it very differently and you have to make sure that you know the system you purchased very well in this respect so that you produce your BREX data modules correspondingly. For example, the managers of your program might decide to use the layered BREX model, but the system you use would allow only two BREX data modules to be checked against, the default BREX and the customized one. It means that you would need to update the BREX data module you get from the main contractor and adjust it with your decisions. And you will need to make sure that the issuing authority approves your changes. Otherwise, you might be in trouble when you deliver your technical publication data modules verified against erroneous recordings of the business rules.

The layering is probably the only minus (but also a plus) point of the BREX.

Some might say that it is not possible to include illustrations and guidance for each of the business rules decisions to create guidance documents and similar. But now, brDoc Schema overtook this role. Even if authoring guides are sometimes exchanged between the partners in the project (and those could be exchanged by using brDoc data module), BREX is about exchanging those business rules decisions which are used for automatic verification of the technical data quality against the project and organization business rules. So I wouldn’t consider that as something negative.Whether brDoc and BREX Schemas will ever merge, no one can say it at the moment. They could, but that would mean change in practices. And the fact is, the process for the BREX use are more or less established. But this is not the case for the brDoc Schema, which appeared first in Issue 4.2. Time will show how this develops. For more thoughts on this topic, refer to the article titled Understanding the Business Rules Document (brDoc) Schema.

View all bitesize business rules

Looking to learn more about Business Rules in the world of S1000D?

Book your place on our S1000D Business Rules training course delivered by Victoria Ichizli-Bartels.

This course is for anyone who needs an understanding of the principles of S1000D prior to implementing the standard.  It covers the technical and business aspects of Business Rules and how to implement it and its implications for technical publications. Find out more.

About Victoria Ichizli-Bartels

Victoria has been working with S1000D since 2004, first for German Defence, then for a major S1000D software vendor and today as part of her own business. In the S1000D community, Victoria serves as the Business Rules Working Group (BRWG) chair since 2005.

To book your place call +44 (0)20 8722 8400 or email