Built-in taxonomy schemas

docmeta ships three taxonomy schemas: closed vocabularies that constrain a classification field to a published set of values. They exist because google:okf:0.1 requires a type but accepts any non-empty string for it, so it cannot stop a docs set from drifting into how-to, howto, and guide all meaning the same thing.

Id	Key	Key required?	Framework
diataxis:diataxis:1.0	type	Yes	Diátaxis
tgdp:templates:1.0	type	Yes	The Good Docs Project
passo-uno:seven-action:1.0	action	No	Seven-Action Documentation Model

All three use Draft 2020-12, allow additional properties, and are built-in references.

The two keyed on type are alternatives to each other — see Which ones compose. For the other four schemas docmeta ships, including the Docusaurus front matter contracts, see the built-in schema registry.

Vocabulary checks vs. presence checks

The two content-type schemas do both jobs: they require their key as well as constraining it, so neither needs a partner to get presence-checking. Adopting a named set of document types is a claim that every page is one of them, which makes an untyped page a gap rather than an abstention:

✗ docs/overview.md
    (root)  must have required property 'type'  (line 1)  [diataxis:diataxis:1.0]

Pair either with google:okf:0.1 for the other OKF fields, not for type:

docmeta validate docs/ -s diataxis:diataxis:1.0 -s google:okf:0.1

passo-uno:seven-action:1.0 is the exception. It checks action only if one is present, which is what makes it safe to layer onto an existing setup — and what makes it safe to carry in the default set.

Both `type` schemas require the key, so retrofit with `--dry-run` first

On an existing docs set that never adopted either vocabulary, turning one on reports every untyped page at once. Run docmeta fill --dry-run to see what would be proposed before writing anything.

Schema order does not matter, here or anywhere else. Both schemas define type, and fill infers against the two rules combined, so the vocabulary’s enum reaches the model whichever -s comes first — the proposal can only be one of the four. validate likewise always runs every schema in the set.

diataxis:diataxis:1.0

Requires type and constrains it to the four Diátaxis forms.

Value	Orientation
tutorial	Learning-oriented
how-to	Task-oriented
reference	Information-oriented
explanation	Understanding-oriented

---
type: how-to
title: Rotate an API key
---

Diátaxis is not part of the default set. It both requires and constrains type, so applying it by default would fail every repo not already using Diátaxis. Opt in with -s or a schemas: entry in config.

tgdp:templates:1.0

Requires type and constrains it to the template slugs published by The Good Docs Project. Where Diátaxis names four abstract forms, TGDP names 25 concrete deliverables, so it fits a docs set that thinks in terms of “we owe this product an installation guide and a changelog” rather than in terms of the four quadrants.

The values are the template directory slugs from the upstream templates repo, grouped here by the pack each belongs to. All 25 validate regardless of pack; the grouping is upstream’s, and is reproduced only to show what you are opting into.

Pack	Values
Core	concept, how-to, readme, reference, release-notes, troubleshooting, tutorial
Community	bug-report, changelog, code-of-conduct, code-of-conduct-incident-record, code-of-conduct-remediation-record, code-of-conduct-response-plan, contributing-guide, our-team
Misc	api-getting-started, api-reference, contact-support, glossary, installation-guide, quickstart, sdk-overview, style-guide, terminology-system, user-personas

---
type: installation-guide
title: Install the collector
---

Like Diátaxis, TGDP is not in the default set: it both constrains and requires type, so defaulting it would fail every untyped document in every repo that had not opted in.

TGDP prescribes no frontmatter of its own

The upstream templates are body-structure templates — they open at a heading and carry no YAML block. The only metadata TGDP publishes is index.json, which describes the templates (name, summary, last_updated, contributors, packs), not documents written from them. So the vocabulary here is lifted from the template set, not an implementation of a TGDP metadata spec, and requiring type is docmeta’s choice rather than an upstream rule — the same choice it makes for Diátaxis, which likewise publishes no frontmatter spec. Pair it with google:okf:0.1 for the fields TGDP leaves unspecified.

passo-uno:seven-action:1.0

Constrains action to the seven reader actions. Derived from upstream model version 2025-01-09.

Value	Alternate verb	What the reader is doing
appraise	Discern	Judging whether something fits their situation
understand	Learn	Grasping a concept
explore	Discover	Finding out what exists
practice	Train	Building a skill by doing
remember	Recall	Looking up a detail they once knew
develop	Integrate	Building the thing into their own work
troubleshoot	Solve	Getting past a problem

Only the left column validates. The alternate verbs are how the model names each action in prose; action: learn fails.

---
action: practice
title: Work through the tutorial
---

This schema is in the default set, alongside OKF. It can be, because it constrains a key that documents do not otherwise carry and does not require it — so it fails nothing that passed before.

If you already use an `action` key

action is a generic field name. If your frontmatter already uses it for something else (a workflow name, a button label), two things change:

• validate fails. Your value is not in the vocabulary, so it is reported as an error against passo-uno:seven-action:1.0.
• fill overwrites it. A key whose value is invalid is a candidate for replacement, not just for filling a gap, and docmeta fill writes to disk unless you pass --dry-run. Run docmeta fill --dry-run first on any repo that uses action for something of its own.

Set a schemas: list in docmeta.config.yaml before running either command. It replaces the default set entirely, which opts you out of both.

Which ones compose

Diátaxis and TGDP both classify what a page is, so both claim type. Seven-Action classifies what a reader is doing, which is independent, so it claims action and composes with either:

---
type: how-to
action: practice
title: Rotate an API key
---

Combination	Result
Diátaxis + Seven-Action	Composes
TGDP + Seven-Action	Composes
Diátaxis + TGDP	Pick one

Stacking the two type schemas is not an error, but it validates against the intersection of their vocabularies, which is narrower than either. explanation is Diátaxis-only and installation-guide is TGDP-only, so each rules out values the other exists to allow — leaving only tutorial, how-to, and reference. Choose the vocabulary your docs set actually uses.

Crosswalk

The Seven-Action model publishes a mapping to Diátaxis. It is not one-to-one: explore lands on Tutorial, and Diátaxis’s single how-to form splits across three actions.

action	Diátaxis type
appraise	no direct equivalent (closest: explanation)
understand	explanation
explore	tutorial
practice	how-to
remember	reference
develop	how-to
troubleshoot	how-to (problem-oriented)

Use it to sanity-check a pairing, not as a rule docmeta enforces. The two schemas validate independently; no combination of a valid type and a valid action is rejected.

If your vocabulary differs

The enums are strict and carry no aliases, so howto and How-To Guide both fail. That is the point of a vocabulary check, but it means a docs set with its own conventions needs its own schema. Copy the shape into a local file and edit the enum:

schemas/types.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": true,
  "required": ["type"],
  "properties": {
    "type": {
      "type": "string",
      "enum": ["tutorial", "how-to", "howto", "reference", "explanation"]
    }
  }
}

Drop the required line if you want a vocabulary check without a presence check — a document with no type then passes.

Then reference it by path instead of the built-in id. See Author a schema for the full authoring guide.