# Architecture decision records reference

Copy as Markdown[View as Markdown](/docs/development/guides/resources/adrs/reference.md)

***

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

## Paths[​](#paths "Direct link to 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[​](#routes "Direct link to Routes")

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

## Required fields[​](#required-fields "Direct link to Required fields")

### `id`[​](#id "Direct link to 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`[​](#name "Direct link to name")

* Type: `string`

Display name of the decision record.

Example

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

### `version`[​](#version "Direct link to version")

* Type: `string`

Version of the decision record.

Example

```
---
version: 1.0.0
---
```

## Optional fields[​](#optional-fields "Direct link to Optional fields")

### `status`[​](#status "Direct link to status")

* Type: `proposed`, `accepted`, `rejected`, `deprecated`, or `superseded`

Lifecycle status for the decision.

Example

```
---
status: accepted
---
```

### `date`[​](#date "Direct link to date")

* Type: `date`

Date the decision was created or recorded.

Example

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

### `summary`[​](#summary "Direct link to summary")

* Type: `string`

Short summary shown in lists and search.

Example

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

### `owners`[​](#owners "Direct link to owners")

* Type: `array`

Teams or users that own the decision record.

Example

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

### `decisionMakers`[​](#decisionMakers "Direct link to decisionMakers")

* Type: `array`

Teams or users that made or approved the decision.

Example

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

### `appliesTo`[​](#appliesTo "Direct link to appliesTo")

* Type: `array`

Resources affected by this decision.

Example

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

### `supersedes`[​](#supersedes "Direct link to supersedes")

* Type: `array`

Decision records replaced by this decision.

Example

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

### `supersededBy`[​](#supersededBy "Direct link to supersededBy")

* Type: `array`

Decision records that replace this decision.

Example

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

### `amends`[​](#amends "Direct link to amends")

* Type: `array`

Decision records amended by this decision.

Example

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

### `amendedBy`[​](#amendedBy "Direct link to amendedBy")

* Type: `array`

Decision records that amend this decision.

Example

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

### `related`[​](#related "Direct link to related")

* Type: `array`

Related decision records.

Example

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

### `badges`[​](#badges "Direct link to badges")

* Type: `array`

Badges rendered on the decision record page.

Example

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

## Applies to[​](#applies-to "Direct link to 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`.