By: Amos (Kippi) Bordowitz

Let's talk about Parameterized RuleSets.

Here at Outburn, we are big fans of FHIR® Shorthand (FSH. Pronounced “fish”) - a domain-specific language for defining the contents of FHIR Resources and Implementation Guides. FSH allows a FHIR® implementor to create every single type of FHIR® resource in a fraction of the time required, vs JSON or XML implementations.

If you are implementors and are still working with JSON or XML files for your FHIR® projects, we highly recommend making the move. We just happen to give courses on the subjects, and you can get more info and register here.

From time to time, we will bring you bits of useful information on how to take your FSH game to the next level, so you can become a… fly FSHer (Sorry, couldn’t help myself – puns are life). So, with no further fanfare, we bring you the first installment of fly-FSHing!

Parameterized rulesets in FSH

Any person who has ever programmed has come up against the age-old question – “copy-paste – good or bad?”. If I learned something in my short tenure as a programmer, it’s that code duplication is almost never a good idea. First off – if you have a mistake in your code, you have now duplicated it n-fold (n being the number of “pastes”). Secondly – if you need to make a change in said code snippet, you now must make the same change in every duplication.

Well, FSH looks an awful much like code. It’s not REALLY code, as it doesn’t have much logic (i.e., loops, functions etc.) in it. You could think of it a bit more as a scripting language, but even that wouldn’t be an exact fit. FSH is a strange… fish. Let’s not dwell on it more. The point is, as you use an IDE with it, the work resembles programming.

****

A side note – the best way to use FSH is with Microsoft VS Code. The reason for this is that the Mitre corporation, the people who created and maintain FSH, have created a wonderful plugin for the IDE. Working with it is a breeze and I cannot recommend it enough. You can write FSH in any text editor, but life is better with an IDE.

****

Rulesets

So – we’ve established that code duplication is not the best idea, especially with copy-paste. But that doesn’t’ mean it doesn’t exist at all. Sometimes it’s unavoidable – many resources require the exact same lines of code. I fully admit, most of my files have lines of code that are identical to lines found in other files, or even lines in the very same file, as I was unaware of the powerful idea of Parameterized RuleSets in FSH.

OK so first off, what are RuleSets? RuleSets are groups of rules one can use in any number of FSH definitions. Rules are the different “bits” of information a resource holds. For example, if we are working on a StructureDefinition (SD), a rule would most often be a restriction or expansion on one of the elements of the SD. For example, say we are writing a Profile on Patient, rules could be redefining the cardinality for Patient.name.given – say we decide a first name is a must for our organization, we can change the cardinality to 1..1. In FSH the rule would look like so:

* name.given 1..1
(Rules all start with an asterisk (*) followed by a space)

ILCore

The ILCore Patient and RelatedPerson Profiles both share at least a few identical Rules. Here – this, for example, is identical in both profiles:

We are defining slicing rules (if you are unfamiliar with slicing, you can still understand this article. Slicing is lesson for another day) on the “identifier” element. If we have the exact same lines of code, we might want to maintain them simultaneously. Enter Rulesets.

We can define a ruleset for the code seen above. We will only do the first 3 lines, just to keep it concise.

Now, any time we want these exact rules in Resource, all we need to do is to invoke the RuleSet using the “insert” rule keyword, like so:

This was an example of a simple RuleSet. RuleSets, at their simplest, are just a name and a set of rules. It’s basically a copy-paste solution that can easily be maintained. You do the work once and can use it as many times as you want.
The idea is clear, I’m sure. Onwards to the real deal.

****

Parameterized RuleSets

One thing worth mentioning before diving into examples of Parameterized RuleSets is “soft indexing”.  Many elements in FHIR® are of an array type – they may hold more than one piece of data. For example, the Patient.name.given element may hold several family names. We can hard-number them, i.e., given[0], given[1] etc. (the bracketed number being the index in the array) or we can soft index them using ‘+’ to indicate a move to the next index and ‘=’ if we need to make extra changes on the same index.

Here - let’s see what that looks like:

There is no need to really understand the syntax here. It’s basic stuff once you’ve taken a dive into FSH. But you can see that the first item was hard coded into index 0, followed by several rules on the same item The next item is added using the ‘+’ sign and then very similar rules

****

Looking at the example above, we can clearly see that there is some form of duplication. It seems like there are great similarities and only slight modifications between the two parameters. Obviously though, we can’t use a regular RuleSet, as there are at least some differences – we have the same fields (parameter.name, parameter.use etc.) but they are not always populated with the same data. In this case, we can create a RuleSet with parameters that we may populate at the time of invocation!

Here is how we would parameterize the RuleSet for this example:

As you can see, after we name the RuleSet, we open parentheses. Anyone who has programmed should be familiar with what comes next – every member inside the parentheses is an input parameter. Note that the parameters are then invoked themselves in the RuleSet definition, just like you would use parameters in a programming function. We do this with the curly braces. Anything that is not inside the curly braces will appear exactly as we see it. Anything in them will be replaced by whatever we specify at the time of invocation. You could look at this as a type of macro.

Once we want to use the Parameterized RuleSet we call it within our resource like so:

You’ll see that calling the RuleSet with these parameters will result in the exact same parameter as the first one in the example shown above.

Note that when we defined the Ruleset we used soft indexing, assuring that every time we call the RuleSet, the new parameter will be inserted into the array in order. So, the first time you call it, it will populate index 0 and the next time – index 1, index 2 and on.

In Conclusion

RuleSets produce more compact and readable code. If we require 20 parameters, each with 6 attributes, instead of having 120 lines of code, we would have… 6. Maintenance is easier, as it the ability to understand the file. It is also more consistent – each parameter is guaranteed to have the same format and errors will be narrowed down to basic syntax rather than missing lines or mistyped fields. And of course – coding = creating errors. The fewer lines of coed you have, the fewer errors.

Happy coding!

BTW - did you know we give courses on FSH? Want to know more? Check out our Academy page

Follow us on LinkedIn