---
id: ADR-003
type: adr
status: accepted
created: 2026-03-16
deciders: [Bernd, Custodian]
---

# ADR-003: Manifest YAML Schema

## Status

Accepted

## Context

markidocx needs a project definition format that:

1. Describes which Markdown source files form a document project
2. Declares the feature level (`level1` / `level3`) and document family (`article`,
   `book`, `website`)
3. Specifies output location and document metadata
4. Is human-writable and version-controllable alongside source files
5. Is parseable by the system without a schema registry or external validator

The format must support single-file and multi-file projects, and be extensible
enough for future additions (e.g. bibliography sources, asset directories) without
breaking existing manifests.

## Decision

Use **YAML** with a fixed four-section top-level structure:

```yaml
project:
  name: <string>
  feature_level: level1 | level3
  family: article | book | website

sources:
  - path: <relative path to .md file>
  - path: <relative path to .md file>

output:
  dir: <relative path to output directory>

metadata:
  title: <string>
  author: <string>
  date: <string>
```

All paths are resolved relative to the manifest file's location. The `metadata`
section and individual source `path` keys may be extended in future versions.

Validation is performed on load by `manifest.py` using dataclass coercion:
`load_manifest(path)` raises `ManifestError` on any schema violation (missing
required fields, unknown feature levels, unresolvable source paths).

## Current Field Definitions

| Field | Type | Required | Default | Notes |
|-------|------|----------|---------|-------|
| `project.name` | string | yes | — | Project identifier; used in output filenames |
| `project.feature_level` | enum | yes | — | `level1` or `level3` |
| `project.family` | enum | yes | — | `article`, `book`, or `website` |
| `sources[].path` | string | yes | — | Relative path; resolved against manifest dir |
| `output.dir` | string | no | `./dist` | Relative path for generated artefacts |
| `metadata.title` | string | no | — | Propagated to DOCX document properties |
| `metadata.author` | string | no | — | Propagated to DOCX document properties |
| `metadata.date` | string | no | — | Propagated to DOCX document properties |

## Consequences

**Positive:**
- Human-readable and diff-friendly; natural fit for version-controlled documentation
  repositories
- No external schema validation library needed — `manifest.py` owns validation
- Simple enough for a first-time user to write by hand
- Relative paths keep manifests portable across machines

**Negative / accepted limitations:**
- Evolving the schema requires coordination between the manifest file format and
  `manifest.py` — there is no formal schema version field
- No auto-completion support in editors without a JSON Schema / YAML Language Server
  configuration (out of scope for v0.1)
- YAML's implicit type coercion can surprise users (e.g. bare `no` parsed as `False`);
  `load_manifest` validates all fields explicitly to catch these cases

## Alternatives Rejected

**TOML** — good alternative, but YAML is more common in documentation tooling
(MkDocs, GitHub Actions, Kubernetes) and more familiar to the target audience.

**JSON** — less writable for humans; comments not supported; trailing commas
disallowed; less pleasant for multi-line string values.

**Database / registry** — over-engineered for the single-project use case; would
require a running service just to define a document project.

**Pydantic / JSON Schema** — considered for validation, but adds a dependency
for functionality that a handful of explicit checks in `load_manifest()` already
covers cleanly.