Skip to main content

Business rules & BREX

S1000D gives you many choices. Each project must decide how it will apply the specification. These decisions are called business rules. A project records its business rules in a machine-checkable data module called the BREX (Business Rules EXchange). Every data module references a BREX, and tools check each data module against it.

Business rules: documented decisions​

A business rule is a documented decision about how a project implements S1000D. S1000D leaves many points open on purpose. Each project chooses, then writes the choice down so every author follows it.

Business rules cover the whole project, not just authoring. Typical decisions include:

  • Which information codes and data module types the project will use.
  • Which Standard Numbering System (SNS) applies to the product.
  • Which elements and attributes are allowed, required, or banned.
  • Which values are permitted for specific attributes.
  • How illustrations, applicability, and metadata are handled.
note

Business rules are decisions. BREX is one way to encode them. A business rule exists even before anyone writes it into BREX, but a rule that lives only in a person's head cannot be checked by software.

BREX: the machine-checkable form​

The BREX is a real S1000D data module. It has its own schema. It encodes the project's business rules in a form that software can read and apply. When a tool validates a data module, it reads the referenced BREX and reports any content that breaks the rules.

A BREX data module always uses these identifying values:

DMC fieldRequired valueMeaning
Information code022Marks the data module as a BREX
Item location codeDThe value the spec mandates for a BREX; D is the item location code meaning "all locations apply"

What a BREX contains​

The content of a BREX holds three kinds of rule:

Rule groupWritten inChecked by
SNS rulesPlain English, in a fixed structureTool plus human review
Context rulesXPath (with plain-English notes)Software, automatically
Context-independent rulesPlain EnglishHuman review

Context rules do the automatic work. Each one points at part of the XML with an XPath expression and states whether that part is allowed, required, or forbidden. A tool walks every data module, runs these expressions, and flags any breach.

info

Because the rules are in XPath, the same BREX can drive validation in any conforming tool. That is the point of the word Exchange in Business Rules EXchange: the rules travel with the data, not with one vendor's software.

Every data module references a BREX​

In S1000D, every data module must reference a BREX. The reference is part of the data module's identification and status metadata. It tells tools which rule set to check the content against.

A project does not have to start from nothing. S1000D ships a default BREX in the download package for each Issue. It carries a base set of rules drawn from the specification. Unless a project states otherwise, its data modules reference this default BREX.

Projects often layer BREX data modules. A common pattern:

S1000D default BREX   (base rules from the spec)
        ▲
   Organisation BREX  (company-wide rules)
        ▲
     Project BREX     (rules for this one project)

Each layer references the one below it. A data module references the most specific BREX, and the rules accumulate down the chain.

Validating with s1kd-tools​

The s1kd-tools toolchain includes s1kd-brexcheck. It reads a data module, finds its referenced BREX, and reports any place where the content breaks a computable rule.

# Example only — uses an illustrative data module filename.
s1kd-brexcheck DMC-MYPRJ-A-00-00-00-00A-040A-D_000-03_EN-CA.XML

The output lists each rule that the data module violates, so an author can fix the content before delivery.

tip

Run s1kd-brexcheck early and often, the same way you would run a linter. A failed check is cheaper to fix while you are still writing than after the publication is assembled.

Summary​

  • Business rules are documented project decisions about how to apply S1000D.
  • BREX (Business Rules EXchange) is a data module that encodes those rules in a machine-checkable form, using information code 022.
  • Every data module references a BREX, and its content is validated against it.
  • S1000D ships a default BREX; projects can layer their own on top.

Sources​