ADR frontmatter API

View as Markdown

---

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

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

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

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

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

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

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

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

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