The proposed metadata vocabularies

A proposal under review

Nothing on this page is registered, published, or enforced yet. It is a design put in front of the documentation community for review. The decisions below are real, and they are still reversible. The full record lives in the repo as proposal 0023, with the draft schemas under docs/proposals/0023/schemas/. The tenth vocabulary, citations, arrived later under proposal 0044, with its draft under docs/proposals/0044/schemas/. Each vocabulary has its own page, linked from the tables below and listed in the sidebar.

manni meta is a CLI that validates the presence and format of document metadata (frontmatter) against JSON Schema, in CI. Its built-in schemas have always transcribed contracts other people published: Hugo’s front matter, DITA’s prolog, Open Graph. This proposal adds the first vocabularies manni meta would publish itself. They cover the facts a docs set needs to stay maintained and readable by machines. Those are ownership, review, audience, applicability, lifecycle, relationships, AI provenance, and quality checks. No site generator defines those facts, and no standard owns them.

The ten vocabularies

The ten are designed as one family. They share the same conventions, and no two of them claim the same key. They are split by intent, so that each one is a separate decision to adopt. Six describe a page. Four carry quality, knowledge-graph and citation metadata that any grader, graph builder, drift check or CI tool can implement. Each has its own page (the sidebar lists all ten) with its fields, examples, design rationale, and its own questions for reviewers:

Id	The question it answers	Fields
manni:core:1.0.0-proposal.4	What is this page?	title* · description* · id · type · keywords · language · locale
manni:stewardship:1.0.0-proposal.3	Is it cared for?	authors · owner · stakeholders · reviewed-by · created · last-updated · last-reviewed · review-interval · verified-against · source-of-truth
manni:audience:1.0.0-proposal.2	Who does it serve, and who may see it?	audiences · personas · journeys · intent · visibility
manni:lifecycle:1.0.0-proposal.2	Where is it in its life?	lifecycle · replaced-by · supersedes · remove-by
manni:structure:1.0.0-proposal.2	What does it connect to?	applies-to · not-applicable-to · concepts · prerequisites · next-steps · related-pages
manni:ai-context:1.0.0-proposal.3	How did machines make it, and how may they use it?	provenance · meta-provenance · risks · sample-questions
manni:evals:1.0.0-proposal.4	What must be true of this page?	evals · eval-suite · eval-skip
manni:kg:1.0.0-proposal.3	What does the knowledge graph know about it?	kg, one closed block: SKOS concepts, iiRDS typing, PROV provenance
manni:artifact-evals:1.0.0-proposal.4	What must a session using this artifact have done?	metadata.evals · metadata.eval-skip · metadata.meta-provenance
manni:citations:1.0.0-proposal.4	What do its claims rest on?	citations

Every family has moved past 1.0.0-proposal.1. Core moved in review rounds 6 and 8, evals and artifact-evals in round 6, and stewardship in round 9. Citations moved when its private sources were encrypted, and again when its claims were pinned by lines. Proposal 0046 moved ai-context, evals, kg and artifact-evals, when page provenance became line pins and the machine-proposal trails merged into meta-provenance. Proposal 0047 then gave all ten a new revision that marks every top-level field with x-manni-location, page or external, and changes no field. The mark says whether a field is meant to reach delivered output or belongs in the collection’s external-metadata manifest. See field location for how the marks are used.

All ten are intended for manni meta’s default set, the schemas a run uses when no schema is configured. Such a run would then require every page to carry a non-empty title and description. Those are the only two required fields in the family. The run would also validate any other family key a page chooses to carry. A page with only the required pair stays valid, because the other nine vocabularies require nothing until you use their keys.

What a fully-annotated page looks like

---
title: Install the operator on Kubernetes
description: Deploy the operator with Helm and verify the rollout.
type: how-to
owner: platform-docs
stakeholders: [jane.doe, pm-alex]
reviewed-by: [sam.reviewer]
created: 2025-11-04
last-updated: 2026-08-20
last-reviewed: 2026-08-20
review-interval: P90D
verified-against: operator 1.4.2
source-of-truth: https://github.com/example/operator/tree/main/helm
audiences: [administrators]
personas: [persona-platform-admin]
intent: Deploy the operator on a running cluster
visibility: public
lifecycle: published
applies-to: [operator-1.4, kubernetes]
concepts: [Operator, Helm chart]
prerequisites: [create-api-token]
related-pages: [operator-architecture]
provenance:
  - generated-by: claude-fable-5
    lines: 12-31
    integrity: sha256-5d41402abc4b2a76b9719d911017c592ae2b8f1c6e0d3a4b7c9e8f1a2b3c4d5e
meta-provenance:
  - generated-by: claude-fable-5
    fields: [/intent, /sample-questions]
    confidence: { /intent: 0.9, /sample-questions: 0.84 }
risks: [privileged, cost-incurring]
sample-questions:
  - How do I install the operator on EKS?
evals:
  - id: install-verified
    assertion: The Helm install steps produce a Ready operator pod.
    grader: human
    severity: warning
citations:
  - id: chart-version
    claim:
      lines: 8
      integrity: sha256-2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae
    source:
      file: helm/operator/Chart.yaml
      lines: 3
      integrity: sha256-78af1d3321f9cbb177a7e4c958e39be56fd14cb93c1e441778bc4232e0fe4b1f
      commit-sha: 3f9c2a1e7b0d4c5a6f8e9d0b1a2c3d4e5f607182
kg:
  label: Operator installation
  broader: [Operator]
  type: task
---

Every key above is optional except title and description. A page that carries only those two is valid. Each further key is a step you take when you are ready for it. The block shows the whole family on one page. So validating it also warns about each field marked external, which a real collection would keep in its manifest instead.

The principles behind every field

1. Weak floors teach bad habits. A default that accepts an empty title teaches the habit it exists to prevent. So title and description are required, every string the core vocabulary defines must be non-empty, and type and language take a single value. This is stricter than the loosest schemas that share those keys: Docusaurus permits an empty title, and Dublin Core allows repeated elements. The family’s compatibility rule is that a document valid under another built-in schema stays valid under these vocabularies. These strictness choices are the only exceptions to that rule, and an automated check records each one.
2. One value is a string; many values are a list. This holds for every field, with no per-field exceptions to remember.
3. Claim content, never rendering. There is no slug, layout, image, tags, ordering, or navigation here. The generator owns how a page is displayed and where it sits. These vocabularies only describe what a page is.
4. Derivable facts lie. There is no date key and no stored review deadline. last-reviewed plus review-interval give the due date, so a stored copy could only agree with them or lie. Review round 9 held the document’s own dates up against this and put them back. created and last-updated sit in stewardship, because git’s timestamps describe the path rather than the document.
5. Facts live at their altitude. A fact belongs at the level that owns it. Reader expertise belongs in your persona definitions, not on every page. Style guides belong in config. stakeholders stays at page level because the right people to consult differ from page to page.
6. Enumerate only what is switched on and bounded. visibility and lifecycle are the only enums this family invents, because something downstream branches on each value. Fields with recommended but open values, such as risks and the artifact grader family, use an open list. The recommended values feed editors and tooling, and any other string stays legal. A consumer that meets an unknown value should treat it as a caution rather than as nothing.
7. Compose, don’t duplicate. Content classification is three layers, each owned by the schema that published it. Those are type for what the page is, Seven-Action’s action for what the reader is doing, and intent for the specific job.
8. Deeper wins. Where the kg block and a page field describe the same fact (type, concepts, applies-to), the declaration inside the block wins and the page-level field is the fallback.
9. Machines propose; humans retire the provenance. A meta-provenance entry names the model that proposed some fields or evals and its confidence in each. Humans delete the entry once they have reviewed them. One key covers the whole family, on the page and under an artifact’s metadata. A surviving entry means machine-written metadata that nobody has checked yet. Prose is different: provenance pins the body lines a machine wrote, and manni meta derive keeps those pins.

Quality contracts, on pages and on agent artifacts

The same eval vocabulary covers documentation pages and the instruction artifacts (skills, agent definitions) that agents run with:

# a docs page
eval-suite: how-to
evals:
  - id: install-command-current
    assertion: The documented install command matches the current package name.
  - id: links-resolve
    grader: command
    command: ["npx", "linkinator", "{file}"]

# a SKILL.md: the host tool owns the top level, so evals nest under metadata
metadata:
  evals:
    - id: used-read
      assertion: The session read at least one source file before editing.
      grader: tool-usage
      options: { tool: Read, expect: used }
    - Reproduce the bug with a failing test before applying the fix.

Entries share one shape on both sides: id, assertion, type, severity, evidence, examples, target, weight, runs, model, and a per-entry skip. The assertion rule is the same on both sides too: ai, human, and entries with no grader require one, and command requires an assertion or a command. The two sides differ in their grader families and in what target can select. Pages are graded by ai, command, human, or a tool:* integration. Sessions are graded by ai, human, command over the trace, or a deterministic session grader such as tool-usage or cost. The tool:* spelling is accepted on both sides, so one grader name works for page and artifact evals.

What we most want your opinion on

These are the calls we consider most contestable, in the order we expect debate:

1. Applicability is flat. applies-to: [operator-1.4, kubernetes] uses flat labels. Named dimensions (product, deployment, generation) were designed and then removed, with prefix labels such as deploy:kubernetes as the escape hatch. Is that too flat?
2. lifecycle is a closed enum (draft · published · deprecated · archived). It catches typos and makes the rule “a deprecated page must name a successor or a removal date” enforceable. It also rejects an experimental or retired stage unless you override the key.
3. risks holds assurances too. read-only and idempotent sit in a field called risks. The reasoning: an unannotated page has not been assessed, which is different from being safe. Does the name survive?
4. The whole family ships in the default set. A manni meta validate run with no schema configured would fail pages that cannot say what they are called or what they are for. That is the one hard requirement. It would also validate any other family key a page already carries, and a bare manni meta fill would propose the full menu. Is a family-wide default the right level of aggressiveness?
5. stakeholders at page level. These are the people to consult about this page, distinct from project-level stakeholder lists, which stay in project docs.

How to review

Open an issue on hawkeyexl/manni. Field-level nitpicks are as welcome as structural objections. The complete design record is in proposal 0023, and the design notes beside it. That covers every cut and rename, plus the runnable example sets that verify each schema. Registration waits for this review to conclude.