okf

package
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 9, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package okf implements validation for the Google Open Knowledge Format (OKF) — a directory of markdown files with YAML frontmatter. It supports spec revisions 0.1 and 0.2 (see Version); a bundle's effective version is read from the okf_version declaration in its root index.md, defaulting to Latest.

Spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md

It is a dependency-light library (stdlib + yaml) so it can be reused three ways: as the go-openlore OKF write-admission plugin (pkg/openlore), directly from downstream shell commands (e.g. knowledge-backend's `kb save`/`kb publish`), and as a standalone conformance checker.

Validate enforces only the hard conformance rules of the spec (§11 in v0.2), which are identical in both supported revisions:

  1. Every non-reserved .md file contains a parseable YAML frontmatter block.
  2. Every such frontmatter block contains a non-empty `type` field.
  3. Reserved filenames (index.md, log.md) carry no required frontmatter; if present it must still be parseable (the bundle-root index.md MAY declare okf_version — the one place frontmatter is permitted in an index).

The version-specific optional field families (v0.2 provenance, trust, lifecycle, and Attested Computation shapes; v0.1 legacy timestamp) are shape-checked as warnings by ValidateBundle via the granular, composable ConceptCheck functions in families.go. Everything else in the spec (titles, descriptions, links, body section conventions) is soft guidance that consumers MUST tolerate, so it is deliberately not enforced.

Index

Constants

View Source 
const (
	IndexFile = "index.md"
	LogFile   = "log.md"
)

Reserved filenames per OKF §3.1. They have defined meaning at any level of the hierarchy and are not concept documents.

View Source 
const TypeAttestedComputation = "Attested Computation"

TypeAttestedComputation is the exact concept type (v0.2 §10) that carries the computation contract fields.

Variables

View Source 
var (
	// FamilyChecksV01 covers the v0.1 conventions superseded in v0.2.
	FamilyChecksV01 = []ConceptCheck{CheckTimestamp}
	// FamilyChecksV02 covers the v0.2 provenance, trust, lifecycle, and
	// computation families.
	FamilyChecksV02 = []ConceptCheck{
		CheckSources,
		CheckGenerated,
		CheckVerified,
		CheckStatus,
		CheckStaleAfter,
		CheckAttestedComputation,
	}
)

Per-version family check sets. These are compositions of the exported granular checks; consumers with different policies can assemble their own.

Functions

func DeclaredVersion added in v0.4.1 

func DeclaredVersion(files []File) (string, bool)

DeclaredVersion returns the raw okf_version declaration from the bundle-root index.md frontmatter — the one place the spec permits it (§12). ok is false when the bundle has no root index, no frontmatter, or no usable okf_version value.

func FormatDiagnostic 

func FormatDiagnostic(d Diagnostic) string

FormatDiagnostic renders a diagnostic in a grep-friendly compiler format.

func IsReserved 

func IsReserved(p string) bool

IsReserved reports whether p's basename is an OKF reserved filename (index.md or log.md).

func LocalLinkPath 

func LocalLinkPath(destination string) (string, bool)

LocalLinkPath returns the path component of a link that should resolve inside a bundle. External URLs, anchors, and empty destinations return false.

func ParseFrontmatter 

func ParseFrontmatter(content []byte) (meta map[string]any, body []byte, ok bool, err error)

ParseFrontmatter extracts and decodes the YAML frontmatter of an OKF document, returning the decoded key/value map and the remaining markdown body. ok is false (with a nil error) when the content has no frontmatter block at all; a malformed block returns a non-nil error.

func SplitFrontmatter 

func SplitFrontmatter(content []byte) (frontmatter, body []byte, ok bool)

SplitFrontmatter separates a document's YAML frontmatter from its body. A frontmatter block is a `---` line at the very start of the file, its content, and a closing `---` line. It returns the raw frontmatter bytes (between the delimiters), the body bytes (after the closing delimiter), and ok=true when a well-formed opening+closing delimiter pair is found. Both LF and CRLF line endings are accepted.

func Validate 

func Validate(p string, content []byte) error

Validate checks a single OKF file's bytes for conformance. p is the file's path (used only to determine reserved-filename status via its basename); content is the exact bytes. A nil error means the file is conformant.

Reserved files (index.md, log.md) are validated leniently (no required frontmatter). Every other file is validated as a concept document: it must carry a parseable YAML frontmatter block with a non-empty `type`.

Types

type Concept added in v0.4.1 

type Concept struct {
	Path string
	Meta map[string]any
	Body []byte
}

Concept is one parsed concept document: the input for granular frontmatter-family checks. Meta is the decoded frontmatter and Body the remaining markdown.

type ConceptCheck added in v0.4.1 

type ConceptCheck func(Concept) []Diagnostic

ConceptCheck is one granular, composable family check over a parsed concept document. Checks only shape-check fields that are present — a missing optional family is never a finding (§11) — and report warnings, never errors, so they cannot make a conformant bundle invalid.

func FamilyChecks added in v0.4.1 

func FamilyChecks(v Version) []ConceptCheck

FamilyChecks returns the standard check set for a spec version.

type Diagnostic 

type Diagnostic struct {
	Path     string
	Line     int
	Column   int
	Severity Severity
	Rule     string
	Message  string
}

Diagnostic is one linter-style validation finding.

func CheckAttestedComputation added in v0.4.1 

func CheckAttestedComputation(c Concept) []Diagnostic

CheckAttestedComputation shape-checks the v0.2 computation contract (§10.2) on concepts whose type is exactly "Attested Computation".

func CheckGenerated added in v0.4.1 

func CheckGenerated(c Concept) []Diagnostic

CheckGenerated shape-checks the v0.2 trust family's `generated` block (§5.2): a mapping whose `by` actor is required within the block.

func CheckSources added in v0.4.1 

func CheckSources(c Concept) []Diagnostic

CheckSources shape-checks the v0.2 provenance family (§5.1): the `sources` list and the top-level `usage_window` that frames its usage counts.

func CheckStaleAfter added in v0.4.1 

func CheckStaleAfter(c Concept) []Diagnostic

CheckStaleAfter shape-checks the v0.2 lifecycle `stale_after` field (§5.5): an absolute YYYY-MM-DD date, not a relative TTL.

func CheckStatus added in v0.4.1 

func CheckStatus(c Concept) []Diagnostic

CheckStatus shape-checks the v0.2 lifecycle `status` field (§5.4). Absent means stable and is never a finding.

func CheckTimestamp added in v0.4.1 

func CheckTimestamp(c Concept) []Diagnostic

CheckTimestamp shape-checks the legacy v0.1 `timestamp` field. v0.2 superseded it with `generated`, but a v0.2 consumer MAY still read it (§13), so it is never reported as unknown or deprecated.

func CheckVerified added in v0.4.1 

func CheckVerified(c Concept) []Diagnostic

CheckVerified shape-checks the v0.2 trust family's `verified` events (§5.2): a list of {by, at} mappings, or a bare {by, at} mapping which consumers MUST normalize to a one-element list (§11).

func ValidateBundle 

func ValidateBundle(files []File) []Diagnostic

ValidateBundle checks OKF conformance for every Markdown file in a bundle, linting against the spec version the bundle declares in its root index.md (Latest when absent; an unknown declaration is a warning, never a rejection, per §12). Hard conformance violations (§11) are errors; shape problems in the version's optional field families are warnings. It intentionally does not reject broken links: OKF §6.1 requires consumers to tolerate them. OpenLore checks link resolvability separately as an operational requirement.

func ValidateBundleAs added in v0.4.1 

func ValidateBundleAs(version Version, files []File) []Diagnostic

ValidateBundleAs is ValidateBundle pinned to a specific spec version, bypassing detection. The hard conformance core is identical across versions; the version selects which optional-family checks (FamilyChecks) run as warnings.

type File 

type File struct {
	Path    string
	Content []byte
}

File is one file in a knowledge bundle. Path is relative to the bundle root. 

type Link struct {
	Destination string
	Line        int
	Column      int
}

Link is a standard Markdown link found in an OKF document. 

func Links(content []byte) []Link

Links returns standard Markdown links from a document body. Frontmatter, images, code spans, and code blocks are excluded by the CommonMark parser. Destinations with URL schemes are included so callers can decide which schemes they know how to check.

type Severity 

type Severity string

Severity is the impact of a validation diagnostic. 

const (
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
)

type Version added in v0.4.1 

type Version string

Version identifies an OKF spec revision this package knows how to lint. 

const (
	// V01 is OKF v0.1: the original spec with a legacy scalar `timestamp`
	// field and body `# Citations` convention.
	V01 Version = "0.1"
	// V02 is OKF v0.2: adds the optional provenance (`sources`,
	// `usage_window`), trust (`generated`, `verified`), lifecycle (`status`,
	// `stale_after`), and Attested Computation frontmatter families.
	V02 Version = "0.2"
	// Latest is the newest spec revision this package targets. Versionless
	// and unrecognized bundles are linted against it, per §12: consumers
	// attempt best-effort consumption rather than rejecting.
	Latest = V02
)

func DetectVersion added in v0.4.1 

func DetectVersion(files []File) Version

DetectVersion resolves a bundle's effective spec version: the declared version when present and recognized, Latest otherwise.

func ResolveVersion added in v0.4.1 

func ResolveVersion(declared string) (v Version, known bool)

ResolveVersion maps a declaration to a supported Version. Unknown declarations resolve to Latest with known=false so callers can surface a diagnostic without rejecting the bundle.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.