---
summary: The YAML metadata block at the top of every entry's index.md.
---
# Frontmatter
The **frontmatter** is the YAML block at the top of every
`index.md` in the workspace. It carries the entry's metadata —
id, title, status, tags, links — in a format that is both
machine-parseable and editable by hand.
The event log lives in a sibling `events.jsonl` companion file,
not in the frontmatter — see [event-log](concept://event-log).
## Shape
A frontmatter is delimited by `---` on its own line, both at the
start of the file and at the end of the YAML block. Between the
delimiters: a single YAML document with the entry's fields. After
the closing delimiter: the Markdown body.
```
---
id: ISSUE-01HQFKM3XYZ1A
title: "Refresh the help text"
status: open
date: 2026-05-04
tags:
- "flow:feature"
links:
- id: ADR-01HQGABCD23K7P
relationship: blocked-by
---
The body of the entry follows here in plain Markdown.
```
The fields fall in two groups:
- **Identity** — `id`, `title`, `status`, `date`, optional
`description`, optional `aliases`. Tags live under `tags:` as a
list of strings.
- **Relationships** — `links:` is a list of
`(id, relationship)` pairs.
The exact set of valid fields and their order is documented in
the per-concept docs ([issue](concept://issue),
[decision-record](concept://decision-record)).
## Configuration
The frontmatter shape itself is not configurable — it is part of
the on-disk schema and bumps via `cartu migrate`. What *is*
configurable is what counts as a valid value for a given field:
the workflow that defines accepted statuses, the descriptors that
constrain tag values, and the closed vocabularies of relationship
names.
## Validation
`cartu check` enforces, for every entry's frontmatter:
- It parses as YAML without errors.
- The opening and closing `---` delimiters are present.
- The `id:` field matches the directory's TSID prefix.
- Field types match the schema (e.g. `tags:` is a list,
`links:` is a list of `(id, relationship)` entries).
- The `events.jsonl` sibling is present, and its terminal state
matches the frontmatter `status:`.
- Domain rules from the concepts the frontmatter carries (status
values, tag descriptors, link targets, event-log shape).
`cartu fmt` canonicalises hand-edited frontmatter — quoting,
field order, indentation — without changing semantics. Run it
after manual edits to keep diffs minimal.
## Commands
- **Inspect**: `cartu issue show <id>` and `cartu <kind> show
<id>` print frontmatter content alongside the body.
- **Canonicalise**: `cartu fmt` (or `cartu fmt --check` for a
dry-run that fails if anything would change).
- **Migrate**: `cartu migrate` rewrites frontmatter when the
schema version bumps.
- **Validate**: `cartu check` (parse + domain rules).