Whitepaper: Blawx for Rules as Code – A Roadmap

Whitepaper: Blawx for Rules as Code – A Roadmap

Recently, particularly in commonwealth countries of the world, there has been increasing interest among public servants, including legislative drafters, regulators, and service delivery experts, in the concept of “Rules As Code.”

Rules as Code is one part of a larger conversation about how legislation, regulation, policy, and other formal rules can be made more effective. One of the insights from that conversation is that encoding rules at the time they are drafted in natural languages has two positive effects: it makes those rules easier to implement in automated systems, and it make the rules objectively better at achieving their policy objectives, for various reasons.

Whether drafting rules in code at the same time as drafting them in a natural language, or encoding existing rules as a Rules as Code experiment or for the purpose of automating the provision of a service, Blawx has features that make it well suited for use in Rules as Code.

This post will set out some of Blawx’s features that make it helpful in a Rules as Code project. It will also set out some features that may be added to the open source tool in the near future. Finally, it will talk about some features that could be added to a hypothetical commercial version.

This document is intended to be helpful to people who are considering whether to include Blawx in Rules as Code experiment projects, potential contributors who want to understand the direction for the open source project, and potential investors interested in funding the development of a commercial version.

Current Features

Declarative Logic Programming

Blawx is a tool for declarative logic programming, which means that rather than setting out data, and a sequence of steps for modifying that data, you set out data and a set of rules that can be used to draw inferences from that data.

This is useful in the Rules as Code space because it allows the people encoding the rules to translate them to code without having to reformulate them as processes first.

Open Source

In the public sphere there is a great deal of emphasis on accountability and transparency. If Rules as Code were used to make decisions or guide citizens, it would be important that we could tell how. Blawx is an open source software project. If you want to know exactly what is being done under the hood, you can just look.


One of the benefits of the Rules as Code idea is that it would be possible to have trusted encodings of rules, and re-use them in different contexts. Blawx allows you to do this by saving your workspace as a .blawx file, making that file available on the internet, and then allowing other workspaces to reference that code using “include” blocks.

This allows the encoded rules to be separate from the application (as in use) to which they are being put. It allows quality assurance to be done against the rules themselves, as opposed to applications. And it allows rules to be updated in a central location and the changes applied across multiple different apps automatically.

Access over API

Blawx currently has a simple API that allows you to send facts and rules and queries to the Blawx.com Reasoner, and get answers to your questions. A connector to take advantage of this reasoner API from inside Docassemble online interviews has also been released as an open source tool. This makes it possible for Rules as Code experiments to demonstrate how encoded rules can be used inside other, client-facing applications.

Defeasibility Increases Isomorphism

Blawx has features for allowing some rules to override other rules inside the code. This allows for greater isomorphism between natural language rules and their encoded equivalents, which simplifies the process of encoding rules and also simplifies the process of maintaining encoded versions when the natural language rules change.

In addition to making the code easier to write and maintain, isomorphism increases the degree to which the encoded rules are readable by the subject matter experts who help to develop them. That may increase the confidence that the non-programmers have in the code, and increase their support for the use of the technology.

Ease of Use

Blawx is a visual programming environment based on Google’s Blockly. This creates two advantages for people who want to learn to use the tool. First, certain kinds of syntactic errors are impossible to make when encoding in Blawx, because if you try to make them the “pieces don’t fit.” This makes explicit some information that is usually implicit and not known until compile time with other programming tools.

Second, Blawx automatically updates its own toolbox on the basis of the categories and attributes and objects that are defined by the user. This allows the initial user interface to be very simple, and for it to become more complicated only when and as the user adds to the vocabulary that can be used.

Long term, this ease of use may also make it feasible to have non-programmers responsible for the encoding and maintaining of encodings of legislation. In the literature surrounding the use of legal expert systems it is acknowledged that the “knowledge acquisition bottleneck” is the major obstacle to the adoption of these tools. The knowledge acquisition bottleneck is the name given to the problem that having a subject matter expert and a programmer sit down together in an effort to put what the expert knows into code is slow, prone to error, and expensive.

By focusing on making the task of encoding easy, Blawx provides an environment in which it might be possible to avoid the bottleneck by having the subject matter expert and the coder be the same person. By analogy, accountants no longer rely on programmers in order to digitize their financial models. Electronic spreadsheets have made it possible for accountants to use computers for that purpose without the assistance of programmers. Blawx aims to do the same thing for legal reasoning.

Roadmap Features

There are also a number of features that are on the roadmap for Blawx that may make it well suited to certain rules as code applications. All of these features are in addition to the objectives of enhancing the usability of the current interface, and fixing bugs and known issues.

Additional Data Types and Functions

Work is underway to add additional datatypes to Blawx and related functions. Currently Blawx deals only with numbers, text, and true or false values. High priority additions include:

  • dates, times, and durations
  • floating point numbers
  • currency

Co-Drafting Features

“Co-drafting” is sometimes used among Rules as Code proponents to describe the process of drafting rules in natural language and code at the same time. Work is underway on changes to the Blawx interface that would allow side-by-side natural language rules and encoded rules, and allow the user to associate encoded rules with their natural language sources in a way that would simplify finding correlates. The same features would also be useful for the translation of existing rules to code.

Standards-Compliant External Data Sources

Blawx’s existing API data interface features use a non-standard JSON-like syntax. We are working on changes to that interface to make it standards compliant, and make it easier for people to build connectors for the Blawx API.

Unnamed Objects

Blawx’s data system is currently capable of creating objects without naming them, but these unnamed objects are complicated to use inside rules. We would like to add features to the interface to make it easier to use unnamed objects, which would in turn make it easier to deal with external data sources.

Testing Features

We would like to document processes that can be used for easy testing of code in Blawx. Testing is currently possible, but requires the explicit construction of data in a complex hierarchical structure, and is therefore time-consuming.

Silent Variables

Currently, if a variable is included in a query will be reported in the results of that query, regardless of whether it is what the user is interested in finding out. Silent variables will allow the user to use a variable but have it not be included in the results.

Debugging Features

Currently, the only way to know whether you have made an error in your Blawx code is to run it, and see if it behaves as expected. In the future we want to add certain syntax-checking methods to the interface that will point the user to incomplete statements and other simply problems that can be detected prior to run-time.

Currently very little input validation is performed on the information placed in text fields in Blawx. That needs to be improved, and techniques that rely on that lack of input validation (such as the current methods for creating objects from unnamed data) need to be replaced.


Currently, getting your own version of Blawx up and running in a development environment is challenging. We are actively focused on simplifying that process by containerizing Blawx into a docker configuration. This will allow people who want to use Blawx on their own servers, instead of at Blawx.com, to do so quickly and easily.

Possible Commercial Features

In addition to features that are anticipated for the open source version, there are a few desired features that could be implemented in a potential future commercial version of Blawx. These features are possible, but not currently planned.

These features would be cross-compatible with the open-source version. Code written in one could be used in the other.

The reasons for categorizing these proposals as commercial vary. Some are not currently possible (or easy) to implement without the addition of proprietary software with licensing requirements. Others would require the use of costly resources. Others merely go beyond what I’m willing to commit to building, but could theoretically be added to the open source version by sufficiently-motivated contributors.


This would add a “why” block to the interface, allowing the user to ask Blawx’s reasoner to provide an explanation for how it came to a conclusion with regard to a specific query. This explanation can be used as a debugging tool, or to provide application users with an explanation for a legal conclusion.

Natural Language Generation

This would add the ability to specify translations from Blawx statements to natural language statements. These translations would be used inside explanations if available and requested, or they could be used to generate natural language versions of sections of Blawx code.

Cloud Storage and Publication

This would give the user the ability to save their Blawx workspaces to the cloud, rather than downloading them and uploading them to other locations on the web.

Version Control

This would allow users to integrate their blawx workspace with GitHub and other version control tools to allow for better version control of changes to code.

Publish Query as API Endpoint

This would give the user the ability to take a Blawx workspace with a query, and publish that workspace as an API endpoint at Blawx.com. Then, an application that wanted access to an answer to that specific question could access that service without needing to have access to the rule encoding. It would only need to provide data in the correct format. This may be useful in commercial applications where the encoding of the rules is intellectual property.

Access Control

This would give the user the ability to control access to their code and queries online, limiting access to the code via API, potentially allowing people to charge fees on a per-use or subscription basis for access to proprietary encodings and queries.

Integration with OWL

This feature would allow Blawx users to import ontological information from the semantic web and use that information (objects, categories, and attributes) inside the Blawx development environment. This could increase the compatibility of blawx codebases with one another and existing standard legal ontologies, and simplify the process of generating applications where those applications are a) integrated with the Blawx API, and b) rely on the same ontology for a data structure.


It is possible to visualize declarative logic software as a node diagram of related legal concepts. This can facilitate the analysis of complicated legal structures, and make it easier to see, when modifying one part of a set of rules, how those changes might inadvertently impact other sections of the rules.

Integration with XML Representations of Legal Source Material

There are XML standards available for the description of statute law and other legal rules, including Akoma Ntoso, and LegalRuleML. It would be possible to integrate Blawx with these languages either by allowing for cross-references from the code to XML elements of the source or co-drafted rules, or by allowing rules to be exported to or imported from these formats.

This would increase Blawx’s ability to integrate with other legislative drafting tools in development and use around the world.

Additional Reasoning Features: “What Do I Need to Know?” and “How Could I Get There?”

In order to use Blawx code as the source material for online chatbots and interviews, it would be helpful to have a facility to pose questions to the reasoner like “what would I need to know in order to determine whether this statement is true?” This would allow the development of applications where the rules could be used as the source code for determining what questions to ask the user and in what order, simplifying the task of developing applications that use Blawx rules.

It would also be helpful to be able to ask the Blawx reasoner “which of these facts would need to be different, and how, in order for this statement to be true?” Technically, this would be challenging to implement. This sort of query would allow Blawx rules to be used as the source code for legal validation functionality in other applications. These applications could provide data to Blawx, along with a goal statement, for example “this document is compliant with the regulations.” Blawx would then reply with information on whether that goal was satisfied, why or why not, and if not what facts could be changed, and how, in order to satisfy it. This could advise a person against doing something non-compliant, explain why it is non-compliant, and advise how to make it compliant, all without the application developer needing to know the rules surrounding compliance.


Whatever your interest in Blawx, I hope this document has been helpful in understanding what it does, why, and what it might do in the future. If you require any more information don’t hesitate to contact the author, Jason Morris, at jason@roundtablelaw.ca, or on twitter at @RoundTableLaw.

In particular, if you are a person or organization for whom the commercial version of Blawx sounds like something you would pay to have use of, please get in touch.

No Comments

Add your comment