# ADR frontmatter API

Copy as Markdown[View as Markdown](/docs/api/adr-api.md)

***

**Added in** `eventcatalog@3.42.0`

Architecture decision records are markdown or MDX files with frontmatter.

adrs/choose-kafka/index.md

```
---
id: choose-kafka
name: Choose Kafka for domain event distribution
summary: Kafka is the primary backbone for inter-domain event distribution.
version: 1.0.0
status: accepted
date: 2026-05-26
owners:
  - platform-team
decisionMakers:
  - architecture-board
appliesTo:
  - type: domain
    id: Orders
  - type: service
    id: PaymentService
  - type: event
    id: PaymentAccepted
supersedes:
  - id: use-webhooks
badges:
  - content: Messaging
    backgroundColor: blue
    textColor: blue
---

## Context

...

## Decision

...

## Consequences

...
```

## File location[​](#file-location "Direct link to File location")

Architecture decisions can be placed in any `adrs` folder in your catalog.

```
adrs/choose-kafka/index.md
domains/Orders/adrs/choose-kafka/index.mdx
```

Versioned decisions use the same folder shape as other versioned resources.

```
adrs/choose-kafka/versioned/1.0.0/index.md
```

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

| Field     | Type                                                           | Description                                |
| --------- | -------------------------------------------------------------- | ------------------------------------------ |
| `id`      | `string`                                                       | Unique identifier for the decision.        |
| `name`    | `string`                                                       | Display name for the decision.             |
| `version` | `string`                                                       | Version of the decision record.            |
| `status`  | `proposed`, `accepted`, `rejected`, `deprecated`, `superseded` | Lifecycle status for the decision.         |
| `date`    | `date`                                                         | Date the decision was created or recorded. |

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

| Field            | Type     | Description                                                                             |
| ---------------- | -------- | --------------------------------------------------------------------------------------- |
| `summary`        | `string` | Short summary shown in lists and search.                                                |
| `owners`         | `array`  | Users or teams that own the decision record.                                            |
| `decisionMakers` | `array`  | Users or teams that made or approved the decision.                                      |
| `appliesTo`      | `array`  | Resources affected by this decision.                                                    |
| `supersedes`     | `array`  | Decisions replaced by this decision.                                                    |
| `supersededBy`   | `array`  | Decisions that replace this decision. Reverse links are also derived from `supersedes`. |
| `amends`         | `array`  | Decisions amended by this decision.                                                     |
| `amendedBy`      | `array`  | Decisions that amend this decision. Reverse links are also derived from `amends`.       |
| `related`        | `array`  | Related decisions.                                                                      |

Architecture decisions also support shared resource fields from the base schema, including `badges`, `draft`, `repository`, `attachments`, `resourceGroups`, and `editUrl`.

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

Use `appliesTo` to link a decision to first-class EventCatalog resources.

```
appliesTo:
  - type: domain
    id: Orders
  - type: service
    id: PaymentService
    version: 1.0.0
  - type: data-product
    id: OrderAnalytics
```

The supported `type` values are:

```
agent
service
event
command
query
flow
channel
domain
user
team
container
entity
diagram
data-product
```

If `version` is omitted, EventCatalog resolves the link to the latest version.

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

Use `supersedes` to declare that this decision replaces one or more earlier decisions.

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

Use `supersededBy` on the older decision to declare the reverse relationship explicitly. EventCatalog also derives reverse links automatically from `supersedes`, so declaring it on either side is sufficient.

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

## `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
```

Reverse links are derived automatically from either side.

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

Use `related` to reference decisions that provide relevant context.

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

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

Use `decisionMakers` to identify the users or teams that approved the decision. This is distinct from `owners`, who are responsible for maintaining the record.

```
decisionMakers:
  - architecture-board
  - platform-team
```