YAML ADRs (YADR)

YAML is a human-friendly, programming language-independent data serialization language; it is commonly used for configuration files. Its human-friendliness makes YAML suited for the capturing Architectural Decisions in Architecture Decision Records (ADRs) as well.

This repository provides YAML ADR templates and examples.

Content overview

• YAML port of the Markdown Architectural Decisions (MADR) template, as well as a usage example for it.
  • Bare version of the YADR template and shortened usage example.
  • JSON conversions of the YADR usage examples validate against the JSON schema¹ for the template.²
• The folder other YAML templates contains YAML ports of templates not originating from the MADR project, for instance, the Y-Statement template.
  • An example and two corresponding JSON conversions are available as well.

Background information and tools

• Homepage of the ADR organization on GitHub
• Markdown ADR (MADR) project with four variants of the MADR template versions (minimal and full, bare and commented with usage instructions)
• Olaf Zimmermann blogs about architectural decision making and capturing:
  • Patterns and anti patterns for ADR creation
  • Architectural decision making fallacies and biases
  • "The Markdown ADR (MADR) Template Explained and Distilled"
• YAML: YAML homepage, YAML specification and YAML best practices
• One of many online JSON schema validators and a sample YAML to JSON converter

Footnotes

1. Note that this schema has been designed to validate all array elements, which requires the type definitions of the array elements to be scalar. See answer 1 to the question "How do I make a jsonschema so that it validates all objects in array?" on Stack Overflow for rationale. ↩

2. The template contains a placeholder id-of-option-1 for the option name in its pros-and-cons-of-the-options object. The JSON schema contains an additionalProperties object so that options pros and cons are validated properly. ↩