A note beforehand: for the simplicity and readability purposes I omitted the “<” and “>” brackets at the element names.
In the last post with the title “brDoc Schema: What is a Business Rules Paragraph (brPara)?”, we started looking a bit deeper into the business rules document (brDoc) XML Schema introduced in the S1000D Issue 4.2. There, we’ve established that a business rule decision point (BRDP) along with decisions (brDecision) taken upon it, as well as metadata of that particular decision point and related decision making, compose a construct named business rules paragraph (brPara).
Let us recall the brPara structure:
So a brDecision is a component of a brPara.
But why is there another instance of a brDecision, outside of the brPara?
Here is the simplified structure of the brDoc Schema to illustrate what I mean. Both instances of brDecision are emphasized as bold and italic:
The answer to the question why is that so becomes clear if you consider that S1000D is never implemented into a regulation-free environment. There are always other rules, standards, and regulations established in a company or project in addition to those introduced by S1000D.
So, to mark up those already existing rules, you use the element with the path brLevelledPara/brDecision. The reason for such a structure is that those regulations do not need a decision point. The decisions exist already without a decision point defined prior.
That also applies to the S1000D text. Helpfully in Issue 4.2, those rules are visible now due to the unique identifiers for default BREX (Business Rules EXchange) rules. These are the rules, which the S1000D implementers must follow so that their data are S1000D-conformant and processes S1000D-compliant.
See for example the following extract references in Issue 4.2, Chap 22.214.171.124.1.1 Common constructs – Change marking, Para 2.1.1:
“Editorial changes must not use change markup. Refer to default BREX rule BREX-S1-00044.
Data modules that have the value of the attribute issueNumber of the element <issueInfo> set to “001” and the value of the attribute issueType of the element <dmStatus> set to “new” must not use change markup. Refer to default BREX rule BREX-S1-00013 and BREX-S1-00036.”
Thus, if the standards and regulations within your organization or project contain similar imperative statements including words such as “must,” then you might consider to capture them using the element brDecision, which is a direct child of brLevelledPara. By doing so, you can identify and refer to those rules easily as well as re-use their definitions.
Following the S1000D example, you might also want to consider to add those to your BREX data modules, especially if that rule can be used in a BREX-checker, the latter being a piece of software verifying the technical publication data modules and other Common Source Data Base (CSDB) objects against your project business rules.
However, the unique identifiers of those rules must not necessarily start with a prefix “BREX-,” especially if you are not going to capture those in BREX data modules. The syntax of the identifiers for these rules as well as the decisions taken upon S1000D BRDP and the decision points being specific to your project or organization is entirely up to you and your project partners.
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.