Documentation
¶
Overview ¶
Package okf implements validation for the Google Open Knowledge Format (OKF) v0.1 — a directory of markdown files with YAML frontmatter.
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.
Validation enforces only the hard conformance rules of the spec (§9):
- Every non-reserved .md file contains a parseable YAML frontmatter block.
- Every such frontmatter block contains a non-empty `type` field.
- 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).
Everything else in the spec (titles, descriptions, links, citations, body section conventions) is soft guidance that consumers MUST tolerate, so it is deliberately not enforced here.
Index ¶
- Constants
- func FormatDiagnostic(d Diagnostic) string
- func IsReserved(p string) bool
- func LocalLinkPath(destination string) (string, bool)
- func ParseFrontmatter(content []byte) (meta map[string]any, body []byte, ok bool, err error)
- func SplitFrontmatter(content []byte) (frontmatter, body []byte, ok bool)
- func Validate(p string, content []byte) error
- type Diagnostic
- type File
- type Link
- type Severity
Constants ¶
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.
Variables ¶
This section is empty.
Functions ¶
func FormatDiagnostic ¶
func FormatDiagnostic(d Diagnostic) string
FormatDiagnostic renders a diagnostic in a grep-friendly compiler format.
func IsReserved ¶
IsReserved reports whether p's basename is an OKF reserved filename (index.md or log.md).
func LocalLinkPath ¶
LocalLinkPath returns the path component of a link that should resolve inside a bundle. External URLs, anchors, and empty destinations return false.
func ParseFrontmatter ¶
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 ¶
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 ¶
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 Diagnostic ¶
type Diagnostic struct {
Path string
Line int
Column int
Severity Severity
Rule string
Message string
}
Diagnostic is one linter-style validation finding.
func ValidateBundle ¶
func ValidateBundle(files []File) []Diagnostic
ValidateBundle checks the mandatory OKF v0.1 conformance rules for every Markdown file in a bundle. It intentionally does not reject broken links: OKF §5.3 requires consumers to tolerate them. OpenLore checks link resolvability separately as an operational requirement.
Source Files