Principles

dealwithdata writes about governed data, so dealwithdata is governed data. Every rule below is something the content teaches, applied to the content itself. If a principle here isn't enforced by the build, it's a wish, not a principle. Each one names its enforcement.

1. One canonical model, many projections

The Markdown files in content/ are the system of record. The website, the JSON API, the glossary in SKOS, the lineage graph, the change-event log, llms.txt, the Atom feed and the MCP server are all generated from them. Nobody hand-edits a projection.

Enforced by: scripts/build.py is the only writer of dist/; dist/ is not committed.

2. Stable identity, separate from names

Every item has an id (dwd_ + 8 random base32 characters) that never changes. The slug is a human-friendly name and may change; old slugs go in aliases so links don't break.

Enforced by: schema pattern on id, uniqueness check across all items, scripts/new.py mints IDs.

3. Data contracts on content

Every item's frontmatter must satisfy schema/item.schema.json. A pull request that breaks the contract does not merge.

Enforced by: schema validation in the build, which runs on every PR.

4. Legible state: draft, reviewed, verified

Status is shown everywhere the item appears, including the API and MCP.

• draft: written, not yet reviewed by someone other than the author.
• reviewed: a maintainer has checked it for accuracy and clarity.
• verified: the claims or code have been tested against a real implementation, and verified_by says how.

Nothing is hidden for being a draft. It is labeled.

Enforced by: required status field; verified requires verified_by.

5. Provenance: who and what made it

authors are the humans accountable for an item. assisted_by records any AI that drafted or edited it. An AI is never an author; a human owns every published word.

Enforced by: authors required and non-empty; assisted_by is shown on the page and in every export.

6. Lineage: every claim traces to a source

sources lists what an item draws on, each with a URL and the date it was accessed. Fast-moving topics carry an as_of date. related links items to each other by ID, and terms links them to glossary entries.

Enforced by: referential-integrity check (every related and terms ID must exist); lineage.json is generated from these links.

7. Active, not passive

Every change to content becomes an event (CloudEvents 1.0) in api/events.jsonl, derived from Git history. Subscribe to it, poll it, or diff it. Metadata that nobody can subscribe to goes stale.

Enforced by: the build derives events from git log; the deploy fetches full history.

8. Classification before publication

Every item declares classification: public. Anything else is refused by the build. A sensitivity lint checks content against a private deny-list (employer names, internal system names, real volumes) that is never committed.

Enforced by: schema enum; check_sensitive step reads .denylist locally or the DWD_DENYLIST secret in CI.

9. One concept, three scales

Wherever it makes sense, a concept is shown at personal, business and enterprise scale. Governance isn't only a bank problem; it's everyone's problem at different sizes.

Enforced by: scales field (at least one), used for filtering everywhere.

10. Consumable by machines as well as people

If a human can read it, an agent can query it: same content, same IDs, same status, same lineage. No channel gets a different truth.

Enforced by: all channels are built from one in-memory catalog in a single build pass.