Business Rule Language (BRL): A Controlled English for Writing Business Rules

A controlled English for rules, based on SBVR and RuleSpeak.

1. Purpose

The same concept is currently expressed many different ways: mandatoriness, enumeration restriction, obligation and conditions each have several competing forms, and the Type field answers more than one question at a time.

Consequence: there is no consistency, so the same rule is not understood the same way by everyone who reads it.

BRL fixes a closed set of keywords and a closed set of sentence patterns. Every rule is written with those and nothing else.

2. Scope

Mandatory for the free text fields of a RULE: Title, Type, Details, TO_BE_Details and Error Message. Also for NTF triggers, SecP conditions, and any other text stating what must be true, what a value is derived from, or what must happen.

The Template_RULE structure is not changed. BRL applies to the text inside the fields only.

Not used for UC main flow narrative steps, which keep the workflow keywords (VALIDATES THAT, IF/THEN/ELSE, DO…UNTIL, MEANWHILE, SENDS … TO, RESUME STEP), and not used for end user facing UI text other than error messages.

Where a UC step needs a constraint, it references the RULE by hyperlink instead of restating it.

3. Necessity test

Applied before writing, classifying or migrating anything.

Could a machine sending or receiving an M2M payload violate this rule?

No means it only works with a human at a screen. That is an SCR or a UC, not a rule.

Then two more filters:

1. Already declared in the entity Data Dictionary (Is Required, enum reference, occurrence)? The DD is the source. Do not restate it as a rule.
2. A permission, who may act? That is a SecP.

The question is not whether the XSD would reject the payload, but whether the backend has to. The XSD enforces types and structure, not business conditions, so for most rules the rule and its error message are the only feedback the sending system gets.

4. Foundations

From SBVR: rules use only terms that exist in the DD or the Vocabulary (Glossary); modality is explicit and limited; rules state what must be true, not what the system does.

From RuleSpeak: subject first, singular; “only if” for restricted permission; two or more conditions become a lettered list, never an and/or chain; one rule, one statement.

The Vocabulary (Glossary) is the companion artefact to this standard. It holds business terms that are not DD attributes and cannot be: Regulation device, Legacy device, OCM device, reporting period, current period, first version, previous version, dossier, dossier status, owner, submitter. A noun that is neither a DD attribute nor a Vocabulary term may not appear in a rule.

5. Keywords

The only words allowed. Anything else is a defect.

5.1 Modality

Do not use: shall, should, can, cannot, will, needs to, has to, is required to, is allowed to, is not allowed to, is able to, ought to.

5.2 Conditions

Do not use: in case, in the event that, provided that, depending on, where.

if and when are not interchangeable. State takes if, event takes when.

5.3 Logical grouping

Do not use: either … or, both … and, and/or, as well as, respectively.

Two or more conditions always become a lettered list with an explicit header. This removes operator precedence ambiguity.

Statements are numbered 1., 2., 3. and the conditions under a statement are lettered a., b., c. Never a plain bullet, so that a review comment, a test case or a Jira story can point at statement 2 condition b.

5.4 Comparison

Do not use: >, <, >=, <=, =, !=, equals, prior to, no later than, at most (dates), smaller than, exceeds, cannot exceed. Also before and after in a comparison.

before and after are allowed in one place only: an NTF scheduled trigger, after a duration and in front of an event (pattern T3). In a comparison they do not say whether the boundary is included.

A comparison to a literal always carries a comparison keyword. The report contact type is Same as manufacturer is a defect, because a bare is turns the value into a predicate and the sentence reads as a comparison of two things rather than a constraint on one. Write must be equal to Same as manufacturer or Other, or must not be equal to Same as authorised representative.

5.5 Presence

Do not use: is empty, is blank, is null, is filled, exists, cannot be empty.

5.6 Sets and enumerations

Do not use: only values from X are allowed, must be one of, is one of, the only accepted value is.

Restricting a subset is a separate statement:

1. The report type is one value from ReportTypeEnum.
2. The report type may be Follow up only if at least one of the following is true:
   a. The report is the first version.
   b. The report type of the previous version is Initial.

Where the subset does not depend on a condition but on the field itself, write the positive obligation, not the exclusion of the value that is missing:

1. The report contact type is one value from SubmitterContactTypesEnum.
2. The report contact type must be equal to Same as manufacturer or Other.

Which of the two forms is right is decided by one question: what has to happen when a value is added to the enum. If the new value has to be permitted on its own, the exclusion form is right, because the reason for excluding is independent of the list, as in The report type must not be equal to Unknown where Unknown is a technical leftover. If the new value must not be permitted without a decision, the positive form is right, because the set is closed by the field itself, as with the report contact type of an EU manufacturer, which has no authorised representative to point at.

Exclusion is an open list minus one value. The positive form is a closed list.

5.7 Cardinality

exactly one, at most one, at least one, at most N, at least N

Do not use: one and only one, no more than, up to, a maximum of, several, multiple.

5.8 Identity, derivation, mutability

Do not use: duplicate, cannot be changed, read-only, non-editable.

Uniqueness without a named scope is a defect in either form. is derived from and defaults to are not synonyms: a derived attribute is immutable by definition, so C12 alongside C11 is redundant, while a default usually needs its own constraint on what it may be changed to. Neither takes must and neither has an error message.

read-only is not a rule word. Three different things hide behind it: the value equals another value, which is the equality statement in the rule; the field is never entered by the user, which is the Data Dictionary columns Is Input By and Is Updateable; and the grey box on the screen, which is the SCR or the UC.

5.9 Format

matches pattern PATTERN
has a length of at most N characters
has a length of exactly N characters
has at most N decimal places

5.10 State

may move from state A to state B only if
is in state
is in dossier status

State and status names capitalised, unquoted: Draft, Submitted, Registered, Approved, Withdrawn, Closed, Active, Pending Closure.

6. Patterns

6.1 Sentence patterns

Nesting is allowed one level only, a numbered statement with lettered conditions under it. More means the rule must be split.

6.2 Statement types

Closed list. A rule may carry more than one, comma separated. The statement types classify a rule during writing and review; they are not written into the Details block.

Compound conditional, nested conditional, complex calculation, range-based conditional and field dependency are not separate types. They are compositions of the above.

6.3 The Details block

Numbered statements only.

1. <statement>
2. <statement>
   a. <condition>
   b. <condition>

Numbered statements are conjunctive: every one of them applies. No header line says so. all the following are true groups conditions inside one statement, it never introduces the statement list, and the legacy preamble All the following constraints apply: is a defect. A rule whose statements are alternatives is not one rule; it is one statement with lettered conditions under at least one of the following is true.

Each statement is one sentence, numbered, ending with a full stop, using only section 5 keywords. More than 6 statements means more than one rule.

A derivation statement (C11) or a default value statement (C15) may stand among the constraint statements of a rule. It is written like the others, numbered, in the same block. It differs in two ways only: it has no error code, because there is nothing to violate, and it has no negative test, so QA does not record a missing test for it. See sections 8.2 and 9.

Example, RULE-00248:

1. A PSR may be referenced in the MIR only if all the following are true:
   a. The MIR is declared as related to a PSR.
   b. The PSR and the MIR have the same owner.
   c. The PSR is in dossier status Active or Pending Closure.
2. A PSR in dossier status Pending Closure may be referenced in the MIR only if the PSR
   moved to that status later than the start date of the current period.
3. Each PSR is referenced at most once in the MIR.

7. Naming

7.1 Business terms, not attribute paths

A statement is read by the business analyst, the business owner and business stakeholders, not only by a developer. It is therefore written in business terms.

The Data Dictionary attribute is named once, in the Title, and the Details block does not repeat it. Enum literals follow the same move: the statement uses the business label (Active, Follow up), the technical literal (ACTIVE, FOLLOW_UP) stays in the ENUM artefact and in the DD.

This loosens nothing else. All section 5 keywords still apply, and every business noun has to exist in the Vocabulary.

Watch the subject when a status belongs to a relationship rather than to the record. A Competent Authority is not approved; its participation in a PSR is. Write “The participation status of the Competent Authority in the referenced PSR is Approved, participating in PSR”, not “The Competent Authority is approved”.

A business label is not a free pass either. When the label is a UI sentence, as in “Same as manufacturer”, the statement still needs a comparison keyword, see 5.4, and the cleanest fix is usually to give the ENUM a label that reads as a value rather than as a screen sentence.

7.2 The object, not the type

A statement talks about the concrete object being processed. Write within the MIR, not within the given MIR and not within a MIR. An indefinite article is used only for a candidate that is still being tested: A PSR may be referenced in the MIR only if …

7.3 Conventions

Never inside a rule: bold, italics, quotes around attribute names, pasted Confluence URLs, escaped braces, the em dash, the rule id restated in its own text.

Enum names: a rule uses the business name, PascalCase with an Enum suffix, as in the DD. ENUM_MTR_REPORT_TYPE style names are XSD type names, not business names. They belong in the DD XSD mapping column next to the XSD path, and are never written in a rule.

8. Classification

8.1 Title

<Entity>.<attribute> (<Short title>)
<Entity> (<Short title>)          when not tied to one attribute

The BusId is a separate field and is not repeated in the Title.

Short title is a noun phrase that says the point of the rule, not its subject. The subject is already in the Title, so repeating the field label and appending the context, as in “Authorised representative contact details and the referenced PSR”, says nothing. “Source of the contact details” says what the rule decides.

Never a sentence, a question, a user story, or a repeat of the BusId.

The table is keyed on the primary Type. A rule that carries more than one value takes the row of the first one, and the short title still says what the rule decides, not what its statements are classified as. Where no short title covers everything the rule holds, the merge was wrong and the rule is two rules; that test is below and it is what guards against merging too much.

Wrong, and why:

Implantable property must be False if Risk Class I          a sentence
Is it Device a suture, staple, dental filling?              a question
As a MF/PR I want to see an information box                 a user story
RULE-00049: -BR-VGL-MIR-00049- - the referenced device      the id repeated
OCM deviceStatus                                            says the subject, not the point

One rule may carry several statements, but only if they share a reason, not merely a field. If no meaningful short title can be written, it is not one rule. The per-field view is the DD row and its Business Rules Ref column, not a bundled rule.

One reason, so one rule:

MIR.reportType (Permitted report types per version)
1. The report type may be Initial only if the MIR is the first version.
2. The report type may be Follow up only if at least one of the following is true:
   a. The MIR is the first version.
   b. The report type of the previous version is Initial.
   c. The report type of the previous version is Follow up.

Only the field in common, so three rules:

PSRP.timePeriod
1. The end date is the same as or later than the start date.
2. The EEA device count is less than or equal to the World device count.
3. A time period must not be switched off while the next one is on.

Date ordering, a numeric relation and a sequence rule. No title covers all three, which is the signal to split.

8.2 Type

The field keeps its template name, Type. The value set is replaced.

The template value set {UI, Workflow, Data consistency, Data constraint} mixes what the rule constrains with where it is enforced. Where it is enforced does not need recording: section 3 already guarantees every surviving rule is M2M relevant, so UI is never the answer. What happens on violation does not need recording either, because the modality keyword carries it. must and is mandatory are obligations, so a violation blocks. is derived from and defaults to are not obligations, so there is nothing to violate.

Type states what the rule constrains. Values from this list.

A rule may carry more than one value, comma separated, when it holds statements of more than one type. The first value is the primary one and is what the rule is filed under.

An Error Message is mandatory for every constraint statement. A derivation statement (C11) and a default value statement (C15) carry none, so a rule made only of those has no Error Message, while a rule that mixes them has one code per constraint statement and none for the rest. See section 9.

Data constraint versus Reference constraint: if the value plus the DD decides it, Data constraint. If deciding it needs another record’s state, Reference constraint. An enum is a closed DD list, so Data constraint; “devices in Registered state” is an open runtime set, so Reference constraint.

Splitting a rule is still right when the statements do not share a reason, and it is decided by the reason, not by the Type. Worked case, RULE-00248: which PSR may be referenced and when the PSR reference is mandatory at all are two different questions about the same field, so they are two rules, and they would be two rules even if both carried the same Type.

The reverse test matters as much. In RULE-00250 the country of the Competent Authority and the participation of that Competent Authority in the PSR both constrain which Competent Authority may be referenced, so they are one rule, even though they come from two different legacy BRs and the rule ends up carrying two Type values.

Workflow is not used. Every rule that would carry it constrains a state, a status or a version, which is Lifecycle. A deadline on a transition is Lifecycle too, not a separate type.

UI is not used. A rule that only concerns rendering fails the section 3 test and is not a rule at all, so it has no Type to carry.

Once the section 3 filter is applied, Data constraint is the exception rather than the default, because most single-attribute facts are already declared in the DD.

8.3 What is not a RULE

A record is read once: if it contains a statement that survives the section 3 test, that statement becomes a rule and the rest of the record belongs elsewhere. If it contains none, it is not a rule at all.

Search is not excluded wholesale. DossierSearchCriteria is part of the M2M schema, so a machine can issue a search and can violate a constraint on it. Split the three cases:

Two cases that cause most mislabelling:

Applicability. A field being shown or hidden is conditional mandatoriness (C2), not presentation. The rule states when the value is required; how the screen renders it is not recorded here.

Consequence rendering. The eligibility condition is the rule; the greyed-out row and the tooltip are not.

9. Error Message

<ERROR-xxxxx> <message>

One sentence, present tense. Names the field by UI label, never by API name. States what is wrong, not what the code does. Runtime values in square brackets. No rule id, no enum technical name, no URL. No “Please” outside a confirmation prompt. English only.

One error code per failure mode, each mapping to one constraint statement. A derivation statement and a default value statement have no failure mode, so they map to no code.

The subject is the object that fails, not the field value. Ownership, state and status belong to the dossier, so the sentence starts with the dossier. The UI label stays in the sentence so that the user can find the field.

Right: The PSR [value] selected in "Periodic Summary Report ID" does not have the same
       owner as this report.
Wrong: "Periodic Summary Report ID" [value] has a different owner.

Where the failing thing really is the field value, the field is the subject:

Old: ERROR-00187: Field is mandatory and cannot be empty - preliminaryResultConclusion
New: ERROR-00187 "Preliminary result conclusion" is mandatory.

The error message is the only place where a Boolean is written as “Yes” or “No”, and the only place where UI labels appear.

10. NTF triggers

Duration: number plus plural unit (21 days). Recipient: <role> of <actor type>.

Event keywords, closed, passive present: is submitted, is registered, is approved, is refused, is withdrawn, is closed, is deleted, is created, is updated, is reached, is exceeded.

11. SecP conditions

A <role> of <actor type> may <action> a <entity> only if all the following are true:
a. <condition>
b. <condition>

Actions, closed: view, search, create, edit, delete, submit, approve, refuse, withdraw, close, export, download, comment, assess.

12. Replacements

A rule that says what the system does is a use case step, not a rule.

13. Conventions taken as settled

14. Summary

Write every rule as a declarative sentence about one subject, in business terms, using only:

must, must not, may, may ... only if, is mandatory, is optional
if, only if, unless, when, otherwise
all the following are true, at least one of the following is true,
exactly one of the following is true, none of the following is true, and, or, not
is equal to, is not equal to, is greater than, is greater than or equal to,
is less than, is less than or equal to, is earlier than, is later than,
is the same as or earlier than, is the same as or later than, is between ... and ...
is provided, is not provided
is one value from, is one or more values from, is in, is not in
exactly one, at most one, at least one, at most N, at least N
is unique within, at most once in, is derived from, defaults to, is immutable after
matches pattern, has a length of at most N characters, has at most N decimal places
may move from state ... to state ... only if, is in state, is in dossier status

Two or more conditions become a lettered list under a numbered statement. One rule, one reason. No procedural verbs. No attribute paths and no technical literals inside a statement: those live in the Title, the DD and the ENUM. UI labels only in error messages.