Rule Templates

A successful general purpose technology is one that is not only flexible, but is also easily modified to fit specific usecases. This document is intended to examine how to best accommodate specificity within the authoring process utilizing an Xalgo Rule Template (XRT) document.

Let me start by defining the problem space.

Context Need Idea
The XRM authoring panel will be used by people across usecases. For specific authorship needs (such as requiring instructions in another language, authoring a rule within a specific industry context), the user will require custom inputs and labels (dropdowns containing specific industry terms, pre-populated hinting, custom labels, improved field descriptions, etc) Make customization of the XRM assembly panel simple by deriving input variables from a selected template document.
Have template folder in the root of the XRM dev application to store template files.

What Can a Template do?

Over time there has been some back and forth on what specific role the template serves and how much information it contains. As of now the template exists as a make-shift CMS, storing information about rule fields for the XRM dev application. However, its utility is limited. The file is hidden in the back end, and it is the singular source of truth regarding rule authoring fields (i.e. changes to this document will be persistent across all authoring panels).

Unfortunately, only being able to utilize this template limits the flexibility of the assembly panel and reduces its general purpose capacity. For example, a pencil manufacture may require specific terms to be uniform across all the rules they author. They would require a template that the author can utilize that enforces these limitations.

Importantly, an author will likely need to make use of multiple templates (the data structure of the template is not changing, only the input preferences) from a single instance of XRMLooking at it from this angle, we can see that templates can serve a role similar to templates (though their functionality extends beyond that of a template). Moreover we can see that template documents can begin to serve as “Smart Contract Templates,” as described by James Hazard of Common Accord. From this it becomes clear that a template folder is required in the root of the XRM dev application where the developer can store template files for use in the IDE.

Custom Template Specifications

In the forthcoming Oughtomation paper, Joseph Potvin outlines the specifics of the template used in the XRM dev interface. All valid extensions of the XRM dev template will be derived from the fields outlined here. In fact, the template data structure will remain unaltered, with the developer adding objects to describe only input and label instructions for assembly panel.

For an example, let’s return to the pencil manufacturer. As employees author rules, they begin to realize that they are using the same four UNSPSC fields over and over again. For the authors it is difficult to remember the codes, and it is frustrating to look them up repeatedly. The developer who deployed XRM for the organization decides to add a pencil-manufacturing-template document to the templates folder that will provide them with a dropdown containing the four UNSPSC codes used by the organization.

The file contains the following:

// pencil-manufacturing-template.json
"item.classification": {
    "label": "UNSPSC Code",
    "description": "Choose the product involved in this rule",
    "type": "array",
    "options": [
        {"label": "Pencil or pen grips", "value": "44121707"}, 
        {"label": "Colored pencils", "value": "44121707"}, 
        {"label": "Wooden pencils", "value": "44121706"}, 
        {"label": "Mechanical pencils", "value": "44121705"}

To accommodate common uses, the input object will likely require the following argumentsI was inspired by these Sanity template arguments for Studio construction.

  1. label accepts strings and is used to specify the input label.
  2. description accepts strings and is used to specify the input description.
  3. hint accepts strings and is used to specify the input hint.
  4. typespecifies the kind of inputs and accepts the following arguments
    • array A drop down
    • string Text string input
    • static Non-editable field
    • date/time Only needed in two instances, so not sure if it should be included
    • range Only needed for “output purpose”, so not sure if it should be included
    • custom It seems like a good idea to have the option include a custom input function, but may have unintended consequences. This could be used to accommodate the range and date/time inputs that are used in rare instances. It could also be used to build better hinting systems, etc.
  5. options accepts an array of options for dropdown choices.

The Rule Assembly Panel

In order to accommodate the arguments of extended rule templates, the front end will have certain variable characteristics. Primarily an input component will be needed to take arguments from the template about input types.

This introduces a key constraint. Before navigating to the rule assembly panel the user will need to select what template they are using. Alternatively they may opt to use the default template—the template currently implemented in XRM dev. I will write up a short document thinking through the UX of this action.

Why Adopt This Feature

This question of custom interfaces has come up in multiple conversations, both with core contributors and with those interested from a distance. Given the common nature of this problem, and the face that such a feature will make XRM dev more general purpose, I strongly advocate that this approach is used in the next generation of the software.


From the default XRM dev there should be a way to search for existing published templates. I’m not sure how this is best accomplished. Perhaps there can be a designated repo where contributors add templates.

It may make sense to add a field to the XRS indicating the address of the template used. I’m not sure if this is needed, but may prove useful.

Table editor features are still not explored

The ability to link to a table for the contents of array may be useful for complex hinting.

20 Sept 2021

Calvin Hutcheon