The more I work with the Rules API the more I’m convinced that the Vocabulary element was only created for the BRC. The most generous I can be is that someone came up with a good idea for the BRC and “retrofitted” it for the API. There are two reasons for this;

  1. The API is unsupported and undocumented.
  2. The BRL (Business Rules Language) can function happily without it – in fact a rule can reference directly the document element / .NET method etc.

If you take a look at the following two bites from the exported rule store, UI think you’ll see why I come to this conclusion;

The following is in effect a definition of a string literal in the export vocabulary

  <vocabularydefinition id=”54e58c56-e279-4729-b0d4-2e7bfbef989e” name=”TransferControlAccount” description=””>

      <literaldefinition type=”string”>



      <formatstring language=”en-US” string=” Transfer Control Account” />


The following is taken from an extract of an action. This interesting thing to note is that the literal value “222222” is also specified, along side the link to the vocab entry specifying it;


          <vocabularylink uri=”2e2bb376-b4ac-4d42-9573-cdf42088f681″

element=”453cb556-e96e-4e10-b456-96bf6d1313c6″ />

          <classmember classref=”Accounting” member=”AddAccountingEntries” sideeffects=”true”>



                <vocabularylink uri=”2e2bb376-b4ac-4d42-9573-cdf42088f681″

element=”54e58c56-e279-4729-b0d4-2e7bfbef989e” />






So why would this redundant data be here? Performance? I doubt it. The whole “immutability” of Rules and Vocabularies makes sense from a version management perspective until you actually start using them. Imagine the scenario; You have defined your Vocabulary before starting your rules (This is required because you can’t reference a Vocabulary from your rules until that Vocabulary has been published – this in itself is predicated on knowing all the terms up front – big assumption!). You define 25+ rules, using multiple references to your vocabulary. Fine. You now publish the rule policy. At this point the world is still in order – version 1.0 of both rules and vocabulary are in a lotus type harmony. But what happens when you want to extend or amend the vocabulary? You create a new version of the Vocabulary (cut & paste!),make your amendments and publish it. Of course NONE of your rules will reference this new vocabulary (1.1) as all links reference 1.0 of the vocabulary. The only way to reference the new vocabulary is to create a new version of your rules (cut & paste!), and edit EACH AND EVERY reference to the vocabulary to repoint to the new version.

This isn’t new of course, and tools do exist to deal with it.

The BRC has been criticised for this “cut & paste” mentality, but in fact some of the problem goes back to the design of the rules system itself.