The YAML ADR Template (YADR): A MADR Port

A previous post featured the MADR template for recording architectural decisions in Markdown. A YAML version of its abstract syntax is available now, called YADR (pronounced similar to “wider”). Let’s find out why it was built, and what to do with the new template rendering.

The MADR Template Revisited

Architectural Decision Records (ADRs) answer “why?” questions. Most ADR templates suggest that the decision context, outcome and its consequences should be recorded. But the considered design options, aka solution alternatives, matter too! Decision drivers should be made explicit, and the consequences usually concern multiple stakeholders — not always positively (tradeoffs!).

Enter Markdown ADR (MADR). Its mandatory template sections are:

• Title
• Context and problem statement
• Considered options
• Decision outcome
  • Identification of chosen design option
  • Justification: rationale for chosen option, reasons to neglect others
  • Consequences: good and bad impact, for all concerned stakeholders

MADR proposes five optional sections: metadata (such as status, date, decision makers and other stakeholders), decision drivers (such as quality goals), pros and cons of the considered options (w.r.t. the drivers, serving as decision input), confirmation (how to check that the design matches the decision), and more information (technical details and references).

The open-source project Operaton gives (M)ADR creation guidance. Its first ADR is “Null Safety Strategy for Operaton”. And the JabRef project has recorded more than 60 architectural decisions in MADR. A recent example is: “Use Apache Velocity as template engine”.

Why YAML?

Just like Markdown, YAML forces you to focus on your content (here: decision rationale) and content organization (structure in particular) rather than its presentation (e.g., font size, page breaks and other formatting issues) while writing. Being plain text, YAML documents can be collaborated upon and version controlled.¹

Unlike Markdown, YAML is a data serialization language. Compared to JSON, YAML comes across as more readable for (most) humans.

Many open source projects and commercial product have decided for YAML as configuration file syntax; specification languages such as OpenAPI support YAML renderings too.

Numerous YAML parsers exist as well as converters, for instance to and from JSON. Text editors support YAML with syntax highlighting and validation. But tools are not mandatory to use.

The YADR Template

Here is a snippet from the YAML port of the MADR template:²

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
title: '{short title, representative of solved problem/found solution}'

context-and-problem-statement: |

  {Describe the context and problem statement, e.g., in free form,  
   two to three sentences, or in the form of an illustrative story. 
   You may want to articulate the problem in form of a question and 
   add links to collaboration boards or issue management systems.}

# this is an optional element:
decision-drivers:
  - '{decision driver 1, e.g., a force, facing concern, …}'
  - ...

considered-options:
  - &id-of-option-1 '{title of option 1}'
  - ...

decision-outcome:
  chosen-option:
    link: *id-of-option-1
    justification: |
      {rationale; e.g.,
        - only option, which resolves driver {force}, …
        - {why other options were not chosen}

All mandatory sections and an optional one are featured in the excerpt.

Note the key-value mappings (indicated by colons :), list items forming sequences (starting with -) and the comment (#). Indentation matters!

Anchors (e.g., &id-of-option-1) are a powerful, less known YAML concept; when aliases reference them (*id-of-option-1), anchors can help avoid redundancy. However, not all YAML tools support them well.

YADR Usage Example and Schema Validation

The YADR repository provides examples. An excerpt from one of them is:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
title: "ADR Syntax (Notation, Meta Model)"

context-and-problem-statement: |

  ADRs primarily target human readers, but machines should also be 
  able to process them. Markdown files can be parsed, there are tools 
  to process them. This has been reported to be tedious.

  * Which notation and format should be used to record ADs?
  * Which meta-model is suited to structure and validate ADRs?

decision-drivers:
- Human readability and understandability, ease of writing
- Machine readability, parsing effort and convenience
- Vitality and size of tool ecosystem for notation, community support
- Stability of notation
- Ability to write rich text

considered-options:
- &madr Markdown with additional semantic anchors
- &json JSON and JSON Schema
- &yaml '[YAML](https://yaml.org/) with JSON Schema validation'

decision-outcome:
  chosen-option:
    link: YAML (*yaml)  
    justification: promising PoC results, YAML goes well with Python

  consequences:
    positive:
    # only one example given:
    - both human and machine readable ADRs
    neutral: []
    negative:
    - design and development required

This excerpt matches the template snippet from above and also features decision drivers and a basic consequences section. Note that option anchors (&yaml) are present, but not used to identify the chosen-option due to missing (or limited support) in some tools.

🤔 How readable do you find the syntax (compared to Markdown and JSON)?

JSON Schema Validation. A JSON schema specifying the template structure is available here. This is a shortened version of it (note: decision drivers and other optional template section not shown):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "title": {
    "type": "string"
  },
  "context-and-problem-statement": {
    "type": "string"
  },
  "decision-outcome": {
    "type": "object",
    "properties": {
      "chosen-option": {
        "type": "object",
          "properties": {
          "link": {
              "type": "string"
            },
            "justification": {
              "type": "string"
            }
          },
          "required": [
            "link",
            "justification"
          ]
}}}}

The YAML mappings (key-value pairs) correspond to JSON objects; the YAML sequences (lists) map to JSON arrays. "required" arrays indicate whether a YADR/MADR section is mandatory or not. The chosen option link is modeled as a string (rationale: interoperability, tool limitations).

JSON renderings of the two YADR examples in the repository are available here and here.³ Copy-paste them into a tool such as this online JSON schema validator to check whether they validate against the JSON schema. For instance, replace a string with an integer or remove a required element to let the validation fail.

You can also generate data classes for many programming languages from the schema, for instance with quicktype. Such data classes typically support conversion from and to YAML, which comes in handy when integrating the ADRs into tool chains.

Summary and Conclusions

Both practitioner articles and academic literature identify essential ADR parts; there even is a standard, ISO/IEC/IEEE 42010:2022. The MADR and YADR template sections take its recommendations into account: context, considered options, decision outcome with consequences; supplemental parts include metadata (such as status), decision drivers (quality attributes in particular), option pros and cons and more information.

YADR keeps the MADR template structure but offers an alternative concrete syntax, which is readable for both humans and machines. YADR instances can be validated and parsed with help from the large ecosystem of YAML libraries and tools.

Try the YADR template out! Feedback is very welcome, for instance, via issues in the GitHub repository.

– Olaf

There is a Medium version of this post.

Acknowledgement. YADR is joint work with Oliver Kopp and Tobias Unger.

Notes.