Rules

These are the rules of @okforest/validate 0.2.1, which the OKForest CLI, the OKForest Validate action, and the OKForest service all run, so a tree gets the same results everywhere. Each finding names the rule, with the file, line, and column.

Severity

Every rule has one severity:

Severity	Meaning
error	Fails okforest validate (exit code 1) and, by default, the OKForest Validate action.
warning	Reported; fails only the action, with fail-on: warning.
info	A note; never fails validation.

By default only errors fail validation; the action’s fail-on input can fail on warnings too, or never fail. The OKF specification says never to reject a bundle for a broken link, for example, so okf/broken-link is a warning.

Changing a severity

A rule’s severity can’t be changed today: neither the CLI nor .okforest/tree.yaml can raise, lower, or turn off a rule. Instead, you can:

• skip files with ignore: globs in .okforest/tree.yaml;
• turn off the action’s diagram checks with diagrams: false;
• choose which severities fail the action with fail-on.

OKF specification

Errors are what the OKF v0.2 specification requires; warnings and info are what it recommends.

Rule	Severity	Checks
okf/frontmatter	error	Every concept starts with a parseable YAML frontmatter block (OKF §4, §11).
okf/type	error	Every concept’s frontmatter has a non-empty string type (OKF §4.1, §11).
okf/index-frontmatter	error	index.md files carry no frontmatter, except an okf_version key in the bundle-root index.md (OKF §8, §12).
okf/index-entries	warning	index.md lists its directory as * [Title](path) - description entries under headings (OKF §8).
okf/log-date	error	log.md groups entries under second-level headings in ISO 8601 YYYY-MM-DD form (OKF §9).
okf/log-order	warning	log.md lists its dates newest first, each once (OKF §9).
okf/okf-version	info	The bundle-root index.md declares okf_version: "0.2" (OKF §12).
okf/generated	error	generated is a mapping with a required by actor (OKF §5.2).
okf/verified	error	verified is a { by, at } mapping or a list of them (OKF §5.2).
okf/sources	error	sources is a list of mappings, each with a resource, unique ids, and well-formed credibility signals (OKF §5.1).
okf/status	error	status is one of draft, stable, or deprecated (OKF §5.4).
okf/datetime	error	Timestamps are ISO 8601 datetimes with an explicit UTC offset, e.g. 2026-06-30T14:00:00Z (OKF §5).
okf/attested-computation	error	An Attested Computation has a runtime, well-formed parameters, executor, and attester, and a computation (a computation path or a code block under # Computation) (OKF §10).
okf/title	warning	Concepts have a title (recommended, OKF §4.1).
okf/description	warning	Concepts have a one-sentence description (recommended, OKF §4.1).
okf/field-types	warning	title, description, and resource are strings, and tags is a list of strings (OKF §4.1).
okf/actor	warning	generated.by and verified[].by follow the actor convention: <producer>/<version>, human:<id>, or process:<id> (OKF §7).
okf/broken-link	warning	Links within the tree point at files that exist (a warning: OKF says never reject a bundle for broken links, §6.1, §11).
okf/footnote-source	warning	In a concept that has sources with ids, every footnote label matches one of them (OKF §5.1 per-claim attribution).
okf/legacy-v01	info	Flags OKF v0.1 conventions superseded in v0.2: timestamp and a body # Citations list (OKF §13).

OKForest conventions

OKForest’s own conventions, beyond the specification.

Rule	Severity	Checks
okforest/tree-yaml	error	.okforest/tree.yaml names exactly one Owner as user:<id>, Stewards as user/group entries, and well-formed optional settings.
okforest/slug	warning	File and directory names of concepts are slugs: lowercase letters, digits, and hyphens.
okforest/placeholder	warning	Bodies contain no unrendered template placeholders ({{name}}, <concept>, [INSERT ...]) or example link paths (path/to/...).
okforest/wikilink	warning	Concepts link with standard markdown links, not [[wikilinks]] (OKF §6.1).
okforest/d2-syntax	error	d2 code blocks are valid D2 (diagrams as code).
okforest/mermaid-syntax	error	mermaid code blocks are valid Mermaid (diagrams as code).
okforest/diagram-unchecked	info	Reports diagram blocks whose syntax could not be checked (tool not installed or unsupported here).