BREX, the developer’s big brother

Introduction

S1000D provides a unique eXtensible Markup Language (XML) data module called a Business Rules EXchange or BREX. The BREX was first introduced in Issue 2.2.

 

What is a BREX?

A BREX is used as a means of sharing the agreed business rules among project stakeholders. An added benefit to BREX is that a project may also validate its data against a BREX to ensure compliance with certain rules.

 

Is a BREX required?

The BREX data module reference (element <brexDmRef> ) is a required element in each data module.

 

NOTE

Beginning with Issue 4.1, a BREX data module reference is also required for the following Common Source DataBase (CSDB) objects: comment, ddn, dml, pm, scormContentPackage, and dataUpdateFile.

 

 

Fortunately, S1000D provides a default BREX, so projects are not required to author their own BREX. Projects using only the default BREX should understand that the default BREX does not include project-specific requirements.

 

Who should use a BREX?

Any project or organization, which has specific authoring requirements, should develop a BREX. This includes any prohibited or required elements and/or attributes, and required values (such as recording the project’s responsible partner company Commercial and Government Entity (CAGE) code) or allowed values (such as configurable attributes).

 

What does a BREX include?

Many of a project’s requirements can be included in a BREX data module. While all rules can be captured within a BREX, many of these rules are considered ‘narrative’ (element <nonContextRules>). Narrative rules have no corresponding XML Path Language (XPath), which the BREX uses to validate data against each rule. BREX rules which can be verified via XPath are considered ‘computer-verifiable’ (element <contextRules> ). Computer-verifiable rules are often true or false, or include an allowed value or a list of allowed values.

An example of a narrative rule is a required font size for titles. A font size cannot be identified in the XML, so no corresponding XPath exists to verify the font size.

An example of a computer-verifiable rule is the inclusion of a prohibited element. If an element is prohibited (in any location of the XML file), its XPath is included within the BREX (e.g., ʺ//elementNameʺ). If the prohibited element is encountered, an error is generated.

Additionally, a BREX can include the entire Standard Numbering System (SNS) and its corresponding technical names (element <snsRules> ). It can also exclude any prohibited notation types (element <notationRuleList> ).

 

How is a BREX used?

A BREX is used to capture specific rules, definitions, patterns, and allowed or prohibited values, which can be shared with other project stakeholders. This provides the stakeholders with all rules regarding the XML, including any project-defined configurable attribute values (e.g., all parties understand the value psd52 identifies a placard item).

Sharing information about XML-specific rules or other project requirements is only part of the value provided by BREX. Another major benefit to having a BREX is that a project can validate their data against the BREX to ensure requirements are met and the data complies with those requirements.

In order to validate data against a BREX, several BREX tools are available. BREX checkers are included as part of some authoring environments while others are used as a stand-alone tool.

 

What are the benefits of using a BREX?

Aside from having business rules documented in a single location, a BREX is a valuable tool when used as input for some authoring environments. With the proper configuration, BREX will generate an error whenever a rule is broken. A BREX can ensure prohibited elements and attributes are not included in the data as well as ensuring required elements and attributes are included in the data.

Projects may desire specific wording is used for procedures – BREX to the rescue.

For example, a technical manual has evolved over decades. During this time, many unwanted modifications have occurred to the data due to lack of documented business rules and multiple authors have inserted many different phrases included for procedures, such as ‘Do the following’ and ‘Make sure the following’. The BREX can identify where those phrases are used, making it easy for authors to correct to the desired phrases (e.g., ‘Perform the following’ and ‘Ensure the following’).

 

Summary

While BREX was originally created to provide project stakeholders with documented business rules, a BREX can also ensure the data meets the project requirements, which ensures consistency in the data. Just like a big brother, BREX is always hovering, waiting to provide guidance and point out errors.

 

For more information

For additional information on BREX or to see how Pentecom can help your company with developing a BREX for your S1000D project; call 888.773.9067 or e-mail us at info@pentecom.com.

 

Download this article in PDF: BREX – the developers big brother

No Comment

Post A Comment