Understanding the Business Rules Document (brDoc) Schema

In this post, our Business Rules trainer Victoria Ichizli-Bartels explains why there is a new Business Rules Schema in Issue 4.2, why it is needed, and why the BREX Schema is not enough.

Business Rules Document (brDoc) XML Schema is a new structure for capturing, managing and exchanging business rules. It has been added to the S1000D Issue 4.2 and represents the result of many years’ work by the Business Rules Working Group, which is a global S1000D working group with members coming from many different countries, industries, and organizations.

There are now two structures for business rules. One is Business Rules Exchange (BREX) and another Business Rules Document (brDoc) Schemas.

What is the difference between them?

Let’s start with their definitions in Issue 4.2 in Chap 9.2.1:

  • Business Rules EXchange (BREX) is “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.”
  • Business rule document data (brDoc) module is “A data module that provides information about the project and/or organizational business rules. It can contain definitions, guidance material, examples, as well as information on the progress of the business rules production process. The information captured in a BR data module can be used to create a BREX data module.”

So primary role for BREX data modules is to exchange the rules resulting from decision making in the given project between all involved parties. These are often used for automatic verification of authored data models against the respective business rules of the project in focus.

The primary role of the business rules document data module is to document everything which relates to business rules including the decisions made, but also all the guidance and other related information. These documents also indicate whether the decisions made must be exchanged with the partners in the project, that is whether they need to be captured in BREX data modules. And finally, the business rules document structure includes constructs to record audit information around each business rules decision point and decisions taken. These are actions to be carried out, deadlines, and an indication whether the decision point has been adequately addressed or not. Just like their counterparts in non-S1000D formats, the business ruled documents are also meant to be at least partially exchanged between organizations involved in the projects.

The structures of two Schemas reflect their purposes. BREX Schema allows a creation of a flat list of decisions, with specific constructs allowing automatic check against them, whereas the business rules document can be created both in an index format as well as running text with a complex nested structure. The business rules document Schema fills in the gap of the functionalities necessary for the full business rules documentation using S1000D technology in addition to those available in the BREX Schema.

The differences and purposes between the two data modules are distinctly visible.  Nevertheless, shortly after the brDoc appearance the questions appeared, whether the two Schemas are necessary and whether one (that is the business rules document Schema) can be enhanced with the functionalities of the other (the BREX Schema), and ultimately replace it. The Business Rules Working Group discussed this even before the brDoc Schema was ratified and frozen for the Issue 4.2. And its members agreed that before we remove or crucially change something which is widely in use, the S1000D users need to gather experience in applying both BREX and brDoc constructs.

To facilitate the efficient use of both, BRWG has suggested how they can be created and applied. To find out how this can be done, read Chap 2.5.2 in S1000D Issue 4.2. You will find both the definitions and diagrams illustrating the generation and use for both constructs. I also recommend that you read a post here in the Bitesize series on Business rules dedicated to this chapter called, Bitesize Business Rules: read-me chapters for Business Rules concept in S1000D® issue 4.2.

Let’s come back to BREX and brDoc Schemas. Both structures came to exist because there was an urgent need to give the backbone of any S1000D implementation, which are business rules, a rigid and at the same time flexible structure to guarantee their interchangeability and maintainability. At the same time, these Schemas were created to accommodate the requirements of various industries, organizations, and projects, to reflect their well-established practices. How these will develop and whether one or another will blend into another, the experience of their use will show.

As a member of the Business Rules Working Group and its chair, I urge you to communicate your thoughts and your experiences to the members of the BRWG, so that we can further improve and strengthen these vital for every S1000D implementation techniques and related resources (such as default BREX, BRDP Index, BR template and other).

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 s