ADR frontmatter

Purpose

This page is the author-facing reference for Dataverket ADR frontmatter.

Use it when you need to know which fields to include, which values Dataverket accepts, and how to express ADR relationships consistently.

For validator internals, pipeline behavior, and strict versus advisory validation, see ADR validation.

Why Dataverket uses structured frontmatter

Dataverket is building a control plane and datacenter automation suite with stable service identities, consistent CLI surfaces, and shared documentation across multiple repos.

That means ADR metadata needs to do more than label a single markdown file. It needs to make decisions discoverable, searchable, and consistent across services such as sentral, maskin, nett, and the wider dataverket platform.

The current model follows Structured MADR and keeps the frontmatter small enough to author by hand while still giving the docs pipeline enough structure to validate and index the decision corpus.

Required fields

Every Dataverket ADR must include these frontmatter fields:

  • title: short decision title used as the canonical page title
  • description: one-sentence summary of the decision
  • type: must always be adr
  • project: the Dataverket project or service the ADR applies to
  • category: the decision domain
  • tags: lowercase kebab-case keywords for filtering and search
  • status: lifecycle state of the ADR
  • created: creation date in YYYY-MM-DD
  • updated: last modified date in YYYY-MM-DD
  • author: person or team responsible for the ADR

Allowed values

Dataverket currently accepts these controlled values:

  • project: dataverket, sentral, maskin, nett, identitet, plattform, tjeneste, objekt
  • category: api, architecture, data, infrastructure, integration, migration, security, testing
  • status: accepted, proposed, rejected, superseded, deprecated

Optional fields

These fields are currently accepted when they add useful context:

  • technologies
  • audience
  • related

Minimal example

---
title: "Resource inventory and tenancy model"
description: "Defines tenant, project, and environment hierarchy with a shared inventory model."
type: adr
project: dataverket
category: architecture
tags:
  - tenancy
  - inventory
  - resources
status: proposed
created: 2026-04-06
updated: 2026-04-06
author: Your Name
related:
  - 007-nats-subject-and-event-envelope.md
---

Use related for ADR-to-ADR relationships that help readers navigate the decision landscape.

Examples include:

  • a follow-up ADR
  • a dependency or prerequisite ADR
  • an ADR that provides contrasting direction
  • an ADR that provides supporting context
  • an ADR that replaces or is replaced by another ADR

Prefer filename-only references when the target ADR basename is unique in the aggregated corpus. Relative paths are also accepted when filename-only references are not appropriate.

Supersession without dedicated fields

Dataverket intentionally does not add explicit supersedes or superseded_by fields.

That is deliberate for two reasons:

  • upstream MADR and Structured MADR treat supersession primarily as a lifecycle state plus a generic relationship, not as a dedicated graph edge
  • keeping one flexible related field makes authoring simpler and avoids splitting relationship semantics across multiple specialized fields

When one ADR replaces another, use the existing fields like this:

  • set the older ADR to status: superseded
  • add the newer ADR to the older ADR’s related list
  • optionally add the older ADR to the newer ADR’s related list as a backlink

This keeps supersession easy to express while preserving the same mechanism for follow-up, dependency, contrast, and supporting-context links.

Required body sections

The validator also expects these markdown sections in the ADR body:

  • Status
  • Context
  • Decision
  • Consequences
  • Decision Outcome
  • Audit

Additional sections such as Decision Drivers, Considered Options, Related Decisions, or More Information are fine when they improve the ADR.

Current fit for Dataverket

The current Structured MADR-derived frontmatter is a good fit for the present Dataverket ADR corpus. It already captures project scope, decision category, lifecycle state, search tags, dates, authorship, and flexible cross-links between decisions.

The main gaps are elsewhere: dependency ordering, rollout state, and datacenter applicability are not yet first-class metadata. If Dataverket later needs those, they should be introduced deliberately as a separate schema and documentation decision rather than by overloading the current fields.

Validation reference

If you are writing an ADR, use this page as the frontmatter contract.

If you need to understand how the docs pipeline enforces that contract, which rules are blocking, or how related links are resolved during validation, use ADR validation.