Architecture decision records reference

View as Markdown

---

This page lists the fields, paths, and routes supported by architecture decision records.

Paths

ADRs can be created in any adrs folder:

/adrs/{ADR Name}/index.mdx
/domains/{Domain Name}/adrs/{ADR Name}/index.mdx
/systems/{System Name}/adrs/{ADR Name}/index.mdx

Versioned ADRs use:

/adrs/{ADR Name}/versioned/{version}/index.mdx

Routes

Route	Description
/docs/adrs/{adr-id}/{version}	ADR documentation page.

Required fields

id

• Type: string

Unique id of the decision record. EventCatalog uses this for URLs and resource references.

Example

---
id: adr-001-use-event-driven-checkout
---

name

• Type: string

Display name of the decision record.

Example

---
name: Use event-driven checkout
---

version

• Type: string

Version of the decision record.

Example

---
version: 1.0.0
---

Optional fields

status

• Type: proposed, accepted, rejected, deprecated, or superseded

Lifecycle status for the decision.

Example

---
status: accepted
---

date

• Type: date

Date the decision was created or recorded.

Example

---
date: 2026-06-01
---

summary

• Type: string

Short summary shown in lists and search.

Example

---
summary: Checkout will publish domain events for downstream fulfilment.
---

owners

• Type: array

Teams or users that own the decision record.

Example

---
owners:
  - architecture-team
---

decisionMakers

• Type: array

Teams or users that made or approved the decision.

Example

---
decisionMakers:
  - architecture-review-board
---

appliesTo

• Type: array

Resources affected by this decision.

Example

---
appliesTo:
  - type: system
    id: checkout-system
---

supersedes

• Type: array

Decision records replaced by this decision.

Example

---
supersedes:
  - id: adr-000-old-checkout-design
---

supersededBy

• Type: array

Decision records that replace this decision.

Example

---
supersededBy:
  - id: adr-004-new-checkout-design
---

amends

• Type: array

Decision records amended by this decision.

Example

---
amends:
  - id: adr-002-payment-routing
---

amendedBy

• Type: array

Decision records that amend this decision.

Example

---
amendedBy:
  - id: adr-005-payment-retry-policy
---

related

• Type: array

Related decision records.

Example

---
related:
  - id: adr-003-order-events
---

badges

• Type: array

Badges rendered on the decision record page.

Example

---
badges:
  - content: Accepted
    backgroundColor: green
    textColor: green
---

Applies to

Use appliesTo to link the decision to resources.

---
appliesTo:
  - type: system
    id: checkout-system
  - type: service
    id: payment-service
  - type: event
    id: PaymentAuthorized
---

Supported resource types include agent, service, system, event, command, query, flow, channel, domain, user, team, container, entity, diagram, and data-product.

Custom properties

You can add organization-specific metadata to this resource using frontmatter fields prefixed with x-. Learn how to define, render, and reference them in Custom properties on resources.