Using JSON Schema to Define Bill of Materials for Work Standardization

In IT organizations, the unit of work is the change request or ‘ticket’. Their representation depends usually on the ticketing system used. The challenge in effective ticketing is two-fold:

• enabling clear communication between the ticket requester and the IT team
• being flexible enough to handle different varieties of work

You want to be able to ask for something from IT without a back and forth dialogue before work starts. That’s usually a sign of a broken process and is certainly is wasteful.

The Phoenix Project argues that running an IT organization is the same as running a manufacturing plant. Let’s take a page from their playbook, shall we?

From Wikipedia:

A bill of materials or product structure (sometimes bill of material, BOM or associated list) is a list of the raw materials, sub-assemblies, intermediate assemblies, sub-components, parts and the quantities of each needed to manufacture an end product.

Meaning if we expressed our types of tickets in terms of the required information needed up-front, the requester will know how to ask to get something done and the IT team will be able to do it right the first time! Win-win!

Ticket systems like Jira are very powerful in that you can create different issue types with customizable fields that can be marked as required which enable you to establish a BOM for each type of work. There are some big drawbacks, however. Jira configuration isn’t version controlled so you can’t see changes over time. If you are using APIs to automate issue creation, required fields constrain their use since you have to bring awareness of them into your code. The situation gets worse as the types of work increase in number and complexity. If a ticket type changes without your knowledge, your code will break!

If you are facing this problem, here’s my advice: if you want to support various types of work in your ticket system, decouple their specification from your ticket system entirely. Make your ticket types uniform and allow their content be free-form.

The next challenge then is to express a BOM in a way external to your ticket system but powerful enough to ensure you get high-quality tickets.

Enter JSON Schema. With it you can define the form of a type of work and even get programmatic validation. Here’s an example for a ticket type that requires a hostname and an EC2 instance type, and even have descriptions of what each field means.

{
  "schema": {
    "hostname": {
      "title": "Hostname",
      "description": "The FQHN of the new server",
      "type": "string"
    },
    "size": {
      "title": "Server Size",
      "description": "an EC2 instance type ",
      "type": "string",
      "enum": [
        "m1.small",
        "m1.large",
        "m1.xlarge"
      ]
    }
  }
}

Basic types include strings, integers, and enums. You can mark certain fields as required, and you can even provide regular expression matching as well!

A benefit of JSON Schema is that there are open-source projects to render them into HTML forms. I personally have used JSONForm, however Schemaform is a recent addition as well.

Building a custom ticket frontend or API using this allows you to specifically define what is required to get work done while having the freedom to format the actual tickets in a way that is understandable by your IT team. Also, by decoupling it from your ticketing system, you have the choice to handle requests in a purely automated fashion in the future rather than simply tracking the request to be done by hand later.

I hope this helps inspire people take control of the flow of work into their teams!