Example: Using Blawx for Rules as Code

Example: Using Blawx for Rules as Code

The purpose of this post is to give users an idea how Blawx might be used to compartmentalize legal reasoning in an application.

Compartmentalizing legal reasoning in an application has a number of benefits. It makes it easier to ensure the substantive legal correctness of the app. It also makes it considerably easier to update the legal reasoning in the app when the relevant rules change.

Please note the example below is a prototype, and relies of features of Blawx that are not yet working at the time of writing. Specifically, there is a known issue where the override blocks do not behave as anticipated.

Also note that this example assumes a very basic understanding of the structure of Blawx code. If you are entirely new to Blawx, you may want to check out some other tutorials first.

Play Along

If you would like to follow along, download the demonstration encoding of the Personal Directives Act, and go to the Blawx live alpha version. In the Menu section choose “Load Workspace” and upload the demonstration encoding.

Our Scenario

Let’s say you want to create a tool that allows people to build personal directives (which in other jurisdictions may be known as “living wills”). In Alberta, the legislation governing personal directives is the Personal Directives Act, RSA 2000 c P-6.

Let’s also say that you want your online tool to be able to tell whether the combination of agents, witness, maker, and alternative signor (if any) are valid according to the Act. The rules around those matters are set out in sections 3 through 5 of the Act, and read as follows:

Part 2 – Personal Directives

Who can make a personal directive

3(1)  Any person who is at least 18 years of age and understands the nature and effect of a personal directive may make a personal directive.

(2)  A person who is at least 18 years of age is presumed to understand the nature and effect of a personal directive.

Personal directive by represented adult

4   Despite section 3, a represented adult may not make a personal directive with respect to a matter over which the represented adult’s guardian has authority.

Requirements of personal directive

5(1)  A personal directive must

                           (a)    be in writing,

                           (b)    be dated,

                           (c)    be signed at the end

                                  (i)    by the maker in the presence of a witness, or

                                (ii)    if the maker is physically unable to sign the directive, by another person on behalf of the maker, at the maker’s direction and in the presence of both the maker and a witness, and

                           (d)    be signed by the witness referred to in clause (c) in the presence of the maker.

(2)  The following persons may not sign a personal directive on behalf of the maker:

                           (a)    a person designated in the directive as an agent;

                           (b)    the spouse or adult interdependent partner of a person designated in the directive as an agent.

(3)  The following persons may not witness the signing of a personal directive:

                           (a)    a person designated in the directive as an agent;

                           (b)    the spouse or adult interdependent partner of a person designated in the directive as an agent;

                           (c)    the spouse or adult interdependent partner of the maker;

                           (d)    a person who signs the directive on behalf of the maker;

                           (e)    the spouse or adult interdependent partner of a person who signs the directive on behalf of the maker.

Our Strategy

Using Blawx, we can create an encoding of these sections of the Act, and make that encoding available for other applications to use by allowing other Blawx users to import that code using Blawx’s include feature.

So one workspace will just encode the Act. Another workspace will import the encoded Act, translate the data provided by an application into terms used in the encoding of the Act, and then ask a question. In this example, we are just looking at the workspace that encodes the Act.

Encoding Section 3

Who can make a personal directive

3(1)  Any person who is at least 18 years of age and understands the nature and effect of a personal directive may make a personal directive.

(2)  A person who is at least 18 years of age is presumed to understand the nature and effect of a personal directive.

The standard process for encoding in Blawx begins with defining an ontology, and then involves expressing the rules using that ontology. In this case, the process of setting out facts and asking questions will be dealt with by other code, so only the ontology and rules apply here.

We will build the ontology required as we go, and add to it as it becomes necessary.

Here, the law is talking about people, who have an age, and an understanding of the nature and effect of personal directives. So our starting ontology looks like this:

We can now encode the rule in section 3(1), which looks like this:

You can see from the question mark in the top left of the rule block that we have added a comment to this block. This is a convenient way to indicate the source of your rule in the original legislation. The comment, when expanded, looks like this:

In future, Blawx will have additional features to allow you to link the blocks in the workspace to relevant sections of legislative text.

Section 3(2) is a presumption. The way that a presumption works is that it is true, when it applies, unless it is overridden by something else. In Blawx, we can represent a presumption by making a rule that applies it, and then overriding it with other rules later. So section 3(2) can be implemented as a simple rule.

The effect of these two rules together is that if someone is a person with an age of 18 or more, they can make a personal directive, because they are presumed to understand one. Any rule that overcomes the presumption with regard to understanding will need to explicitly override the rule “presumption of understanding”.

Encoding Section 4

Personal directive by represented adult

4   Despite section 3, a represented adult may not make a personal directive with respect to a matter over which the represented adult’s guardian has authority.

Section 4 is an example of something that overrides the rule in section 3. This is a difficult rule to model without complicating our ontology significantly, because it refers to “matter[s] over which the represented adult’s guardian has authority”. That introduces the concepts of a guardian, a matter, and an authority. And usefully applying those concepts to a question of whether or not a personal directive is valid would require us to know what matters are dealt with in the personal directive.

It is also not clear, from the drafting, whether the intent is that only matters over which a guardian has authority are invalid in an otherwise valid personal directive, or if a personal directive that includes such matter is invalid entirely.

Even if it was clear, it’s not obvious that “matters over which the represented adult’s guardian has authority” are limited to a set list, or clearly distinguishable from one another.

These are the kinds of difficulties that you will constantly run into in encoding legislation that was not drafting with computational reasoning in mind.

For our purposes, we can take a shortcut. We are trying to facilitate the process of creating personal directives online. In that context, we would rather prohibit represented adults from using the tool at all, for their own safety. So we will reformulate section 4 of the Act, and encode it as though it is a blanked exception to section 3 for represented adults.

We still need to update our ontology to include the concept of a represented adult.

We could also have made a represented adult a sub-category of person, but for our purposes being represented is an attribute of a person.

Section 4 is then encoded in two blocks: a rule that says that a represented adult may not make a PD, and an override statement to show that where it disagrees with the outcome of the rules in section 3, it overrides those rules.

This demonstrates one of the advantages of Blawx’s ability to have the outcome of one rule override the outcome of another, which is enhanced “isomorphism.”

Isomorphism is the idea that there should ideally be a one-to-one relationship between sections of the law you are encoding, and sections of the code. The advantage of that one-to-one relationship is that when a section of the law changes, you know where you need to change your code.

If it were not possible to specify section 4 as an exception to section 3, it would have been necessary to include the requirement that the person is not a represented adult in the rule that determines who may make a personal directive. That would make it harder to find and amend the code if changes were made to section 4 at some point in the future.

Because Blawx allows you to have certain rules override other rules, it is possible to have section 4 encoded seperately, making it easier to maintain the code if the law changes.

Encoding Section 5(1)

Section 5 sets out the requirements of how a personal directive must be signed, and how it must be witnessed. Section 5(1) reads as follows:

5(1)  A personal directive must

                           (a)    be in writing,

                           (b)    be dated,

                           (c)    be signed at the end

                                  (i)    by the maker in the presence of a witness, or

                                (ii)    if the maker is physically unable to sign the directive, by another person on behalf of the maker, at the maker’s direction and in the presence of both the maker and a witness, and

                           (d)    be signed by the witness referred to in clause (c) in the presence of the maker.

Here we run into problems interpreting the language again. First, we run into the difficulty of describing the situation in which the requirements in 5(1) are met, and describing the situation in which the requirements of 5(1) are not met. The statute does not give us a name for a thing that purports to be a personal directive but fails to meet these requirements.

One approach might be to say that such a thing is not a personal directive at all. But then our ontology would need to address some general concept of a document, some type of document that it claims to be, and whether or not that claim is accurate.

Another approach is to use “compliant with the requirements of section 5(1)” as an attribute of a personal directive. But that is quite wordy, and doesn’t communicate what the requirements of section 5(1) imply. A person who doesn’t know what section 5(1) means might thing that it is a set of criteria to be avoided as much as a set of criteria to be sought.

So instead we will use the concept of “validity”. The word “valid” isn’t used in section 5 of the Act, but it is referred to in section 27(1)(b) which states that a Court can “determine the validity of a personal directive or any part of it.” So we are not pulling the word entirely from thin air. But we are clearly filling in a hole.

The new ontological elements we need in order to express these rules are a “Personal Directive”, which has attributes such as “in writing” and “dated”. But we also need a way to represent whether the personal directive has been signed, by whom, for what purpose, in the presence of whom.

So we will start by saying that a Personal Directive has a set of signatures. Each signature has a role, either “Maker” or “Witness”. Each signature also has a person who did the signing, which allows us to distinguish between a person signing on their own behalf and a person signing for someone else. Each signature also has an attribute for the people who were present at that signing. A signature also indicates whether it is at the end of the document.

Here is what our new ontological elements look like. First, the Roles, and Signatures.

You will have noticed that the attributes of different categories begin with an indicator for the category they belong to. This is because Blawx cannot distinguish between two attributes with the same name applied to different categories. In the future we hope to implement better scoping for attributes so that they will not interfere with one another. For now, the best practice is to name attributes in this way so as to avoid conflicts in attribute names.

And this is the ontology for Personal Directives.

In the same way that compliance with all of the requirements of section 5(1) has been called “pd_valid” as an attribute, we introduce names for 5(1)(c) and 5(1)(d) called “pd_validly_signed” and “pd_validly_witnessed”, respectively. This is useful for a few reasons.

First, it allows us to write shorter rules that are easier to understand, and break them up into sections that don’t badly injure isomorphism. Second, having these intermediary conclusions makes it easier for the software using the code to detect why certain conclusions were reached. For instance, a user will now be able to easily ask “is this PD validly signed”, instead of having to look at a long complicated validity rule and see which parts of it were broken. Third, as we will see, these intermediate conclusions will come in helpful encoding the rest of section 5.

Our rule for section 5(1), therefore, looks like this:

We now need to make rules to define “validly signed” and “validly witnessed”. Starting with 5(1)(c), we need to know a new thing about people. Specifically, whether they are physically unable to sign documents. So our ontology for people is updated to look like this:

In the same way that it was helpful to divide “validly signed” and “validly witnessed” as separate ideas, it is now useful to divide out the ideas of “validly signed by the maker” and “validly signed by someone else”. So we can add those concepts to the ontology for a personal directive.

Now we can encode section 5(1)(c) as follows:

So we have said that a personal directive is validly signed if it is either validly signed by the maker (which is section 5(1)(c)(i)) or it is validly signed by someone else on behalf of the maker (section 5(1)(c)(ii).

One thing to note about this reformulation: the words “be signed at the end” appear in section 5(1)(c) itself, not its sub-sections. Should our encoding of section 5(1)(c) similarly include the same requirement?

We could do it that way, but knowing whether a signature is at the end requires knowing what signature it is, which would require us to make this short, clear rule more complicated. So in the interests of clarity of code we are reformulating the law here from

(c) be signed at the end

                                  (i)    by the maker in the presence of a witness, or

                                (ii)    if the maker is physically unable to sign the directive, by another person on behalf of the maker, at the maker’s direction and in the presence of both the maker and a witness, and

to something more like

(c) either

(i) be signed at the end by the maker in the presence of a witness, or

(ii) if the maker is physically unable to sign the directive, be signed at the end by another person on behalf of the maker, at the maker’s direction and in the presence of both the maker and a witness, and

This is a break in isomorphism. If the legislation is later amended to remove the requirement that things be signed at the end by amending section 5(1)(c) itself, you need to be sure that you will be able to find where you encoded that section of the law.

There are a couple of approaches that can help. One is to document the actual reformulation that you encoded somewhere, and refer to that reformulation in your code instead of the original act. Then, when changes happen to the law, the person updating the code needs to look at the changes to the law, determine if they require changes to the reformulation, and then decide if there are required changes to the code itself.

Another approach is to indicate that the code for section 5(1)(c)(i) encodes both that section and 5(1)(c) itself. This example will demonstrate this second method.

Now we need a code block to define when a personal directive is validly signed, at the end, by the person making it, in the presence of the witness.

Here is what the code looks like:

If you open the comments on the main rule block and the “sig_at_end” attribute block, you can see that we have indicated that this block of code incorporates rules from two different sections of the act.

So let’s take another look at the rule block and go through it line by line.

The conclusion means “an object, which we will call ‘A’ should have its ‘validly signed by maker’ attribute set to ‘true’, if the following things are true.” The conditions then set out the requirements of the section, and link the different pieces of information in the ontology to one another.

Our code double-checks that the objects are of the correct type, which is a good practice, but we can skip over the “is in the Category” blocks to get a clearer understanding of what the rule says. It says:

  • An object, which we call A, is a Personal Directive
  • A has a Signature, which we will call B
  • A has a Maker, which we will call C
  • A has a Witness, which we will call E
  • the signature B is signed at the end
  • the role of the signature B is “Maker”
  • the signature B has a signor (the person who signed) which we will call D
  • The Maker of the directive, which we call C, and the signor for the Maker, which we call D, are the same object (in this case, the same person)
  • The witness, who we call E, was present at the signature we call B

This is a very good example of how a very short statement in a statute can hide a complicated structure underneath. To a person “signed at the end by the maker in the presence of a witness” seems quite straightforward.

Now we need to encode the other option, where a person’s personal directive is signed for them by someone else. This section looks very similar to the one above, but adds a few changes. First, it checks to see that the maker is a person who is physically incapable of signing. Second, it negates the test to make sure that the maker and the signor for the maker are the same person, instead checking to make sure they aren’t. Third, it adds the requirements that the signature be on behalf of the maker and at the maker’s instruction. Fourth, it checks to make sure that the maker was present at the time of the signature, in addition to the witness.

Next we are going to encode section 5(1)(d), which discusses whether the personal directive was validly witnessed. This turns out to be surprisingly complicated. The text of the section in context is:

5(1)  A personal directive must

                           (d)    be signed by the witness referred to in clause (c) in the presence of the maker.

We will need to reformulate that in order to understand what exactly it requires in terms of our ontology. A “witness referred to in clause (c)” is a person who was a witness to the signature that satisfied the requirements of validly signing the personal directive, whether that was the signature of the maker, or the signature of someone else.

Here is another implicit concept in the Act – “the signature which satisfied the requirements of 5(1)(c).” We don’t have that in our ontology, so we can’t refer to it. If we don’t add it, we’re going to have to re-do all of the code for valid signatures inside the code for valid witnesses.

So let’s add it, and let’s change the two validity rules so that they set the valid attribute, but they also record WHICH signature was valid.

So first we add the attribute to the personal directive category:

Now we modify the two rules for valid signatures to set that attribute in their conclusions:

And similarly:

Now we can check to see if the witness is valid by checking to see if they were present for the pd_valid_signature.

Again, this is relatively complex, considering what we started with. Skipping the category checks, it can be read as follows:

A personal directive is validly witnessed if:

  • It has a witness we will call B
  • It has a maker we will call C
  • It has a signature we will call D
  • The role for that signature is “Witness”
  • The signor for that signature is the witness we call B
  • The maker C was present for the signature of the witness as witness
  • The personal directive was validly signed by a signature we call E
  • The witness was present for the signature E

Encoding Section 5(2)

Section 5(2) reads as follows:

(2)  The following persons may not sign a personal directive on behalf of the maker:

                           (a)    a person designated in the directive as an agent;

                           (b)    the spouse or adult interdependent partner of a person designated in the directive as an agent.

So this is going to require us to enhance our ontology again. First, we need to be able to speak about the people designated as agent in a personal directive. Second, we are going to need to be able to talk about spouses and adult interdependent partners.

For simplicity, we will combine the two categories of spouse and adult interdependent partner (which is what the Province of Alberta calls “common law” relationships), into a single category we will call “spouse.”

The Personal Directive ontology changes to look like this:

And then we update the ontology for “Person” so that “spouse” is an attribute.

So now we have what we need to specify the rule. The rule essentially means that even if the personal directive is validly signed on behalf of a maker, it is not validly signed if the person doing the signing falls into these categories. So it is an exception to a general rule. We will write it as a rule, and a block that specifies the rule that it overrides.

So this rule states that the validly signed attribute is false if:

  • the personal directive, which we call A, has a signature we call B
  • The role of the signature B is “Maker”
  • the signor of B is a person we call C
  • the personal directive A has agents we call D
  • the personal directive A has a maker we call F
  • The maker and the signor are not the same person
  • and either an agent is the signor
  • or the agent has a spouse who is the signor

It might not be clear why, in this rule, we need to check to see that the person who signed for the maker and the maker are not the same person, if the only thing it affects is whether it was validly signed by someone other than the maker. One reason is that if the maker has signed for themselves, and the maker is listed as an agent, the personal directive is not therefore “invalidly signed by another person”.

Once we have this rule, we indicate that it overrides the general rule setting out valid alternative signings.

Encoding Section 5(3)

The last section to encode is the section which sets out who may not be a witness. Similarly to section 5(2), we will encode this as a rule that makes the witnessing invalid, and overrides the rule which made the witnessing valid.

Luckily, we have all the ontological concepts we need, so we can go straight to the rule.

This is a very long rule, which encodes all of section 5(3). Reading from the top and skipping the category checks, it says that a personal directive is not validly witnessed if:

  • it has a witness we call B, and one of the following is true:
  • the pd has agents, and the witness B is one of them
  • the pd has agents, who have spouses, and the witness B is one of the spouses
  • the pd has a maker, who has a spouse, and the witness B is the spouse of the maker
  • the pd has a person who signed for the maker, and the witness B is that signor
  • the pd has a person who signed for the maker, that person has a spouse, and the witness B is that spouse

You will notice that variables like “C” are re-used between the different options. Because they are separated by “or” statements, the “C” referred to in one option will never be compared to the “C” referred to in another option. You can safely re-use the variable names in that context.

But the variables “A” and “B”, because they are used “outside” the or blocks, are the same everywhere.

One of the unfortunate parts of this demonstration, and something that we have on the feature list for future versions of Blawx, is the way that you get access to a list of more than two disjunctions by nesting “or” blocks. It works, but it just isn’t very pretty. We’re working on it.

Having set out the rule, we now have to specify that it overrides the default.

Conclusion

That’s it. I hope that helps you to understand what using Blawx for Rules as Code would look like.

Here are a few take-aways:

  • The process of building an ontology to represent the rules in a law often requires you to make explicit concepts that are implicit in the law, like “compliance with section X”.
  • Sometimes it will make sense to break complicated rules into parts, which may also require adding intermediate legal conclusions that are only implicit in the actual law.
  • Blawx’s override features means you don’t need to reformulate as often as in tools that don’t support reformulation. But you will occasionally want to re-formulate the law and move requirements from one section of the law to another, usually to simplify the code. When you are doing that, you need to make sure you are documenting it in comments so later the relevant sections of the code can be easily found.
  • Not everything can be helpfully encoded. That’s fine. Just do what helps.
  • There is a lot of flexibility in how you model legislative concepts. Sometimes complicating things at the ontology stage (e.g. adding the idea of a signature object), makes it easier to express complicated ideas later (e.g. “present at a signature”).
  • Encoding a law is an iterative process. What you need to say about one rule can change based on what you need to know to make it easier to encode later rules. You go back and forth between rules an ontology until you have something that works.

There are a lot of parts of the process that we haven’t described, here. This example doesn’t touch on testing, on data integration with different applications, or on dealing with unknown data and getting useful information for your app.

I’m hoping to cover those and more issues in the future. Stay tuned!

Want to Help?

Blawx is now an open source project, hosted at GitHub. If you are a developer, an aspiring legal engineer, a legislative drafter, a Rules as Code enthusiast, or any other manner of helpful individual, don’t hesitate to offer feedback, feature ideas, or even code!

Thanks for your support!

No Comments

Add your comment