ISO 25010 Quality Attributes in ADRs — Tagging Decisions for Architecture Governance

Why quality attribute tagging matters for ADRs

An ADR without quality attribute annotation documents what was decided and why in prose, but makes it difficult to answer the organisational question that governance processes ask: which decisions were made to address our security posture? or which decisions carry reliability implications for the upcoming DR test? These are not questions you can answer by reading prose; they require a structured tag that a tool can filter on.

ISO/IEC 25010 (the Systems and Software Quality Requirements and Evaluation standard) provides an internationally recognised vocabulary for software quality characteristics. Using its terminology means the annotations are legible to auditors, architects outside your team, and tooling that understands the standard — not just to the team that wrote the original ADRs.

Three concrete use cases where quality attribute tags pay dividends:

• Pre-governance-review audit. Before an Architecture Board review or SOC 2 assessment, generate "all ADRs tagged security from the last 12 months" as the agenda input. Without tags, someone reads every ADR manually to extract the relevant decisions.
• Architecture change impact assessment. When a new requirement arrives ("we need to achieve 99.99% availability") you can immediately surface all existing ADRs tagged reliability to understand which decisions constrain the path to higher availability — without searching prose for terms like "uptime", "failover", or "circuit breaker".
• New-engineer onboarding. A senior engineer joining the team can filter the ADR directory to "all decisions that affected security or maintainability in the past two years" to understand the architecture posture quickly, without reading every ADR in sequence.

The ISO 25010 quality characteristics

ISO/IEC 25010:2023 defines eight top-level quality characteristics. The table below shows each one, its relevance as an ADR tag, and a worked example of an architecture decision it would annotate:

ISO 25010:2011 vs 2023 naming. Many teams and tooling still use the 2011 names: Usability (now Interaction Capability) and Portability (now Flexibility). The semantic content is largely the same — the 2023 revision refined the sub-characteristics and renamed the top-level characteristics. Establish one canonical set of names in an ADR conventions document and stick to it. The most common mistake is mixing "portability" and "flexibility" across different ADRs because two engineers used different editions of the standard.

Copy-paste frontmatter schema

The following YAML frontmatter block can be added to any Nygard-format ADR that currently lacks frontmatter, or merged into an existing MADR frontmatter block:

---
id: "0042"
title: "Use server-side sessions with HttpOnly cookies for admin dashboard auth"
status: "Accepted"
date: "2026-03-14"
deciders: ["@eleanor-cheng", "@ops-lead"]
supersedes: ""
superseded-by: ""
quality-attributes:
  - security
  - maintainability
tags:
  - auth
  - dashboard
  - session-management
---

Key design choices in this schema:

• quality-attributes is a list, not a single value. Most decisions touch more than one quality attribute. Capping at three prevents every decision from being tagged with every characteristic, which destroys the filtering value. If you are tempted to add four or more, ask: which one or two were the primary drivers of the decision? Tag those. Note the others in the Consequences section as "secondary quality attributes affected: [list]" as prose, not as structured tags.
• Use the full characteristic name, not abbreviations. Tags like perf or sec are not legible to tooling or to new team members unfamiliar with your conventions. Use the canonical lowercase hyphenated names from the table above.
• Separate quality-attributes from tags. The tags field in MADR and most ADR tooling is a free-form taxonomy for searchability (e.g., "auth", "database", "caching"). The quality-attributes field is a controlled vocabulary from the ISO standard. Keeping them separate prevents the quality-attribute list from drifting into a freeform tag set and preserves the ISO standard's interoperability value.

Minimal addition to a Nygard ADR without frontmatter

If your existing ADRs use the Nygard format with an H1 title and H2 Status heading (no YAML frontmatter), add the frontmatter block before the first heading:

---
quality-attributes: [security, maintainability]
---

# ADR-0042: Use server-side sessions with HttpOnly cookies for admin dashboard auth

## Status
Accepted

## Context
...

The YAML frontmatter is invisible in GitHub's rendered Markdown view but is machine-readable by Dataview, Log4Brains (with custom field configuration), and your own jq/grep queries. The existing Nygard structure is unchanged.

Tagging discipline: one to three characteristics, primary drivers only

The most common mistake when introducing quality attribute tags is over-tagging. An ADR describing the decision to use PostgreSQL over MongoDB touches performance-efficiency (query patterns), maintainability (team familiarity, tooling ecosystem), reliability (replication, ACID guarantees), and arguably compatibility (existing tooling expecting relational schemas). Tagging all four produces a tag set that is useless for filtering — if most decisions are tagged reliability, the reliability filter returns almost the entire ADR directory.

The useful question to force a single-characteristic tag: if you had to choose one quality attribute that, if it were not a concern, would have led to a different decision — what is it? For the PostgreSQL vs MongoDB example, if reliability were not a concern (if the team were building a prototype with no uptime SLA) the decision might have been different. That is the primary tag. If the team's primary driver was "the team knows SQL and will write better queries faster", the primary tag is maintainability, not reliability.

A practical tagging discipline for retrospective ADRs (common when extracting decisions from AI chat history): read the trade-off sentences in the Consequences section, identify the one or two quality attribute categories the negative consequences belong to, and use those as the tags. The negative consequences are where the real trade-off language lives — the positive consequences often flatter every quality attribute ("it's faster, more secure, and easier to maintain") while the negatives point to the characteristic the decision sacrificed.

Querying by quality attribute

Dataview in Obsidian

For teams using Obsidian for ADR drafting, the Dataview plugin reads YAML frontmatter and allows quality-attribute queries across the decisions/ folder:

-- All security-tagged ADRs, newest first
TABLE status, date, deciders
FROM "decisions"
WHERE contains(quality-attributes, "security")
SORT date DESC

-- Count ADRs per quality attribute (governance inventory)
TABLE length(rows) AS count
FROM "decisions"
WHERE quality-attributes != null
GROUP BY quality-attributes

-- ADRs tagged both security and maintainability
-- (decisions where security and maintainability were co-drivers)
TABLE status, date, title
FROM "decisions"
WHERE contains(quality-attributes, "security")
  AND contains(quality-attributes, "maintainability")
SORT date ASC

The third query is particularly useful for governance reviews: decisions where two quality attributes were co-drivers are often the most complex trade-offs and the ones most likely to be revisited or superseded.

jq recipe for ADR directories without Obsidian

If your ADRs are Markdown files in a git repository without Obsidian, a two-step pipeline using yq (YAML processor) and jq generates the same inventory:

#!/usr/bin/env bash
# Emit a JSON array of {file, status, quality_attributes} for all ADRs
for f in doc/decisions/*.md; do
  yq e '{"file": "'"$f"'", "status": .status, "qa": .quality-attributes}' \
    --front-matter=extract "$f"
done | jq -s '
  group_by(.qa[])
  | map({
      attribute: .[0].qa[0],
      count: length,
      accepted: [.[] | select(.status == "Accepted")] | length
    })
  | sort_by(.count) | reverse
'

The output is a frequency table of quality attributes across all ADRs with a breakdown by accepted vs. proposed. Run this before an architecture governance review as a one-minute inventory of which quality areas have the most decision history.

GitHub Actions CI enforcement

Add a check to the ADR GitHub Action that validates quality-attributes are present on all Accepted ADRs:

- name: Check quality-attributes on Accepted ADRs
  run: |
    VALID_QA="functional-suitability performance-efficiency compatibility \
      interaction-capability reliability security maintainability flexibility"
    for f in doc/decisions/*.md; do
      STATUS=$(yq e '.status' --front-matter=extract "$f" 2>/dev/null || echo "")
      QA=$(yq e '.quality-attributes | join(",")' --front-matter=extract "$f" 2>/dev/null || echo "")
      if [ "$STATUS" = "Accepted" ] && [ -z "$QA" ]; then
        echo "ERROR: $f is Accepted but has no quality-attributes field"
        exit 1
      fi
      for attr in $(echo "$QA" | tr ',' '\n'); do
        if ! echo "$VALID_QA" | grep -qw "$attr"; then
          echo "ERROR: $f has non-standard quality attribute '$attr'"
          exit 1
        fi
      done
    done

This check has two jobs: it enforces that no ADR graduates to Accepted without a quality attribute tag, and it enforces that the tags use only the eight canonical ISO 25010 characteristic names (no drift into "perf", "availability", or "UX" variants).

Integration with arc42 and TOGAF

arc42 section 10 — Quality Scenarios

In arc42, quality attributes are addressed in section 10 (Quality Requirements), which contains a quality tree of attributes and specific quality scenarios. ADRs in an arc42 context live in section 9 (Architecture Decisions). The natural integration is to add a quality-attributes frontmatter field to your arc42 ADRs (section 9) and reference the corresponding section 10 scenario ID in the ADR's Context section:

## Context
Quality scenario QS-004 (Security / Accountability): all administrative operations
on user data must produce an audit log entry attributable to the acting user,
with no pathway for an administrator to suppress or modify the audit trail after
the fact. This constraint is triggered by our SOC 2 Type II certification requirements.
See arc42 section 10 for the full scenario definition.

The quality-attributes: [security] frontmatter tag then makes this ADR retrievable in the "all security decisions" query, while the inline reference to QS-004 satisfies the arc42 traceability requirement from ADR to quality scenario.

TOGAF Architecture Requirements Specification

TOGAF's Architecture Requirements Specification (ARS) catalogues quality requirements with unique IDs (QR-001, QR-002...). For TOGAF-aligned teams, the recommended pattern is to add a requirements field alongside quality-attributes:

---
quality-attributes:
  - security
  - maintainability
requirements:
  - QR-003
  - QR-007
---

The quality-attributes field works as a human-navigable category filter; the requirements field provides the audit-defensible traceability link that TOGAF governance auditors look for when they ask "show me the decisions made to satisfy QR-003". See the TOGAF ADR template page for the full seven-field frontmatter schema including EA Domain and ADM Phase alongside quality attribute annotation.

Sub-characteristics: when to go deeper

ISO 25010 defines sub-characteristics under each top-level characteristic. For Security: Confidentiality, Integrity, Non-repudiation, Accountability, Authenticity, Resistance. For Reliability: Faultlessness, Availability, Fault Tolerance, Recoverability. For Maintainability: Modularity, Reusability, Analysability, Modifiability, Testability.

Most engineering teams should not tag at the sub-characteristic level until they have at least 30 to 50 accepted ADRs tagged at the top-level characteristic. The value of sub-characteristics is in distinguishing "this security decision was about confidentiality (encryption at rest)" from "this security decision was about non-repudiation (audit trail)". At low ADR volume, the top-level tag already disambiguates enough for the queries that matter.

Teams that do operate at the sub-characteristic level should add a secondary field rather than replacing the top-level field:

---
quality-attributes: [security]
quality-sub-attributes: [non-repudiation, accountability]
---

This preserves backward compatibility with all queries using the top-level tag while adding finer-grained filtering for governance reports that need to distinguish sub-characteristic clusters.

Quality attribute comparison: ISO 25010 vs custom tagging

Why this matters for retrospective decision capture

The quality-attributes tag is especially powerful for teams adopting ADRs retrospectively — when the architecture already exists and decisions are being documented after the fact rather than at decision time. In retrospective ADRs, the quality attribute is often clearer than it was at decision time: you know which trade-offs actually materialised, which constraints proved binding, and which quality attribute you sacrificed to ship on time.

When teams use the WhyChose extractor to surface decisions from ChatGPT or Claude chat history, the extracted records include the trade-off sentences from the conversation. Those sentences are rich with quality attribute signals: "we went with SQLite because the operational complexity of running a full Postgres in every deployment environment is not worth it at current scale" signals maintainability as the primary driver. "We chose the stateless JWT approach despite the logout-everywhere limitation because the read-path latency improvement from eliminating the session lookup was essential" signals performance-efficiency as the primary driver and security (non-repudiation) as the sacrificed quality.

A downstream LLM classification step — or a human reviewer taking five seconds per record — can tag the extracted decisions with the ISO 25010 characteristic before the ADR is graduated to the decisions/ directory. This means teams adopting ADRs retrospectively can have a quality-attribute-tagged ADR inventory within a few weeks rather than re-reading years of code history to infer which quality pressures shaped the architecture.

Get early access

Related questions

Further reading

• ADR template in Markdown — copy-paste ready — the base template to which you add the quality-attributes frontmatter field. Includes the full Nygard section structure and the minimum viable frontmatter schema.
• The Nygard ADR template (2026 edition) — the original five-section format most compatible with adr-tools and the ADR GitHub Action. Explains where YAML frontmatter fits into the Nygard format without breaking the original template structure.
• TOGAF ADR template — mapping decision records to Phase H and the Architecture Repository — the full seven-field frontmatter schema for TOGAF-aligned teams, including EA Domain, ADM Phase, and requirements traceability fields that pair with quality-attributes.
• ADR template in Obsidian — Dataview queries, auto-numbering, and the supersession Canvas — the Obsidian vault setup that makes quality-attribute Dataview queries work; covers YAML frontmatter schema, Dataview plugin setup, and the wikilinks-off setting for compatibility with adr-tools.
• Architecture decision record best practices — what actually works after year one — the consolidated best practices reference; includes guidance on which fields earn their weight in the ADR template and which add ceremony without value, directly applicable to deciding whether to add quality-attributes tagging to your team's practice.
• ADR review checklist — what to look for before merging an architecture decision record — the 12-item checklist for ADR PR review; the quality-attributes field is an optional addition to the Traceability category that pairs with the PR or issue link check.
• The open-source extractor — reads ChatGPT or Claude exports and surfaces decision records as Nygard-compatible Markdown. Extracted records include trade-off prose that enables downstream quality attribute classification before ADR graduation.