YAML Frontmatter
Machine-parseable metadata for tooling integration. Filter, search, and query your decisions programmatically.
Structured MADR
Structured MADR is an extension of MADR (Markdown Architectural Decision Records) that adds YAML frontmatter for machine-readable metadata, comprehensive option analysis with risk assessments, and required audit sections for compliance tracking.
Why Structured MADR?
Section titled “Why Structured MADR?”Traditional ADR formats were designed for human readers. While they capture decisions effectively, they lack machine-readable metadata for programmatic access, structured risk assessment for option evaluation, audit trails for compliance verification, and explicit relationships between decisions.
Structured MADR addresses these gaps while remaining fully human-readable and compatible with existing ADR workflows.
Key Features
Section titled “Key Features”Risk Assessment
Evaluate technical, schedule, and ecosystem risk for every considered option with a structured three-dimension model.
Audit Trail
Built-in compliance tracking with findings tables. Meet SOC2, HIPAA, and ISO 27001 requirements.
AI-Ready
Structured metadata enables AI tools like Claude Code, GitHub Copilot, and Cursor to filter, understand, and surface relevant decisions.
Quick Links
Section titled “Quick Links” Getting Started Create your first Structured MADR in under 5 minutes
Schema Reference Complete JSON Schema field reference
GitHub Action Automated CI/CD validation for your ADRs
Templates Full and bare templates ready to use
Why Structured MADR Motivation and ideal use cases
Format Comparison How Structured MADR compares to other ADR formats
At a Glance
Section titled “At a Glance”| Feature | Description |
|---|---|
| YAML Frontmatter | Machine-parseable metadata for tooling integration |
| Hierarchical Drivers | Primary and secondary decision drivers |
| Risk Assessment | Technical, schedule, and ecosystem risk per option |
| Split Consequences | Positive, negative, and neutral outcomes |
| Audit Section | Built-in compliance tracking with findings tables |
| Explicit Relationships | Typed links between related decisions |
Current Version
Section titled “Current Version”- Specification: 1.0.0
- Schema: 1.0.0
- Project: 1.1.0