Building a Better BREX (Part 1)

What is BREX?

Introduction

This series of articles is intended for those working with S1000D data and are responsible in ensuring the data conforms to the business rules defined for your project. At a minimum, it is beneficial if you have a basic familiarity with S1000D and XML structures and terminology.

Disclaimer

I am the lead developer of IrisCheck, an S1000D data validation tool. The goal is to provide information that is beneficial to you regardless of what S1000D processing tools you choose to use. However, IrisCheck will be mentioned in this series to help illustrate concepts and/or provide examples of how BREX-based validation tools may operate.

What are Business Rules?

Business rules is a big deal when working with S1000D. Business rules are the decisions your make and/or adopt on how to implement S1000D for your project, where the specification itself identifies business rule decision points (BRDPs) to help you identify items to consider in establishing the business rules for your project. For example:

Business rule decision point BRDP-S1-00007 - Use of optional elements and attributes:

• Decide whether and how to use each optional element and attribute in its structural context.

This is just one of many, where you will likely define additional business rules not called out explicitly in the specification. Chapter 2.5.3, Para 2 of the S1000D specification enumerates all the BRDPs defined. Once you get over the initial shock of how many there are, you will realize that initial decisions you make will eliminate the need to address other BRDPs: You only need to focus on those that are relevant to your project.

What is BREX?

Chapter 4.10.2 of the S1000D specification defines the business rules exchange (BREX) data module as follows:

The data module provides a means to represent adopted business rules in a formal way that enables unambiguous automatic processing of the rules. Such processing includes, without being restricted to, verification that the XML objects in the CSDB fulfill the requirements expressed in the business rules.

The key phrase of that paragraph is, “automatic processing”. It is not uncommon for S1000D-based projects to contain hundreds, if not thousands, of data modules, making manual verification of them a costly exercise. The BREX data module provides a language for codifying your project rules, allowing the automatic validation of your data modules with a BREX checker. Of course, not all of your business rules can be encoded into your BREX, but for the ones you can, you eliminate the need to manually verify them.

Normally, discussions involving BREX focuses on its ability to support automated validation, but a BREX data module is comprised of 3 components:

• Context Rules:

  • Rules defined in a formal matter to facilitate automated verification.

  • Schema/XML-based.

  • Uses XPath (which we will cover later).

• Non-context Rules:

  • Rules independent of XML structure and/our outside the scope of a single data module.

• SNS Rules:

  • Contains descriptions of one or several SNS systems that apply to your project.

This series of articles focus on the context rules component of the BREX, and within the scope of this series, when the term “rule” is used, it is synonymous to “context rule” unless explicitly specified otherwise.

Aren’t the Schemas Enough?

No. The S1000D XML schemas define the basic structures all data modules must conform to. Although XML schemas are quite powerful in defining what is, and is not, allowed in XML documents, within the scope of S1000D, they have the following limitations:

• S1000D defines rules where the rules for a specific XML structure is conditional on data specified in another part of the document. For example, take the following rule:

  Data modules up to and including the initial issue of the approved release must have the attribute issueNumber set to the value 000 for inwork versions or value 001 for the initial issue and have the attribute issueType set to the value /new/. (Chap 3.9.5.1, Para 2.2)

  The XML schema language does not provide a way to express and enforce this rule. This is just one of many rules that cannot be codified in the schemas. When you download the S1000D specification and schema package from s1000d.org, the default BREX is included that encapsulates such rules.

• S1000D is designed to be tailorable, where you can choose to impose additional restrictions on your data that the schema allows. Since it is common practice that S1000D schemas are “set in stone” by contract, where modifying the schemas directly to enforce your rules is prohibited (you do not exchange schema files when exchanging data with other parties). The BREX provides a mechanism to customize the rules on a per-contract basis, but with the limitation that such customizations cannot allow structures the schemas explicitly prohibit.

BREX Limitations

Although much can be achieved with BREX context rules, it is important to be aware of its limitations so you will know which project rules can and cannot be codified in a BREX data module to support automated validation.

The scope of BREX context rules is limited to a single-document. Rules that require access to multiple data modules, and any other information external to a module’s XML document structure, cannot be represented by BREX context rules (but can at least be documented as non-context rules).

Examples of the types of checks a BREX cannot support:

• Applicability product and condition references.

• CIR references.

• CSN references.

• Data module references.

• Media references.

• etc…

Now what?

In Part 2, we will the cover the basic XML markup for writing context rules, and provide an introduction to XPath, the expression language used in writing context rules.