# Relationships

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

***

**Added in** `eventcatalog@3.42.0`

ADRs often build on or replace earlier decisions. EventCatalog supports four relationship types to capture this history.

## Supersedes and supersededBy[​](#supersedes-and-supersededby "Direct link to Supersedes and supersededBy")

Use `supersedes` when a new decision replaces an older one. The older decision should set its `status` to `superseded`.

adrs/adr-003-v2/index.mdx (new decision)

```
---
id: adr-003-standardize-domain-event-buses
version: 2.0.0
status: accepted
supersedes:
  - id: adr-003-standardize-domain-event-buses
    version: 1.0.0
---
```

You can also declare the relationship from the older side using `supersededBy`.

adrs/adr-003-v1/index.mdx (old decision)

```
---
id: adr-003-standardize-domain-event-buses
version: 1.0.0
status: superseded
supersededBy:
  - id: adr-003-standardize-domain-event-buses
    version: 2.0.0
---
```

EventCatalog derives reverse links automatically. Declaring `supersedes` on the new decision is enough to infer the `supersededBy` relationship on the old one, and vice versa.

## Amends and amendedBy[​](#amends-and-amendedby "Direct link to Amends and amendedBy")

Use `amends` when a decision refines or extends an earlier one without fully replacing it.

```
amends:
  - id: adr-001-choose-event-driven-orders
```

As with supersedes, reverse links are derived automatically from either side.

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

Use `related` to point to decisions that are relevant context but not in a supersedes or amends relationship.

```
related:
  - id: adr-001-choose-event-driven-orders
  - id: adr-003-standardize-domain-event-buses
    version: 2.0.0
```

## How relationships appear in the sidebar[​](#how-relationships-appear-in-the-sidebar "Direct link to How relationships appear in the sidebar")

Each relationship group appears as a separate section in the ADR's sidebar:

* **Supersedes** — decisions this ADR replaces
* **Superseded by** — decisions that replace this ADR
* **Amends** — decisions this ADR refines
* **Amended by** — decisions that refine this ADR
* **Related decisions** — associated decisions

Deprecated and superseded ADRs also display a warning banner at the top of the page with links to the current decision.